Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Class Members | File Members

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.30.2.1  2005/02/04 05:19:08  csoutheren
00028  * Backported patches from Atlas-devel
00029  *
00030  * Revision 1.31  2004/12/08 00:51:11  csoutheren
00031  * Move PURLLegacyScheme to header file to allow external usage
00032  *
00033  * Revision 1.30  2004/11/11 07:34:50  csoutheren
00034  * Added #include <ptlib.h>
00035  *
00036  * Revision 1.29  2004/07/07 07:18:43  csoutheren
00037  * Removed warnings on Linux from Windows static global hacks
00038  *
00039  * Revision 1.28  2004/07/06 10:12:51  csoutheren
00040  * Added static integer o factory template to assist in ensuring factories are instantiated
00041  *
00042  * Revision 1.27  2004/06/01 07:32:45  csoutheren
00043  * Removed warning on Linux
00044  *
00045  * Revision 1.26  2004/06/01 07:28:44  csoutheren
00046  * Changed URL parsing to use abstract factory code
00047  *
00048  * Revision 1.25  2004/03/13 06:30:52  rjongbloed
00049  * Virtualised parse function.
00050  *
00051  * Revision 1.24  2003/04/04 05:18:08  robertj
00052  * Added "callto", "tel" and fixed "h323" URL types.
00053  *
00054  * Revision 1.23  2002/12/10 04:40:34  robertj
00055  * Added test function for URL being empty.
00056  *
00057  * Revision 1.22  2002/11/20 00:50:09  robertj
00058  * Fixed correct interpretation of url re double slashes as per latest RFC,
00059  *   including file: mapping and relative paths. Probably still more to do.
00060  *
00061  * Revision 1.21  2002/11/19 10:36:08  robertj
00062  * Added functions to set anf get "file:" URL. as PFilePath and do the right
00063  *   things with platform dependent directory components.
00064  *
00065  * Revision 1.20  2002/11/06 22:47:24  robertj
00066  * Fixed header comment (copyright etc)
00067  *
00068  * Revision 1.19  2002/09/16 01:08:59  robertj
00069  * Added #define so can select if #pragma interface/implementation is used on
00070  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00071  *
00072  * Revision 1.18  2002/03/18 05:01:54  robertj
00073  * Added functions to set component parts of URL.
00074  *
00075  * Revision 1.17  2001/11/08 00:32:49  robertj
00076  * Added parsing of ';' based parameter fields into string dictionary if there are multiple parameters, with '=' values.
00077  *
00078  * Revision 1.16  2001/09/28 00:32:24  robertj
00079  * Broke out internal static function for unstranslating URL strings.
00080  *
00081  * Revision 1.15  1999/03/09 08:01:47  robertj
00082  * Changed comments for doc++ support (more to come).
00083  *
00084  * Revision 1.14  1999/02/16 08:07:10  robertj
00085  * MSVC 6.0 compatibility changes.
00086  *
00087  * Revision 1.13  1998/09/23 06:20:11  robertj
00088  * Added open source copyright license.
00089  *
00090  * Revision 1.12  1998/02/16 00:12:53  robertj
00091  * Added function to open a URL in a browser.
00092  *
00093  * Revision 1.11  1998/02/03 10:02:35  robertj
00094  * Added ability to get scheme, host and port from URL as a string.
00095  *
00096  * Revision 1.10  1998/02/03 06:18:49  robertj
00097  * Fixed URL encoding to be closer to RFC
00098  *
00099  * Revision 1.9  1997/01/12 04:22:54  robertj
00100  * Added has function so URL can be dictionary key.
00101  *
00102  * Revision 1.8  1996/08/19 13:37:28  robertj
00103  * Fixed URL parsing and definition (cannot have relative paths).
00104  *
00105  * Revision 1.7  1996/06/10 09:55:44  robertj
00106  * Added global function for query parameters parsing.
00107  *
00108  * Revision 1.6  1996/03/31 08:53:13  robertj
00109  * Added string representation for URI part only.
00110  *
00111  * Revision 1.5  1996/03/16 04:46:02  robertj
00112  * Added translation type to TranslateString() to accommodate query variables.
00113  *
00114  * Revision 1.4  1996/03/02 03:12:13  robertj
00115  * Added function to translate a string to a form suitable for inclusion in a URL.
00116  *
00117  * Revision 1.3  1996/02/03 11:06:27  robertj
00118  * Added splitting of query field into variables dictionary.
00119  *
00120  * Revision 1.2  1996/01/26 02:24:32  robertj
00121  * Further implemetation.
00122  *
00123  * Revision 1.1  1996/01/23 13:04:20  robertj
00124  * Initial revision
00125  *
00126  */
00127 
00128 #ifndef _PURL
00129 #define _PURL
00130 
00131 #ifdef P_USE_PRAGMA
00132 #pragma interface
00133 #endif
00134 
00135 #include <ptlib.h>
00136 
00137 
00139 // PURL
00140 
00141 class PURLLegacyScheme;
00142 
00148 class PURL : public PObject
00149 {
00150   PCLASSINFO(PURL, PObject)
00151   public:
00153     PURL();
00155     PURL(
00156       const char * cstr,    
00157       const char * defaultScheme = NULL 
00158     );
00160     PURL(
00161       const PString & str,  
00162       const char * defaultScheme = NULL 
00163     );
00165     PURL(
00166       const PFilePath & path   
00167     );
00168 
00177     virtual Comparison Compare(
00178       const PObject & obj   
00179     ) const;
00180 
00192     virtual PINDEX HashFunction() const;
00193 
00196     virtual void PrintOn(
00197       ostream &strm   
00198     ) const;
00199 
00203     virtual void ReadFrom(
00204       istream &strm   
00205     );
00207  
00211     inline BOOL Parse(
00212       const char * cstr,   
00213       const char * defaultScheme = NULL 
00214     ) { return InternalParse(cstr, defaultScheme); }
00216     inline BOOL Parse(
00217       const PString & str, 
00218       const char * defaultScheme = NULL 
00219     ) { return InternalParse((const char *)str, defaultScheme); }
00220 
00222     enum UrlFormat {
00224       FullURL,      
00226       PathOnly,     
00228       URIOnly,      
00230       HostPortOnly  
00231     };
00232 
00239     PString AsString(
00240       UrlFormat fmt = FullURL   
00241     ) const;
00242 
00246     PFilePath AsFilePath() const;
00247 
00249     enum TranslationType {
00251       LoginTranslation,
00253       PathTranslation,
00255       QueryTranslation
00256     };
00257 
00265     static PString TranslateString(
00266       const PString & str,    
00267       TranslationType type    
00268     );
00269 
00277     static PString UntranslateString(
00278       const PString & str,    
00279       TranslationType type    
00280     );
00281 
00283     static void SplitQueryVars(
00284       const PString & queryStr,   
00285       PStringToString & queryVars 
00286     );
00287 
00288 
00290     const PCaselessString & GetScheme() const { return scheme; }
00291 
00293     void SetScheme(const PString & scheme);
00294 
00296     const PString & GetUserName() const { return username; }
00297 
00299     void SetUserName(const PString & username);
00300 
00302     const PString & GetPassword() const { return password; }
00303 
00305     void SetPassword(const PString & password);
00306 
00308     const PCaselessString & GetHostName() const { return hostname; }
00309 
00311     void SetHostName(const PString & hostname);
00312 
00314     WORD GetPort() const { return port; }
00315 
00317     void SetPort(WORD newPort);
00318 
00320     BOOL GetRelativePath() const { return relativePath; }
00321 
00323     const PString & GetPathStr() const { return pathStr; }
00324 
00326     void SetPathStr(const PString & pathStr);
00327 
00329     const PStringArray & GetPath() const { return path; }
00330 
00332     void SetPath(const PStringArray & path);
00333 
00335     PString GetParameters() const;
00336 
00338     void SetParameters(const PString & parameters);
00339 
00341     const PStringToString & GetParamVars() const { return paramVars; }
00342 
00344     void SetParamVars(const PStringToString & paramVars);
00345 
00347     void SetParamVar(const PString & key, const PString & data);
00348 
00350     const PString & GetFragment() const { return fragment; }
00351 
00353     PString GetQuery() const;
00354 
00356     void SetQuery(const PString & query);
00357 
00359     const PStringToString & GetQueryVars() const { return queryVars; }
00360 
00362     void SetQueryVars(const PStringToString & queryVars);
00363 
00365     void SetQueryVar(const PString & key, const PString & data);
00366 
00368     BOOL IsEmpty() const { return urlString.IsEmpty(); }
00369 
00370 
00377     static BOOL OpenBrowser(
00378       const PString & url   
00379     );
00381 
00382     BOOL LegacyParse(const PString & _url, const PURLLegacyScheme * schemeInfo);
00383     PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme * schemeInfo) const;
00384 
00385   protected:
00386     virtual BOOL InternalParse(
00387       const char * cstr,         
00388       const char * defaultScheme 
00389     );
00390     void Recalculate();
00391     PString urlString;
00392 
00393     PCaselessString scheme;
00394     PString username;
00395     PString password;
00396     PCaselessString hostname;
00397     WORD port;
00398     BOOL relativePath;
00399     PString pathStr;
00400     PStringArray path;
00401     PStringToString paramVars;
00402     PString fragment;
00403     PStringToString queryVars;
00404 };
00405 
00406 
00408 // PURLScheme
00409 
00410 class PURLScheme : public PObject
00411 {
00412   PCLASSINFO(PURLScheme, PObject);
00413   public:
00414     virtual PString GetName() const = 0;
00415     virtual BOOL Parse(const PString & url, PURL & purl) const = 0;
00416     virtual PString AsString(PURL::UrlFormat fmt, const PURL & purl) const = 0;
00417 };
00418 
00420 // PURLLegacyScheme
00421 
00422 class PURLLegacyScheme : public PURLScheme
00423 {
00424   public:
00425     PURLLegacyScheme(const char * _scheme)
00426       : scheme(_scheme) { }
00427 
00428     BOOL Parse(const PString & url, PURL & purl) const
00429     { return purl.LegacyParse(url, this); }
00430 
00431     PString AsString(PURL::UrlFormat fmt, const PURL & purl) const
00432     { return purl.LegacyAsString(fmt, this); }
00433 
00434     PString GetName() const     
00435     { return scheme; }
00436 
00437     PString scheme;
00438     BOOL hasUsername;
00439     BOOL hasPassword;
00440     BOOL hasHostPort;
00441     BOOL defaultToUserIfNoAt;
00442     BOOL defaultHostToLocal;
00443     BOOL hasQuery;
00444     BOOL hasParameters;
00445     BOOL hasFragments;
00446     BOOL hasPath;
00447     BOOL relativeImpliesScheme;
00448     WORD defaultPort;
00449 };
00450 
00451 
00452 
00453 #ifdef _WIN32
00454 #  ifndef P_DISABLE_FACTORY_INSTANCES
00455 #    ifndef  P_FACTORY_INSTANCE_PURLScheme
00456 #      define P_FACTORY_INSTANCE_PURLScheme 1
00457 #      pragma message("Including PURLScheme factory loader")
00458        PLOAD_FACTORY(PURLScheme, PString)
00459 #    endif
00460 #  endif
00461 #endif
00462 
00463 #endif
00464 
00465 // End Of File ///////////////////////////////////////////////////////////////

Generated on Tue Mar 15 10:44:52 2005 for PWLib by  doxygen 1.4.0