url.h

Go to the documentation of this file.
00001 /*
00002  * url.h
00003  *
00004  * Universal Resource Locator (for HTTP/HTML) class.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-2002 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Contributor(s): ______________________________________.
00025  *
00026  * $Log: url.h,v $
00027  * Revision 1.34  2005/11/30 12:47:37  csoutheren
00028  * Removed tabs, reformatted some code, and changed tags for Doxygen
00029  *
00030  * Revision 1.33  2005/04/20 05:19:48  csoutheren
00031  * Patch 1185334. Ensure SIP URLs correctly store status of port
00032  * Thanks to Ted Szoczei
00033  *
00034  * Revision 1.32  2005/01/04 07:44:02  csoutheren
00035  * More changes to implement the new configuration methodology, and also to
00036  * attack the global static problem
00037  *
00038  * Revision 1.31  2004/12/08 00:51:11  csoutheren
00039  * Move PURLLegacyScheme to header file to allow external usage
00040  *
00041  * Revision 1.30  2004/11/11 07:34:50  csoutheren
00042  * Added #include <ptlib.h>
00043  *
00044  * Revision 1.29  2004/07/07 07:18:43  csoutheren
00045  * Removed warnings on Linux from Windows static global hacks
00046  *
00047  * Revision 1.28  2004/07/06 10:12:51  csoutheren
00048  * Added static integer o factory template to assist in ensuring factories are instantiated
00049  *
00050  * Revision 1.27  2004/06/01 07:32:45  csoutheren
00051  * Removed warning on Linux
00052  *
00053  * Revision 1.26  2004/06/01 07:28:44  csoutheren
00054  * Changed URL parsing to use abstract factory code
00055  *
00056  * Revision 1.25  2004/03/13 06:30:52  rjongbloed
00057  * Virtualised parse function.
00058  *
00059  * Revision 1.24  2003/04/04 05:18:08  robertj
00060  * Added "callto", "tel" and fixed "h323" URL types.
00061  *
00062  * Revision 1.23  2002/12/10 04:40:34  robertj
00063  * Added test function for URL being empty.
00064  *
00065  * Revision 1.22  2002/11/20 00:50:09  robertj
00066  * Fixed correct interpretation of url re double slashes as per latest RFC,
00067  *   including file: mapping and relative paths. Probably still more to do.
00068  *
00069  * Revision 1.21  2002/11/19 10:36:08  robertj
00070  * Added functions to set anf get "file:" URL. as PFilePath and do the right
00071  *   things with platform dependent directory components.
00072  *
00073  * Revision 1.20  2002/11/06 22:47:24  robertj
00074  * Fixed header comment (copyright etc)
00075  *
00076  * Revision 1.19  2002/09/16 01:08:59  robertj
00077  * Added #define so can select if #pragma interface/implementation is used on
00078  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00079  *
00080  * Revision 1.18  2002/03/18 05:01:54  robertj
00081  * Added functions to set component parts of URL.
00082  *
00083  * Revision 1.17  2001/11/08 00:32:49  robertj
00084  * Added parsing of ';' based parameter fields into string dictionary if there are multiple parameters, with '=' values.
00085  *
00086  * Revision 1.16  2001/09/28 00:32:24  robertj
00087  * Broke out internal static function for unstranslating URL strings.
00088  *
00089  * Revision 1.15  1999/03/09 08:01:47  robertj
00090  * Changed comments for doc++ support (more to come).
00091  *
00092  * Revision 1.14  1999/02/16 08:07:10  robertj
00093  * MSVC 6.0 compatibility changes.
00094  *
00095  * Revision 1.13  1998/09/23 06:20:11  robertj
00096  * Added open source copyright license.
00097  *
00098  * Revision 1.12  1998/02/16 00:12:53  robertj
00099  * Added function to open a URL in a browser.
00100  *
00101  * Revision 1.11  1998/02/03 10:02:35  robertj
00102  * Added ability to get scheme, host and port from URL as a string.
00103  *
00104  * Revision 1.10  1998/02/03 06:18:49  robertj
00105  * Fixed URL encoding to be closer to RFC
00106  *
00107  * Revision 1.9  1997/01/12 04:22:54  robertj
00108  * Added has function so URL can be dictionary key.
00109  *
00110  * Revision 1.8  1996/08/19 13:37:28  robertj
00111  * Fixed URL parsing and definition (cannot have relative paths).
00112  *
00113  * Revision 1.7  1996/06/10 09:55:44  robertj
00114  * Added global function for query parameters parsing.
00115  *
00116  * Revision 1.6  1996/03/31 08:53:13  robertj
00117  * Added string representation for URI part only.
00118  *
00119  * Revision 1.5  1996/03/16 04:46:02  robertj
00120  * Added translation type to TranslateString() to accommodate query variables.
00121  *
00122  * Revision 1.4  1996/03/02 03:12:13  robertj
00123  * Added function to translate a string to a form suitable for inclusion in a URL.
00124  *
00125  * Revision 1.3  1996/02/03 11:06:27  robertj
00126  * Added splitting of query field into variables dictionary.
00127  *
00128  * Revision 1.2  1996/01/26 02:24:32  robertj
00129  * Further implemetation.
00130  *
00131  * Revision 1.1  1996/01/23 13:04:20  robertj
00132  * Initial revision
00133  *
00134  */
00135 
00136 #ifndef _PURL
00137 #define _PURL
00138 
00139 #ifdef P_USE_PRAGMA
00140 #pragma interface
00141 #endif
00142 
00143 #include <ptlib.h>
00144 
00145 
00147 // PURL
00148 
00149 class PURLLegacyScheme;
00150 
00156 class PURL : public PObject
00157 {
00158   PCLASSINFO(PURL, PObject)
00159   public:
00161     PURL();
00163     PURL(
00164       const char * cstr,    
00165       const char * defaultScheme = NULL 
00166     );
00168     PURL(
00169       const PString & str,  
00170       const char * defaultScheme = NULL 
00171     );
00173     PURL(
00174       const PFilePath & path   
00175     );
00176 
00185     virtual Comparison Compare(
00186       const PObject & obj   
00187     ) const;
00188 
00200     virtual PINDEX HashFunction() const;
00201 
00204     virtual void PrintOn(
00205       ostream &strm   
00206     ) const;
00207 
00211     virtual void ReadFrom(
00212       istream &strm   
00213     );
00215  
00219     inline BOOL Parse(
00220       const char * cstr,   
00221       const char * defaultScheme = NULL 
00222     ) { return InternalParse(cstr, defaultScheme); }
00224     inline BOOL Parse(
00225       const PString & str, 
00226       const char * defaultScheme = NULL 
00227     ) { return InternalParse((const char *)str, defaultScheme); }
00228 
00230     enum UrlFormat {
00232       FullURL,      
00234       PathOnly,     
00236       URIOnly,      
00238       HostPortOnly  
00239     };
00240 
00247     PString AsString(
00248       UrlFormat fmt = FullURL   
00249     ) const;
00250 
00254     PFilePath AsFilePath() const;
00255 
00257     enum TranslationType {
00259       LoginTranslation,
00261       PathTranslation,
00263       QueryTranslation
00264     };
00265 
00273     static PString TranslateString(
00274       const PString & str,    
00275       TranslationType type    
00276     );
00277 
00285     static PString UntranslateString(
00286       const PString & str,    
00287       TranslationType type    
00288     );
00289 
00291     static void SplitQueryVars(
00292       const PString & queryStr,   
00293       PStringToString & queryVars 
00294     );
00295 
00296 
00298     const PCaselessString & GetScheme() const { return scheme; }
00299 
00301     void SetScheme(const PString & scheme);
00302 
00304     const PString & GetUserName() const { return username; }
00305 
00307     void SetUserName(const PString & username);
00308 
00310     const PString & GetPassword() const { return password; }
00311 
00313     void SetPassword(const PString & password);
00314 
00316     const PCaselessString & GetHostName() const { return hostname; }
00317 
00319     void SetHostName(const PString & hostname);
00320 
00322     WORD GetPort() const { return port; }
00323 
00325     void SetPort(WORD newPort);
00326 
00328     BOOL GetRelativePath() const { return relativePath; }
00329 
00331     const PString & GetPathStr() const { return pathStr; }
00332 
00334     void SetPathStr(const PString & pathStr);
00335 
00337     const PStringArray & GetPath() const { return path; }
00338 
00340     void SetPath(const PStringArray & path);
00341 
00343     PString GetParameters() const;
00344 
00346     void SetParameters(const PString & parameters);
00347 
00349     const PStringToString & GetParamVars() const { return paramVars; }
00350 
00352     void SetParamVars(const PStringToString & paramVars);
00353 
00355     void SetParamVar(const PString & key, const PString & data);
00356 
00358     const PString & GetFragment() const { return fragment; }
00359 
00361     PString GetQuery() const;
00362 
00364     void SetQuery(const PString & query);
00365 
00367     const PStringToString & GetQueryVars() const { return queryVars; }
00368 
00370     void SetQueryVars(const PStringToString & queryVars);
00371 
00373     void SetQueryVar(const PString & key, const PString & data);
00374 
00376     BOOL IsEmpty() const { return urlString.IsEmpty(); }
00377 
00378 
00385     static BOOL OpenBrowser(
00386       const PString & url   
00387     );
00389 
00390     BOOL LegacyParse(const PString & _url, const PURLLegacyScheme * schemeInfo);
00391     PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme * schemeInfo) const;
00392 
00393   protected:
00394     virtual BOOL InternalParse(
00395       const char * cstr,         
00396       const char * defaultScheme 
00397     );
00398     void Recalculate();
00399     PString urlString;
00400 
00401     PCaselessString scheme;
00402     PString username;
00403     PString password;
00404     PCaselessString hostname;
00405     WORD port;
00406     BOOL portSupplied;          
00407     BOOL relativePath;
00408     PString pathStr;
00409     PStringArray path;
00410     PStringToString paramVars;
00411     PString fragment;
00412     PStringToString queryVars;
00413 };
00414 
00415 
00417 // PURLScheme
00418 
00419 class PURLScheme : public PObject
00420 {
00421   PCLASSINFO(PURLScheme, PObject);
00422   public:
00423     virtual PString GetName() const = 0;
00424     virtual BOOL Parse(const PString & url, PURL & purl) const = 0;
00425     virtual PString AsString(PURL::UrlFormat fmt, const PURL & purl) const = 0;
00426 };
00427 
00429 // PURLLegacyScheme
00430 
00431 class PURLLegacyScheme : public PURLScheme
00432 {
00433   public:
00434     PURLLegacyScheme(const char * _scheme)
00435       : scheme(_scheme) { }
00436 
00437     BOOL Parse(const PString & url, PURL & purl) const
00438     { return purl.LegacyParse(url, this); }
00439 
00440     PString AsString(PURL::UrlFormat fmt, const PURL & purl) const
00441     { return purl.LegacyAsString(fmt, this); }
00442 
00443     PString GetName() const     
00444     { return scheme; }
00445 
00446     PString scheme;
00447     BOOL hasUsername;
00448     BOOL hasPassword;
00449     BOOL hasHostPort;
00450     BOOL defaultToUserIfNoAt;
00451     BOOL defaultHostToLocal;
00452     BOOL hasQuery;
00453     BOOL hasParameters;
00454     BOOL hasFragments;
00455     BOOL hasPath;
00456     BOOL relativeImpliesScheme;
00457     WORD defaultPort;
00458 };
00459 
00460 #endif
00461 
00462 // End Of File ///////////////////////////////////////////////////////////////

Generated on Fri Sep 21 14:40:11 2007 for PWLib by  doxygen 1.5.3