PTLib Version 2.12.9

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
PURL Class Reference

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

`#include <url.h>`

Inheritance diagram for PURL:
[legend]
Collaboration diagram for PURL:
[legend]

## Classes
struct | LoadParams

## 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)
bool | LegacyParse (const char *str, 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
unsigned | GetTraceContextIdentifier () const
| Get PTRACE context identifier. More...
void | SetTraceContextIdentifier (unsigned id)
void | GetTraceContextIdentifier (PObject &obj)
void | GetTraceContextIdentifier (PObject *obj)
void | SetTraceContextIdentifier (const PObject &obj)
void | SetTraceContextIdentifier (const PObject *obj)
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
template<class CLS >
CLS * | CloneAs () const
| As for Clone() but converts to specified type. 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...
__inline const PObject * | PTraceObjectInstance () const
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...
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. 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
const PURLScheme * | schemeInfo
PString | urlString
PCaselessString | scheme
PString | username
PString | password
PCaselessString | hostname
WORD | port
bool | portSupplied
bool | relativePath
| port was supplied in string input More...
PStringArray | path
PStringOptions | paramVars
PString | fragment
PStringOptions | queryVars
PString | m_contents
Protected Attributes inherited from PObject
unsigned | m_traceContextIdentifier

## New functions for class.
enum | UrlFormat { FullURL, PathOnly, LocationOnly, RelativeOnly, HostPortOnly = LocationOnly, URIOnly = RelativeOnly }
| 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...
bool | 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. Zero resets to default. More...
PBoolean | GetPortSupplied () const
| Get if explicit port is specified. More...
PString | GetHostPort () const
| Get the hostname and optional port fields of the URL. 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...
void | ChangePath (const PString &segment, PINDEX idx=P_MAX_INDEX)
| Change segment in 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 LoadParams &params=LoadParams()) const
| Get the resource the URL is pointing at. More...
bool | LoadResource (PBYTEArray &data, const LoadParams &params=LoadParams()) const
template<class T >
bool | LoadResource (T &data, const PString &requiredContentType=PString::Empty(), const PTimeInterval &timeout=PMaxTimeInterval) 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 __inline const PObject * | PTraceObjectInstance (const char *)
static __inline const PObject * | PTraceObjectInstance (const PObject *obj)
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
Friends inherited from PObject

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

Note, this has been extended to be for URI's (Universal Resource Identifier) which is a superset of URL's. But for backward compatinility reasons the name is still PURL.

## 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 | Output full URI.
PathOnly | Translate to a string as only path.
LocationOnly | Translate to a string with the location (scheme and user/pass/host/port)
RelativeOnly | Translate to a string with no scheme or host, just the relative part.
HostPortOnly |
URIOnly |

## 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 PHTTPResource::GetHotLink(), OpenBrowser(), and operator PString().

void PURL::ChangePath | ( | const PString & | segment,
|  | PINDEX | idx = `P_MAX_INDEX`
| ) |  |

Change segment in the path field of the URL.

Parameters

  segment | New value for segment, empty means remove
  idx | Segment index, P_MAX_INDEX means last segment

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::GetHostPort | ( |  | ) | const

Get the hostname and optional port fields 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

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().

bool PURL::LegacyParse | ( | const char * | str,
|  | const PURLLegacyScheme * | schemeInfo
| ) |  |

Referenced by PURLLegacyScheme::Parse().

bool PURL::LoadResource | ( | PString & | data,
|  | const LoadParams & | params = `LoadParams()`
| ) |  | 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
  params | Parameters for load

bool PURL::LoadResource | ( | PBYTEArray & | data,
|  | const LoadParams & | params = `LoadParams()`
| ) |  | const

Parameters

  data | Resource data as a binary blob
  params | Parameters for load

template<class T >

bool PURL::LoadResource | ( | T & | data,
|  | const PString & | requiredContentType = `PString::Empty()`,
|  | const PTimeInterval & | timeout = `PMaxTimeInterval`
| ) |  | const
| inline

Parameters

  data | Resource data as a string
  requiredContentType | Expected content type where applicable
  timeout | Timeout to wait for resource

References LoadResource().

Referenced by LoadResource().

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.

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.

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. Zero resets to default.

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

bool 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().

bool PURL::portSupplied
| protected

Referenced by GetPortSupplied().

PStringOptions PURL::queryVars
| protected

Referenced by GetQueryVars().

bool PURL::relativePath
| protected

port was supplied in string input

Referenced by GetRelativePath().

PCaselessString PURL::scheme
| protected

Referenced by GetScheme().

const PURLScheme* PURL::schemeInfo
| protected

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