# PURL Class Reference

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

`#include <url.h>`

Inheritance diagram for PURL:

List of all members.

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

## Public Member Functions

| PURL ()
| Construct a new URL object from the URL string.
| PURL (const char *cstr, const char *defaultScheme="http")
| Construct a new URL object from the URL string.
| PURL (const PString &str, const char *defaultScheme="http")
| Construct a new URL object from the URL string.
| PURL (const PFilePath &path)
| Construct a new URL object from the file path.
| 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.
virtual PINDEX | HashFunction () const
| This function yields a hash value required by the `PDictionary` class.
virtual void | PrintOn (ostream &strm) const
| Output the contents of the URL to the stream as a string.
virtual void | ReadFrom (istream &strm)
| Input the contents of the URL from the stream.

## Protected Member Functions

void | CopyContents (const PURL &other)
virtual PBoolean | InternalParse (const char *cstr, const char *defaultScheme)
void | Recalculate ()

## Protected Attributes

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

## 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.

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.

const PString& PURL::GetFragment | ( |  | ) | const`[inline]`

Get the fragment (#) field of the URL.

const PCaselessString& PURL::GetHostName | ( |  | ) | const`[inline]`

Get the hostname field of the URL.

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

const PString& PURL::GetPassword | ( |  | ) | const`[inline]`

Get the password field of the URL.

const PStringArray& PURL::GetPath | ( |  | ) | const`[inline]`

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

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.

PBoolean PURL::GetPortSupplied | ( |  | ) | const`[inline]`

Get if explicit port is specified.

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

PBoolean PURL::GetRelativePath | ( |  | ) | const`[inline]`

Get if path is relative or absolute.

const PCaselessString& PURL::GetScheme | ( |  | ) | const`[inline]`

Get the scheme field of the URL.

const PString& PURL::GetUserName | ( |  | ) | const`[inline]`

Get the username field of the URL.

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

PBoolean PURL::IsEmpty | ( |  | ) | const`[inline]`

Return true if the URL is an empty string.

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

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

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::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

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

Parameters:

  url | URL to open

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.

PURL::operator PString | ( |  | ) | const`[inline]`

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 ('' means none)
  sep1 | Separater between pairs
  sep2 | Separater between key and value
  type | Type of translation.

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

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

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::URIValue, and PvCard::InlineValue.

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::URIValue, and PvCard::InlineValue.

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.

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.

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]`

PCaselessString PURL::hostname `[protected]`

PString PURL::m_contents `[protected]`

PStringOptions PURL::paramVars `[protected]`

PString PURL::password `[protected]`

PStringArray PURL::path `[protected]`

WORD PURL::port `[protected]`

PBoolean PURL::portSupplied `[protected]`

PStringOptions PURL::queryVars `[protected]`

PBoolean PURL::relativePath `[protected]`

port was supplied in string input

PCaselessString PURL::scheme `[protected]`

PString PURL::urlString `[protected]`

PString PURL::username `[protected]`

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

- url.h