PURL Class Reference

This class describes a Universal Resource Locator. More...

`#include <url.h>`

Inheritance diagram for PURL:

## Public Member Functions

| PURL ()
| Construct a new URL object from the URL string. More...
| PURL (const char *cstr, const char *defaultScheme="http")
| Construct a new URL object from the URL string. More...
| PURL (const PString &str, const char *defaultScheme="http")
| Construct a new URL object from the URL string. More...
| PURL (const PFilePath &path)
| Construct a new URL object from the file path. More...
| PURL (const PURL &other)
PURL & | operator= (const PURL &other)
PBoolean | LegacyParse (const PString &url, const PURLLegacyScheme *schemeInfo)
PString | LegacyAsString (PURL::UrlFormat fmt, const PURLLegacyScheme *schemeInfo) const
Overrides from class PObject
virtual Comparison | Compare (const PObject &obj) const
| Compare the two URLs and return their relative rank. More...
virtual PINDEX | HashFunction () const
| This function yields a hash value required by the `PDictionary` class. More...
virtual void | PrintOn (ostream &strm) const
| Output the contents of the URL to the stream as a string. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the URL from the stream. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...

## Protected Member Functions

void | CopyContents (const PURL &other)
virtual PBoolean | InternalParse (const char *cstr, const char *defaultScheme)
void | Recalculate ()
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes

PString | urlString
PCaselessString | scheme
PString | username
PString | password
PCaselessString | hostname
WORD | port
PBoolean | portSupplied
PBoolean | relativePath
| port was supplied in string input More...
PStringArray | path
PStringOptions | paramVars
PString | fragment
PStringOptions | queryVars
PString | m_contents

## New functions for class.

enum | UrlFormat { FullURL, PathOnly, URIOnly, HostPortOnly }
| Print/String output representation formats. More...
enum | TranslationType { LoginTranslation, PathTranslation, QueryTranslation, ParameterTranslation, QuotedParameterTranslation }
| Type for translation of strings to URL format,. More...
PBoolean | Parse (const char *cstr, const char *defaultScheme=NULL)
| Parse the URL string into the fields in the object instance. More...
PBoolean | Parse (const PString &str, const char *defaultScheme=NULL)
| Parse the URL string into the fields in the object instance. More...
PString | AsString (UrlFormat fmt=FullURL) const
| Convert the URL object into its string representation. More...
| operator PString () const
PFilePath | AsFilePath () const
| Get the "file:" URL as a file path. More...
const PCaselessString & | GetScheme () const
| Get the scheme field of the URL. More...
void | SetScheme (const PString &scheme)
| Set the scheme field of the URL. More...
const PString & | GetUserName () const
| Get the username field of the URL. More...
void | SetUserName (const PString &username)
| Set the username field of the URL. More...
const PString & | GetPassword () const
| Get the password field of the URL. More...
void | SetPassword (const PString &password)
| Set the password field of the URL. More...
const PCaselessString & | GetHostName () const
| Get the hostname field of the URL. More...
void | SetHostName (const PString &hostname)
| Set the hostname field of the URL. More...
WORD | GetPort () const
| Get the port field of the URL. More...
void | SetPort (WORD newPort)
| Set the port field in the URL. More...
PBoolean | GetPortSupplied () const
| Get if explicit port is specified. More...
PBoolean | GetRelativePath () const
| Get if path is relative or absolute. More...
PString | GetPathStr () const
| Get the path field of the URL as a string. More...
void | SetPathStr (const PString &pathStr)
| Set the path field of the URL as a string. More...
const PStringArray & | GetPath () const
| Get the path field of the URL as a string array. More...
void | SetPath (const PStringArray &path)
| Set the path field of the URL as a string array. More...
void | AppendPath (const PString &segment)
| Append segment to the path field of the URL. More...
PString | GetParameters () const
| Get the parameter (;) field of the URL. More...
void | SetParameters (const PString &parameters)
| Set the parameter (;) field of the URL. More...
const PStringOptions & | GetParamVars () const
| Get the parameter (;) field(s) of the URL as a string dictionary. More...
void | SetParamVars (const PStringToString &paramVars)
| Set the parameter (;) field(s) of the URL as a string dictionary. More...
void | SetParamVar (const PString &key, const PString &data, bool emptyDataDeletes=true)
| Set the parameter (;) field of the URL as a string dictionary. More...
const PString & | GetFragment () const
| Get the fragment (#) field of the URL. More...
PString | GetQuery () const
| Get the Query (?) field of the URL as a string. More...
void | SetQuery (const PString &query)
| Set the Query (?) field of the URL as a string. More...
const PStringOptions & | GetQueryVars () const
| Get the Query (?) field of the URL as a string dictionary. More...
void | SetQueryVars (const PStringToString &queryVars)
| Set the Query (?) field(s) of the URL as a string dictionary. More...
void | SetQueryVar (const PString &key, const PString &data)
| Set the Query (?) field of the URL as a string dictionary. More...
const PString & | GetContents () const
| Get the contents of URL, data left after all elemetns are parsed out. More...
void | SetContents (const PString &str)
| Set the contents of URL, data left after all elemetns are parsed out. More...
PBoolean | IsEmpty () const
| Return true if the URL is an empty string. More...
bool | LoadResource (PString &data, const PString &requiredContentType=PString::Empty()) const
| Get the resource the URL is pointing at. More...
bool | LoadResource (PBYTEArray &data, const PString &requiredContentType=PString::Empty()) const
bool | OpenBrowser () const
| Open the URL in a browser. More...
static PString | TranslateString (const PString &str, TranslationType type)
| Translate a string from general form to one that can be included into a URL. More...
static PString | UntranslateString (const PString &str, TranslationType type)
| Untranslate a string from a form that was included into a URL into a normal string. More...
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. More...
static void | SplitQueryVars (const PString &queryStr, PStringToString &queryVars)
| Split a string in &= form to a dictionary of names and values. More...
static void | OutputVars (ostream &strm, const PStringToString &vars, char sep0= ';', char sep1= ';', char sep2= '=', TranslationType type=ParameterTranslation)
| Construct string from a dictionary using separators. More...
static bool | OpenBrowser (const PString &url)

## Additional Inherited Members

Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...

## Detailed Description

This class describes a Universal Resource Locator.

This is the desciption of a resource location as used by the World Wide Web and the `PHTTPSocket` class.

## Member Enumeration Documentation

enum PURL::TranslationType

Type for translation of strings to URL format,.

Enumerator
LoginTranslation | Translate a username/password field for a URL.
PathTranslation | Translate the path field for a URL.
QueryTranslation | Translate the query variable field for a URL.
ParameterTranslation | Translate the parameter variables field for a URL.
QuotedParameterTranslation | Translate the quoted parameter variables field for a URL.

enum PURL::UrlFormat

Print/String output representation formats.

Enumerator
FullURL | Translate to a string as a full URL.
PathOnly | Translate to a string as only path.
URIOnly | Translate to a string with no scheme or host.
HostPortOnly | Translate to a string with scheme and host/port.

## Constructor & Destructor Documentation

PURL::PURL | ( |  | ) |

Construct a new URL object from the URL string.

PURL::PURL | ( | const char * | cstr,
|  | const char * | defaultScheme = `"http"`
| ) |  |

Construct a new URL object from the URL string.

Parameters

  cstr | C string representation of the URL.
  defaultScheme | Default scheme for URL

PURL::PURL | ( | const PString & | str,
|  | const char * | defaultScheme = `"http"`
| ) |  |

Construct a new URL object from the URL string.

Parameters

  str | String representation of the URL.
  defaultScheme | Default scheme for URL

PURL::PURL | ( | const PFilePath & | path | ) |

Construct a new URL object from the file path.

Parameters

  path | File path to turn into a "file:" URL.

PURL::PURL | ( | const PURL & | other | ) |

## Member Function Documentation

void PURL::AppendPath | ( | const PString & | segment | ) |

Append segment to the path field of the URL.

PFilePath PURL::AsFilePath | ( |  | ) | const

Get the "file:" URL as a file path.

If the URL is not a "file:" URL then returns an empty string.

PString PURL::AsString | ( | UrlFormat | fmt = `FullURL` | ) | const

Convert the URL object into its string representation.

The parameter indicates whether a full or partial representation os to be produced.

Returns
  String representation of the URL.

Parameters

  fmt | The type of string to be returned.

Referenced by OpenBrowser(), and operator PString().

virtual Comparison PURL::Compare | ( | const PObject & | obj | ) | const

virtual

Compare the two URLs and return their relative rank.

Returns
  `LessThan`, `EqualTo` or `GreaterThan` according to the relative rank of the objects.

Parameters

  obj | Object to compare against.

Reimplemented from PObject.

void PURL::CopyContents | ( | const PURL & | other | ) |

protected

const PString& PURL::GetContents | ( |  | ) | const

inline

Get the contents of URL, data left after all elemetns are parsed out.

References m_contents.

const PString& PURL::GetFragment | ( |  | ) | const

inline

Get the fragment (#) field of the URL.

References fragment.

const PCaselessString& PURL::GetHostName | ( |  | ) | const

inline

Get the hostname field of the URL.

References hostname.

PString PURL::GetParameters | ( |  | ) | const

Get the parameter (;) field of the URL.

const PStringOptions& PURL::GetParamVars | ( |  | ) | const

inline

Get the parameter (;) field(s) of the URL as a string dictionary.

Note the values have already been translated using UntranslateString

References paramVars.

const PString& PURL::GetPassword | ( |  | ) | const

inline

Get the password field of the URL.

References password.

const PStringArray& PURL::GetPath | ( |  | ) | const

inline

Get the path field of the URL as a string array.

References path.

PString PURL::GetPathStr | ( |  | ) | const

Get the path field of the URL as a string.

WORD PURL::GetPort | ( |  | ) | const

inline

Get the port field of the URL.

References port.

PBoolean PURL::GetPortSupplied | ( |  | ) | const

inline

Get if explicit port is specified.

References portSupplied.

PString PURL::GetQuery | ( |  | ) | const

Get the Query (?) field of the URL as a string.

const PStringOptions& PURL::GetQueryVars | ( |  | ) | const

inline

Get the Query (?) field of the URL as a string dictionary.

Note the values have already been translated using UntranslateString

References queryVars.

PBoolean PURL::GetRelativePath | ( |  | ) | const

inline

Get if path is relative or absolute.

References relativePath.

const PCaselessString& PURL::GetScheme | ( |  | ) | const

inline

Get the scheme field of the URL.

References scheme.

const PString& PURL::GetUserName | ( |  | ) | const

inline

Get the username field of the URL.

References username.

virtual PINDEX PURL::HashFunction | ( |  | ) | const

virtual

This function yields a hash value required by the `PDictionary` class.

A descendent class that is required to be the key of a dictionary should override this function. The precise values returned is dependent on the semantics of the class. For example, the `PString` class overrides it to provide a hash function for distinguishing text strings.

The default behaviour is to return the value zero.

Returns
  hash function value for class instance.

Reimplemented from PObject.

virtual PBoolean PURL::InternalParse | ( | const char * | cstr,
|  | const char * | defaultScheme
| ) |  |

protected virtual

Parameters

  cstr | URL as a string to parse.
  defaultScheme | Default scheme for URL

Referenced by Parse().

PBoolean PURL::IsEmpty | ( |  | ) | const

inline

Return true if the URL is an empty string.

References PString::IsEmpty(), and urlString.

PString PURL::LegacyAsString | ( | PURL::UrlFormat | fmt,
|  | const PURLLegacyScheme * | schemeInfo
| ) |  | const

Referenced by PURLLegacyScheme::AsString().

PBoolean PURL::LegacyParse | ( | const PString & | url,
|  | const PURLLegacyScheme * | schemeInfo
| ) |  |

Referenced by PURLLegacyScheme::Parse().

bool PURL::LoadResource | ( | PString & | data,
|  | const PString & | requiredContentType = `PString::Empty()`
| ) |  | const

Get the resource the URL is pointing at.

The data returned is obtained according to the scheme and the factory PURLLoaderFactory.

Parameters

  data | Resource data as a string
  requiredContentType | Expected content type where applicable

bool PURL::LoadResource | ( | PBYTEArray & | data,
|  | const PString & | requiredContentType = `PString::Empty()`
| ) |  | const

Parameters

  data | Resource data as a binary blob
  requiredContentType | Expected content type where applicable

bool PURL::OpenBrowser | ( |  | ) | const

inline

Open the URL in a browser.

Returns
  The browser was successfully opened. This does not mean the URL exists and was displayed.

References AsString(), and OpenBrowser().

Referenced by OpenBrowser().

static bool PURL::OpenBrowser | ( | const PString & | url | ) |

static

Parameters

  url | URL to open

PURL::operator PString | ( |  | ) | const

inline

References AsString().

PURL& PURL::operator= | ( | const PURL & | other | ) |

static void PURL::OutputVars | ( | ostream & | strm,
|  | const PStringToString & | vars,
|  | char | sep0 = `';'`,
|  | char | sep1 = `';'`,
|  | char | sep2 = `'='`,
|  | TranslationType | type = `ParameterTranslation`
| ) |  |

static

Construct string from a dictionary using separators.

Parameters

  strm | Stream to output dictionary to
  vars | Dictionary of variable names and values.
  sep0 | First separater before all ('\0' means none)
  sep1 | Separater between pairs
  sep2 | Separater between key and value
  type | Type of translation.

PBoolean PURL::Parse | ( | const char * | cstr,
|  | const char * | defaultScheme = `NULL`
| ) |  |

inline

Parse the URL string into the fields in the object instance.

Parameters

  cstr | URL as a string to parse.
  defaultScheme | Default scheme for URL

References InternalParse().

PBoolean PURL::Parse | ( | const PString & | str,
|  | const char * | defaultScheme = `NULL`
| ) |  |

inline

Parse the URL string into the fields in the object instance.

Parameters

  str | URL as a string to parse.
  defaultScheme | Default scheme for URL

References InternalParse().

virtual void PURL::PrintOn | ( | ostream & | strm | ) | const

virtual

Output the contents of the URL to the stream as a string.

Parameters

  strm | Stream to print the object into.

Reimplemented from PObject.

Reimplemented in PvCard::InlineValue, and PvCard::URIValue.

virtual void PURL::ReadFrom | ( | istream & | strm | ) |

virtual

Input the contents of the URL from the stream.

The input is a URL in string form.

Parameters

  strm | Stream to read the objects contents from.

Reimplemented from PObject.

Reimplemented in PvCard::InlineValue, and PvCard::URIValue.

void PURL::Recalculate | ( |  | ) |

protected

void PURL::SetContents | ( | const PString & | str | ) |

Set the contents of URL, data left after all elemetns are parsed out.

void PURL::SetHostName | ( | const PString & | hostname | ) |

Set the hostname field of the URL.

void PURL::SetParameters | ( | const PString & | parameters | ) |

Set the parameter (;) field of the URL.

void PURL::SetParamVar | ( | const PString & | key,
|  | const PString & | data,
|  | bool | emptyDataDeletes = `true`
| ) |  |

Set the parameter (;) field of the URL as a string dictionary.

Note the values will be translated using TranslateString

Parameters

  key | Key to add/delete
  data | Vlaue to add at key, if empty string may be removed
  emptyDataDeletes | If true, and data empty string, key is removed

void PURL::SetParamVars | ( | const PStringToString & | paramVars | ) |

Set the parameter (;) field(s) of the URL as a string dictionary.

Note the values will be translated using TranslateString

void PURL::SetPassword | ( | const PString & | password | ) |

Set the password field of the URL.

void PURL::SetPath | ( | const PStringArray & | path | ) |

Set the path field of the URL as a string array.

void PURL::SetPathStr | ( | const PString & | pathStr | ) |

Set the path field of the URL as a string.

void PURL::SetPort | ( | WORD | newPort | ) |

Set the port field in the URL.

void PURL::SetQuery | ( | const PString & | query | ) |

Set the Query (?) field of the URL as a string.

Note the values will be translated using UntranslateString

void PURL::SetQueryVar | ( | const PString & | key,
|  | const PString & | data
| ) |  |

Set the Query (?) field of the URL as a string dictionary.

Note the values will be translated using TranslateString

void PURL::SetQueryVars | ( | const PStringToString & | queryVars | ) |

Set the Query (?) field(s) of the URL as a string dictionary.

Note the values will be translated using TranslateString

void PURL::SetScheme | ( | const PString & | scheme | ) |

Set the scheme field of the URL.

void PURL::SetUserName | ( | const PString & | username | ) |

Set the username field of the URL.

static void PURL::SplitQueryVars | ( | const PString & | queryStr,
|  | PStringToString & | queryVars
| ) |  |

inline static

Split a string in &= form to a dictionary of names and values.

Parameters

  queryStr | String to split into variables.
  queryVars | Dictionary of variable names and values.

References QueryTranslation, and SplitVars().

static void PURL::SplitVars | ( | const PString & | str,
|  | PStringToString & | vars,
|  | char | sep1 = `';'`,
|  | char | sep2 = `'='`,
|  | TranslationType | type = `ParameterTranslation`
| ) |  |

static

Split a string to a dictionary of names and values.

Parameters

  str | String to split into variables.
  vars | Dictionary of variable names and values.
  sep1 | Separater between pairs
  sep2 | Separater between key and value
  type | Type of translation.

Referenced by SplitQueryVars().

static PString PURL::TranslateString | ( | const PString & | str,
|  | TranslationType | type
| ) |  |

static

Translate a string from general form to one that can be included into a URL.

All reserved characters for the particular field type are escaped.

Returns
  String for the URL ready translation.

Parameters

  str | String to be translated.
  type | Type of translation.

static PString PURL::UntranslateString | ( | const PString & | str,
|  | TranslationType | type
| ) |  |

static

Untranslate a string from a form that was included into a URL into a normal string.

All reserved characters for the particular field type are unescaped.

Returns
  String from the URL untranslated.

Parameters

  str | String to be translated.
  type | Type of translation.

## Member Data Documentation

PString PURL::fragment

protected

Referenced by GetFragment().

PCaselessString PURL::hostname

protected

Referenced by GetHostName().

PString PURL::m_contents

protected

Referenced by GetContents().

PStringOptions PURL::paramVars

protected

Referenced by GetParamVars().

PString PURL::password

protected

Referenced by GetPassword().

PStringArray PURL::path

protected

Referenced by GetPath().

WORD PURL::port

protected

Referenced by GetPort().

PBoolean PURL::portSupplied

protected

Referenced by GetPortSupplied().

PStringOptions PURL::queryVars

protected

Referenced by GetQueryVars().

PBoolean PURL::relativePath

protected

port was supplied in string input

Referenced by GetRelativePath().

PCaselessString PURL::scheme

protected

Referenced by GetScheme().

PString PURL::urlString

protected

Referenced by IsEmpty().

PString PURL::username

protected

Referenced by GetUserName().

The documentation for this class was generated from the following file:

- url.h