PTLib  Version 2.10.4
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  * $Revision: 26847 $
00027  * $Author: rjongbloed $
00028  * $Date: 2012-01-08 03:33:29 -0600 (Sun, 08 Jan 2012) $
00029  */
00030 
00031 #ifndef PTLIB_PURL_H
00032 #define PTLIB_PURL_H
00033 
00034 #ifdef P_USE_PRAGMA
00035 #pragma interface
00036 #endif
00037 
00038 
00039 #if P_URL
00040 
00041 #include <ptlib/pfactory.h>
00042 
00043 
00045 // PURL
00046 
00047 class PURLLegacyScheme;
00048 
00054 class PURL : public PObject
00055 {
00056   PCLASSINFO(PURL, PObject)
00057   public:
00059     PURL();
00061     PURL(
00062       const char * cstr,    
00063       const char * defaultScheme = "http" 
00064     );
00066     PURL(
00067       const PString & str,  
00068       const char * defaultScheme = "http" 
00069     );
00071     PURL(
00072       const PFilePath & path   
00073     );
00074 
00075     PURL(const PURL & other);
00076     PURL & operator=(const PURL & other);
00077 
00086     virtual Comparison Compare(
00087       const PObject & obj   
00088     ) const;
00089 
00101     virtual PINDEX HashFunction() const;
00102 
00105     virtual void PrintOn(
00106       ostream &strm   
00107     ) const;
00108 
00112     virtual void ReadFrom(
00113       istream &strm   
00114     );
00116  
00120     inline PBoolean Parse(
00121       const char * cstr,   
00122       const char * defaultScheme = NULL 
00123     ) { return InternalParse(cstr, defaultScheme); }
00125     inline PBoolean Parse(
00126       const PString & str, 
00127       const char * defaultScheme = NULL 
00128     ) { return InternalParse((const char *)str, defaultScheme); }
00129 
00131     enum UrlFormat {
00133       FullURL,      
00135       PathOnly,     
00137       URIOnly,      
00139       HostPortOnly  
00140     };
00141 
00148     PString AsString(
00149       UrlFormat fmt = FullURL   
00150     ) const;
00151     operator PString() const { return AsString(); }
00152 
00156     PFilePath AsFilePath() const;
00157 
00159     enum TranslationType {
00161       LoginTranslation,
00163       PathTranslation,
00165       QueryTranslation,
00167       ParameterTranslation,
00169       QuotedParameterTranslation
00170     };
00171 
00179     static PString TranslateString(
00180       const PString & str,    
00181       TranslationType type    
00182     );
00183 
00191     static PString UntranslateString(
00192       const PString & str,    
00193       TranslationType type    
00194     );
00195 
00197     static void SplitVars(
00198       const PString & str,    
00199       PStringToString & vars, 
00200       char sep1 = ';',        
00201       char sep2 = '=',        
00202       TranslationType type = ParameterTranslation 
00203     );
00204 
00206     static void SplitQueryVars(
00207       const PString & queryStr,   
00208       PStringToString & queryVars 
00209     ) { SplitVars(queryStr, queryVars, '&', '=', QueryTranslation); }
00210 
00213     static void OutputVars(
00214       ostream & strm,               
00215       const PStringToString & vars, 
00216       char sep0 = ';',              
00217       char sep1 = ';',              
00218       char sep2 = '=',              
00219       TranslationType type = ParameterTranslation 
00220     );
00221 
00222 
00224     const PCaselessString & GetScheme() const { return scheme; }
00225 
00227     void SetScheme(const PString & scheme);
00228 
00230     const PString & GetUserName() const { return username; }
00231 
00233     void SetUserName(const PString & username);
00234 
00236     const PString & GetPassword() const { return password; }
00237 
00239     void SetPassword(const PString & password);
00240 
00242     const PCaselessString & GetHostName() const { return hostname; }
00243 
00245     void SetHostName(const PString & hostname);
00246 
00248     WORD GetPort() const { return port; }
00249 
00251     void SetPort(WORD newPort);
00252     
00254     PBoolean GetPortSupplied() const { return portSupplied; }
00255 
00257     PBoolean GetRelativePath() const { return relativePath; }
00258 
00260     PString GetPathStr() const;
00261 
00263     void SetPathStr(const PString & pathStr);
00264 
00266     const PStringArray & GetPath() const { return path; }
00267 
00269     void SetPath(const PStringArray & path);
00270 
00272     void AppendPath(const PString & segment);
00273 
00275     PString GetParameters() const;
00276 
00278     void SetParameters(const PString & parameters);
00279 
00282     const PStringOptions & GetParamVars() const { return paramVars; }
00283 
00286     void SetParamVars(const PStringToString & paramVars);
00287 
00290     void SetParamVar(
00291       const PString & key,          
00292       const PString & data,         
00293       bool emptyDataDeletes = true  
00294     );
00295 
00297     const PString & GetFragment() const { return fragment; }
00298 
00300     PString GetQuery() const;
00301 
00304     void SetQuery(const PString & query);
00305 
00308     const PStringOptions & GetQueryVars() const { return queryVars; }
00309 
00312     void SetQueryVars(const PStringToString & queryVars);
00313 
00316     void SetQueryVar(const PString & key, const PString & data);
00317 
00319     const PString & GetContents() const { return m_contents; }
00320 
00322     void SetContents(const PString & str);
00323 
00325     PBoolean IsEmpty() const { return urlString.IsEmpty(); }
00326 
00327 
00332     bool LoadResource(
00333       PString & data,  
00334       const PString & requiredContentType = PString::Empty() 
00335     );
00336     bool LoadResource(
00337       PBYTEArray & data,  
00338       const PString & requiredContentType = PString::Empty() 
00339     );
00340 
00347     bool OpenBrowser() const { return OpenBrowser(AsString()); }
00348     static bool OpenBrowser(
00349       const PString & url   
00350     );
00352 
00353     PBoolean LegacyParse(const PString & url, const PURLLegacyScheme * schemeInfo);
00354     PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme * schemeInfo) const;
00355 
00356   protected:
00357     void CopyContents(const PURL & other);
00358     virtual PBoolean InternalParse(
00359       const char * cstr,         
00360       const char * defaultScheme 
00361     );
00362     void Recalculate();
00363     PString urlString;
00364 
00365     PCaselessString scheme;
00366     PString username;
00367     PString password;
00368     PCaselessString hostname;
00369     WORD port;
00370     PBoolean portSupplied;          
00371     PBoolean relativePath;
00372     PStringArray path;
00373     PStringOptions paramVars;
00374     PString fragment;
00375     PStringOptions queryVars;
00376     PString m_contents;  // Anything left after parsing other elements
00377 };
00378 
00379 
00381 // PURLScheme
00382 
00383 class PURLScheme : public PObject
00384 {
00385   PCLASSINFO(PURLScheme, PObject);
00386   public:
00387     virtual PString GetName() const = 0;
00388     virtual PBoolean Parse(const PString & url, PURL & purl) const = 0;
00389     virtual PString AsString(PURL::UrlFormat fmt, const PURL & purl) const = 0;
00390 };
00391 
00392 typedef PFactory<PURLScheme> PURLSchemeFactory;
00393 
00394 
00396 // PURLLegacyScheme
00397 
00398 class PURLLegacyScheme : public PURLScheme
00399 {
00400   public:
00401     PURLLegacyScheme(
00402       const char * s,
00403       bool user    = false,
00404       bool pass    = false,
00405       bool host    = false,
00406       bool def     = false,
00407       bool defhost = false,
00408       bool query   = false,
00409       bool params  = false,
00410       bool frags   = false,
00411       bool path    = false,
00412       bool rel     = false,
00413       WORD port    = 0
00414     )
00415       : scheme(s)
00416       , hasUsername           (user)
00417       , hasPassword           (pass)
00418       , hasHostPort           (host)
00419       , defaultToUserIfNoAt   (def)
00420       , defaultHostToLocal    (defhost)
00421       , hasQuery              (query)
00422       , hasParameters         (params)
00423       , hasFragments          (frags)
00424       , hasPath               (path)
00425       , relativeImpliesScheme (rel)
00426       , defaultPort           (port)
00427     { }
00428 
00429     PBoolean Parse(const PString & url, PURL & purl) const
00430     { return purl.LegacyParse(url, this); }
00431 
00432     PString AsString(PURL::UrlFormat fmt, const PURL & purl) const
00433     { return purl.LegacyAsString(fmt, this); }
00434 
00435     PString GetName() const     
00436     { return scheme; }
00437 
00438     PString scheme;
00439     bool hasUsername;
00440     bool hasPassword;
00441     bool hasHostPort;
00442     bool defaultToUserIfNoAt;
00443     bool defaultHostToLocal;
00444     bool hasQuery;
00445     bool hasParameters;
00446     bool hasFragments;
00447     bool hasPath;
00448     bool relativeImpliesScheme;
00449     WORD defaultPort;
00450 };
00451 
00452 #define PURL_LEGACY_SCHEME(schemeName, user, pass, host, def, defhost, query, params, frags, path, rel, port) \
00453   class PURLLegacyScheme_##schemeName : public PURLLegacyScheme \
00454   { \
00455     public: \
00456       PURLLegacyScheme_##schemeName() \
00457         : PURLLegacyScheme(#schemeName, user, pass, host, def, defhost, query, params, frags, path, rel, port) \
00458         { } \
00459   }; \
00460   static PURLSchemeFactory::Worker<PURLLegacyScheme_##schemeName> schemeName##Factory(#schemeName, true); \
00461 
00462 
00463 
00465 // PURLLoader
00466 
00467 class PURLLoader : public PObject
00468 {
00469   PCLASSINFO(PURLLoader, PObject);
00470   public:
00471     virtual bool Load(const PURL & url, PString & str, const PString & requiredContentType) = 0;
00472     virtual bool Load(const PURL & url, PBYTEArray & data, const PString & requiredContentType) = 0;
00473 };
00474 
00475 typedef PFactory<PURLLoader> PURLLoaderFactory;
00476 
00477 
00478 #endif // P_URL
00479 
00480 #endif // PTLIB_PURL_H
00481 
00482 
00483 // End Of File ///////////////////////////////////////////////////////////////
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines