PURL Class Reference

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

#include <url.h>

Inheritance diagram for PURL:


New functions for class.
enum	UrlFormat { FullURL, PathOnly, URIOnly, HostPortOnly }
	Print/String output representation formats. More...
enum	TranslationType { LoginTranslation, PathTranslation, QueryTranslation }
	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 PStringToString &	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 PStringToString &	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.
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)
	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 PBoolean	OpenBrowser (const PString &url)
	Open the URL in a browser.
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
PStringToString	paramVars
PString	fragment
PStringToString	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 parameters 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 PStringToString& 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 PStringToString& 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
	)

static PBoolean PURL::OpenBrowser ( const PString & url ) [static]

Open the URL in a browser.

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

Parameters:

url

URL to open

PURL::operator PString ( ) const [inline]

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

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.

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.

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
	)			`[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

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]

PStringToString PURL::paramVars [protected]

PString PURL::password [protected]

PStringArray PURL::path [protected]

WORD PURL::port [protected]

PBoolean PURL::portSupplied [protected]

PStringToString 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

Generated on Fri Oct 14 01:44:14 2011 for PTLib by

1.4.7

PURL Class Reference

New functions for class.

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation