# 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: 27132 $
    00027  * $Author: rjongbloed $
    00028  * $Date: 2012-03-06 17:29:05 -0600 (Tue, 06 Mar 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     ) const;
    00336     bool LoadResource(
    00337       PBYTEArray & data,
    00338       const PString & requiredContentType = PString::Empty()
    00339     ) const;
    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 ///////////////////////////////////////////////////////////////