url.h
Go to the documentation of this file.
/*
* url.h
*
* Universal Resource Locator (for HTTP/HTML) class.
*
* Portable Windows Library
*
* Copyright (c) 1993-2002 Equivalence Pty. Ltd.
*
* The contents of this file are subject to the Mozilla Public License
* Version 1.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
* the License for the specific language governing rights and limitations
* under the License.
*
* The Original Code is Portable Windows Library.
*
* The Initial Developer of the Original Code is Equivalence Pty. Ltd.
*
* Contributor(s): ______________________________________.
*
* $Revision: 27132 $
* $Author: rjongbloed $
* $Date: 2012-03-06 17:29:05 -0600 (Tue, 06 Mar 2012) $
*/
#ifndef PTLIB_PURL_H
#define PTLIB_PURL_H
#ifdef P_USE_PRAGMA
#pragma interface
#endif
#if P_URL
#include <ptlib/pfactory.h>
// PURL
class PURLLegacyScheme;
class PURL : public PObject
{
PCLASSINFO(PURL, PObject)
public:
PURL();
PURL(
const char * cstr,
const char * defaultScheme = "http"
);
PURL(
const PString & str,
const char * defaultScheme = "http"
);
PURL(
const PFilePath & path
);
PURL(const PURL & other);
PURL & operator=(const PURL & other);
virtual Comparison Compare(
const PObject & obj
) const;
virtual PINDEX HashFunction() const;
virtual void PrintOn(
ostream &strm
) const;
virtual void ReadFrom(
istream &strm
);
inline PBoolean Parse(
const char * cstr,
const char * defaultScheme = NULL
) { return InternalParse(cstr, defaultScheme); }
inline PBoolean Parse(
const PString & str,
const char * defaultScheme = NULL
) { return InternalParse((const char *)str, defaultScheme); }
enum UrlFormat {
FullURL,
PathOnly,
URIOnly,
HostPortOnly
};
PString AsString(
UrlFormat fmt = FullURL
) const;
operator PString() const { return AsString(); }
PFilePath AsFilePath() const;
enum TranslationType {
LoginTranslation,
PathTranslation,
QueryTranslation,
ParameterTranslation,
QuotedParameterTranslation
};
static PString TranslateString(
const PString & str,
TranslationType type
);
static PString UntranslateString(
const PString & str,
TranslationType type
);
static void SplitVars(
const PString & str,
PStringToString & vars,
char sep1 = ';',
char sep2 = '=',
TranslationType type = ParameterTranslation
);
static void SplitQueryVars(
const PString & queryStr,
PStringToString & queryVars
) { SplitVars(queryStr, queryVars, '&', '=', QueryTranslation); }
static void OutputVars(
ostream & strm,
const PStringToString & vars,
char sep0 = ';',
char sep1 = ';',
char sep2 = '=',
TranslationType type = ParameterTranslation
);
const PCaselessString & GetScheme() const { return scheme; }
void SetScheme(const PString & scheme);
const PString & GetUserName() const { return username; }
void SetUserName(const PString & username);
const PString & GetPassword() const { return password; }
void SetPassword(const PString & password);
const PCaselessString & GetHostName() const { return hostname; }
void SetHostName(const PString & hostname);
WORD GetPort() const { return port; }
void SetPort(WORD newPort);
PBoolean GetPortSupplied() const { return portSupplied; }
PBoolean GetRelativePath() const { return relativePath; }
PString GetPathStr() const;
void SetPathStr(const PString & pathStr);
const PStringArray & GetPath() const { return path; }
void SetPath(const PStringArray & path);
void AppendPath(const PString & segment);
PString GetParameters() const;
void SetParameters(const PString & parameters);
const PStringOptions & GetParamVars() const { return paramVars; }
void SetParamVars(const PStringToString & paramVars);
void SetParamVar(
const PString & key,
const PString & data,
bool emptyDataDeletes = true
);
const PString & GetFragment() const { return fragment; }
PString GetQuery() const;
void SetQuery(const PString & query);
const PStringOptions & GetQueryVars() const { return queryVars; }
void SetQueryVars(const PStringToString & queryVars);
void SetQueryVar(const PString & key, const PString & data);
const PString & GetContents() const { return m_contents; }
void SetContents(const PString & str);
PBoolean IsEmpty() const { return urlString.IsEmpty(); }
bool LoadResource(
PString & data,
const PString & requiredContentType = PString::Empty()
) const;
bool LoadResource(
PBYTEArray & data,
const PString & requiredContentType = PString::Empty()
) const;
bool OpenBrowser() const { return OpenBrowser(AsString()); }
static bool OpenBrowser(
const PString & url
);
PBoolean LegacyParse(const PString & url, const PURLLegacyScheme * schemeInfo);
PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme * schemeInfo) const;
protected:
void CopyContents(const PURL & other);
virtual PBoolean InternalParse(
const char * cstr,
const char * defaultScheme
);
void Recalculate();
PString urlString;
PCaselessString scheme;
PString username;
PString password;
PCaselessString hostname;
WORD port;
PBoolean portSupplied;
PBoolean relativePath;
PStringArray path;
PStringOptions paramVars;
PString fragment;
PStringOptions queryVars;
PString m_contents; // Anything left after parsing other elements
};
// PURLScheme
class PURLScheme : public PObject
{
PCLASSINFO(PURLScheme, PObject);
public:
virtual PString GetName() const = 0;
virtual PBoolean Parse(const PString & url, PURL & purl) const = 0;
virtual PString AsString(PURL::UrlFormat fmt, const PURL & purl) const = 0;
};
typedef PFactory<PURLScheme> PURLSchemeFactory;
// PURLLegacyScheme
class PURLLegacyScheme : public PURLScheme
{
public:
PURLLegacyScheme(
const char * s,
bool user = false,
bool pass = false,
bool host = false,
bool def = false,
bool defhost = false,
bool query = false,
bool params = false,
bool frags = false,
bool path = false,
bool rel = false,
WORD port = 0
)
: scheme(s)
, hasUsername (user)
, hasPassword (pass)
, hasHostPort (host)
, defaultToUserIfNoAt (def)
, defaultHostToLocal (defhost)
, hasQuery (query)
, hasParameters (params)
, hasFragments (frags)
, hasPath (path)
, relativeImpliesScheme (rel)
, defaultPort (port)
{ }
PBoolean Parse(const PString & url, PURL & purl) const
{ return purl.LegacyParse(url, this); }
PString AsString(PURL::UrlFormat fmt, const PURL & purl) const
{ return purl.LegacyAsString(fmt, this); }
PString GetName() const
{ return scheme; }
PString scheme;
bool hasUsername;
bool hasPassword;
bool hasHostPort;
bool defaultToUserIfNoAt;
bool defaultHostToLocal;
bool hasQuery;
bool hasParameters;
bool hasFragments;
bool hasPath;
bool relativeImpliesScheme;
WORD defaultPort;
};
#define PURL_LEGACY_SCHEME(schemeName, user, pass, host, def, defhost, query, params, frags, path, rel, port) \
class PURLLegacyScheme_##schemeName : public PURLLegacyScheme \
{ \
public: \
PURLLegacyScheme_##schemeName() \
: PURLLegacyScheme(#schemeName, user, pass, host, def, defhost, query, params, frags, path, rel, port) \
{ } \
}; \
static PURLSchemeFactory::Worker<PURLLegacyScheme_##schemeName> schemeName##Factory(#schemeName, true); \
// PURLLoader
class PURLLoader : public PObject
{
PCLASSINFO(PURLLoader, PObject);
public:
virtual bool Load(const PURL & url, PString & str, const PString & requiredContentType) = 0;
virtual bool Load(const PURL & url, PBYTEArray & data, const PString & requiredContentType) = 0;
};
typedef PFactory<PURLLoader> PURLLoaderFactory;
#endif // P_URL
#endif // PTLIB_PURL_H
// End Of File ///////////////////////////////////////////////////////////////
PURL::PathTranslation
Translate the path field for a URL.
Definition: url.h:163
PURL::InternalParse
virtual PBoolean InternalParse(const char *cstr, const char *defaultScheme)
PURL::ReadFrom
virtual void ReadFrom(istream &strm)
Input the contents of the URL from the stream.
PURLLegacyScheme::defaultToUserIfNoAt
bool defaultToUserIfNoAt
Definition: url.h:442
PURL::paramVars
PStringOptions paramVars
Definition: url.h:373
PURL::SplitQueryVars
static void SplitQueryVars(const PString &queryStr, PStringToString &queryVars)
Split a string in &= form to a dictionary of names and values.
Definition: url.h:206
PString::IsEmpty
virtual PBoolean IsEmpty() const
Determine if the string is empty.
PURLLoaderFactory
PFactory< PURLLoader > PURLLoaderFactory
Definition: url.h:475
PURL::LegacyParse
PBoolean LegacyParse(const PString &url, const PURLLegacyScheme *schemeInfo)
PURL::SetPathStr
void SetPathStr(const PString &pathStr)
Set the path field of the URL as a string.
PURLLegacyScheme
Definition: url.h:398
PURL::FullURL
Translate to a string as a full URL.
Definition: url.h:133
PCLASSINFO
#define PCLASSINFO(cls, par)
Declare all the standard PTLib class information.
Definition: object.h:1049
PURLLegacyScheme::PURLLegacyScheme
PURLLegacyScheme(const char *s, bool user=false, bool pass=false, bool host=false, bool def=false, bool defhost=false, bool query=false, bool params=false, bool frags=false, bool path=false, bool rel=false, WORD port=0)
Definition: url.h:401
PURL::m_contents
PString m_contents
Definition: url.h:376
PURLLegacyScheme::hasQuery
bool hasQuery
Definition: url.h:444
PURLLegacyScheme::hasUsername
bool hasUsername
Definition: url.h:439
PURL::HashFunction
virtual PINDEX HashFunction() const
This function yields a hash value required by the PDictionary class.
PURL::GetQueryVars
const PStringOptions & GetQueryVars() const
Get the Query (?) field of the URL as a string dictionary.
Definition: url.h:308
pfactory.h
PURL::SetHostName
void SetHostName(const PString &hostname)
Set the hostname field of the URL.
PURLLegacyScheme::scheme
PString scheme
Definition: url.h:438
PURL::operator=
PURL & operator=(const PURL &other)
PURL::TranslationType
TranslationType
Type for translation of strings to URL format,.
Definition: url.h:159
PURL::Parse
PBoolean Parse(const char *cstr, const char *defaultScheme=NULL)
Parse the URL string into the fields in the object instance.
Definition: url.h:120
PURL::username
PString username
Definition: url.h:366
PURLLegacyScheme::hasHostPort
bool hasHostPort
Definition: url.h:441
PURL::ParameterTranslation
Translate the parameter variables field for a URL.
Definition: url.h:167
PURL::Recalculate
void Recalculate()
PStringToString
This is a dictionary collection class of PString objects, keyed by another string.
Definition: pstring.h:2784
PFilePath
This class describes a full description for a file on the particular platform.
Definition: filepath.h:65
PURL::SetUserName
void SetUserName(const PString &username)
Set the username field of the URL.
PURL::Compare
virtual Comparison Compare(const PObject &obj) const
Compare the two URLs and return their relative rank.
PObject::Comparison
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
PURL::fragment
PString fragment
Definition: url.h:374
PURL::OutputVars
static void OutputVars(ostream &strm, const PStringToString &vars, char sep0=';', char sep1=';', char sep2='=', TranslationType type=ParameterTranslation)
Construct string from a dictionary using separators.
PURLLegacyScheme::Parse
PBoolean Parse(const PString &url, PURL &purl) const
Definition: url.h:429
PCaselessString
This class is a variation of a string that ignores case.
Definition: pstring.h:1708
PURL::SetParamVars
void SetParamVars(const PStringToString &paramVars)
Set the parameter (;) field(s) of the URL as a string dictionary.
PURL::Parse
PBoolean Parse(const PString &str, const char *defaultScheme=NULL)
Parse the URL string into the fields in the object instance.
Definition: url.h:125
PURL::AppendPath
void AppendPath(const PString &segment)
Append segment to the path field of the URL.
PURL::GetParamVars
const PStringOptions & GetParamVars() const
Get the parameter (;) field(s) of the URL as a string dictionary.
Definition: url.h:282
PStringArray
This is an array collection class of PString objects.
Definition: pstring.h:2024
PURL::SetContents
void SetContents(const PString &str)
Set the contents of URL, data left after all elemetns are parsed out.
PURL::LoadResource
bool LoadResource(PString &data, const PString &requiredContentType=PString::Empty()) const
Get the resource the URL is pointing at.
PURL::GetFragment
const PString & GetFragment() const
Get the fragment (#) field of the URL.
Definition: url.h:297
PURL::GetRelativePath
PBoolean GetRelativePath() const
Get if path is relative or absolute.
Definition: url.h:257
PURL::QuotedParameterTranslation
Translate the quoted parameter variables field for a URL.
Definition: url.h:169
PURL::GetParameters
PString GetParameters() const
Get the parameter (;) field of the URL.
PURL::password
PString password
Definition: url.h:367
PURLLegacyScheme::GetName
PString GetName() const
Definition: url.h:435
PURL::QueryTranslation
Translate the query variable field for a URL.
Definition: url.h:165
PURL::SetQueryVar
void SetQueryVar(const PString &key, const PString &data)
Set the Query (?) field of the URL as a string dictionary.
PURL::IsEmpty
PBoolean IsEmpty() const
Return true if the URL is an empty string.
Definition: url.h:325
PURL::GetPortSupplied
PBoolean GetPortSupplied() const
Get if explicit port is specified.
Definition: url.h:254
PURL::UntranslateString
static PString UntranslateString(const PString &str, TranslationType type)
Untranslate a string from a form that was included into a URL into a normal string.
PURL::PURL
PURL()
Construct a new URL object from the URL string.
PURL::SetPath
void SetPath(const PStringArray &path)
Set the path field of the URL as a string array.
PBoolean
BOOL PBoolean
Definition: object.h:102
PURL::GetUserName
const PString & GetUserName() const
Get the username field of the URL.
Definition: url.h:230
PURL::HostPortOnly
Translate to a string with scheme and host/port.
Definition: url.h:139
PBYTEArray
Array of unsigned characters.
Definition: array.h:670
PURL::GetHostName
const PCaselessString & GetHostName() const
Get the hostname field of the URL.
Definition: url.h:242
PStringOptions
Specialised version of PStringToString to contain a dictionary of options/attributes.
Definition: pstring.h:2845
PURL::SplitVars
static void SplitVars(const PString &str, PStringToString &vars, char sep1=';', char sep2='=', TranslationType type=ParameterTranslation)
Split a string to a dictionary of names and values.
PURLLegacyScheme::hasParameters
bool hasParameters
Definition: url.h:445
PURLLoader
Definition: url.h:467
PURL::SetScheme
void SetScheme(const PString &scheme)
Set the scheme field of the URL.
PURL::SetPort
void SetPort(WORD newPort)
Set the port field in the URL.
PURL::PathOnly
Translate to a string as only path.
Definition: url.h:135
PURL::TranslateString
static PString TranslateString(const PString &str, TranslationType type)
Translate a string from general form to one that can be included into a URL.
PURL::AsFilePath
PFilePath AsFilePath() const
Get the "file:" URL as a file path.
PURLSchemeFactory
PFactory< PURLScheme > PURLSchemeFactory
Definition: url.h:392
PURL::SetQuery
void SetQuery(const PString &query)
Set the Query (?) field of the URL as a string.
PURL::scheme
PCaselessString scheme
Definition: url.h:365
PURL::OpenBrowser
bool OpenBrowser() const
Open the URL in a browser.
Definition: url.h:347
PURL::GetContents
const PString & GetContents() const
Get the contents of URL, data left after all elemetns are parsed out.
Definition: url.h:319
PURL::portSupplied
PBoolean portSupplied
Definition: url.h:370
PURL::GetPort
WORD GetPort() const
Get the port field of the URL.
Definition: url.h:248
PURL::urlString
PString urlString
Definition: url.h:363
PString
The character string class.
Definition: pstring.h:108
PURL::hostname
PCaselessString hostname
Definition: url.h:368
PString::Empty
static PString Empty()
Return an empty string.
PURLLegacyScheme::AsString
PString AsString(PURL::UrlFormat fmt, const PURL &purl) const
Definition: url.h:432
PURLLegacyScheme::hasPassword
bool hasPassword
Definition: url.h:440
PURLScheme
Definition: url.h:383
PURL::GetScheme
const PCaselessString & GetScheme() const
Get the scheme field of the URL.
Definition: url.h:224
PURL::UrlFormat
UrlFormat
Print/String output representation formats.
Definition: url.h:131
PFactory
Template class for generic factories of an abstract class.
Definition: pfactory.h:144
PURL::SetParamVar
void SetParamVar(const PString &key, const PString &data, bool emptyDataDeletes=true)
Set the parameter (;) field of the URL as a string dictionary.
PURL::GetQuery
PString GetQuery() const
Get the Query (?) field of the URL as a string.
PURL::queryVars
PStringOptions queryVars
Definition: url.h:375
PURL::LoginTranslation
Translate a username/password field for a URL.
Definition: url.h:161
PURLLegacyScheme::hasFragments
bool hasFragments
Definition: url.h:446
PURL::PrintOn
virtual void PrintOn(ostream &strm) const
Output the contents of the URL to the stream as a string.
PURLLegacyScheme::hasPath
bool hasPath
Definition: url.h:447
PURLLegacyScheme::defaultHostToLocal
bool defaultHostToLocal
Definition: url.h:443
PURL::GetPathStr
PString GetPathStr() const
Get the path field of the URL as a string.
PURL::SetPassword
void SetPassword(const PString &password)
Set the password field of the URL.
PURL::GetPassword
const PString & GetPassword() const
Get the password field of the URL.
Definition: url.h:236
PURL::relativePath
PBoolean relativePath
port was supplied in string input
Definition: url.h:371
PURLLegacyScheme::defaultPort
WORD defaultPort
Definition: url.h:449
PURL::SetParameters
void SetParameters(const PString &parameters)
Set the parameter (;) field of the URL.
PURLLegacyScheme::relativeImpliesScheme
bool relativeImpliesScheme
Definition: url.h:448
PURL::GetPath
const PStringArray & GetPath() const
Get the path field of the URL as a string array.
Definition: url.h:266
PObject
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
PURL::LegacyAsString
PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme *schemeInfo) const
PURL
This class describes a Universal Resource Locator.
Definition: url.h:54
PURL::AsString
PString AsString(UrlFormat fmt=FullURL) const
Convert the URL object into its string representation.
PURL::URIOnly
Translate to a string with no scheme or host.
Definition: url.h:137
PURL::SetQueryVars
void SetQueryVars(const PStringToString &queryVars)
Set the Query (?) field(s) of the URL as a string dictionary.
PURL::port
WORD port
Definition: url.h:369
PURL::path
PStringArray path
Definition: url.h:372
PURL::CopyContents
void CopyContents(const PURL &other)