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

#include <url.h>

Inheritance diagram for PURL:

Collaboration diagram for PURL:

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
__inline unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

__inline void	SetTraceContextIdentifier (unsigned id)

__inline void	SetTraceContextIdentifier (const PObject &obj)

__inline void	SetTraceContextIdentifier (const PObject *obj)

__inline void	CopyTraceContextIdentifier (PObject &obj) const

__inline void	CopyTraceContextIdentifier (PObject *obj) const

virtual	~PObject ()

__inline const char *	GetClass () const

__inline bool	IsClass (const char *name) const

__inline const PObject *	PTraceObjectInstance () const

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 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 *	m_schemeInfo

PString	m_urlString

PCaselessString	m_scheme

PString	m_username

PString	m_password

PCaselessString	m_hostname

WORD	m_port

bool	m_portSupplied

bool	m_relativePath
	port was supplied in string input More...

PStringArray	m_path

PStringOptions	m_paramVars

PString	m_fragment

PStringOptions	m_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, bool merge=false)
	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 PCaselessString	ExtractScheme (const char *str)
	Extract scheme as per RFC2396. 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 __inline void	CopyTraceContextIdentifier (PObject &to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject *from)

static __inline void	CopyTraceContextIdentifier (PObject *to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject to, const PObject from)

static __inline const char *	Class ()

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

template<typename T >
static Comparison	Compare2 (T v1, T v2)
	Compare two types, returning Comparison type. 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.

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

static PCaselessString PURL::ExtractScheme ( const char * str )

static

Extract scheme as per RFC2396.

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

const PCaselessString& PURL::GetHostName ( ) const

inline

Get the hostname field of the URL.

References m_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 m_paramVars.

const PString& PURL::GetPassword ( ) const

inline

Get the password field of the URL.

References m_password.

const PStringArray& PURL::GetPath ( ) const

inline

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

References m_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 m_port.

PBoolean PURL::GetPortSupplied ( ) const

inline

Get if explicit port is specified.

References m_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 m_queryVars.

PBoolean PURL::GetRelativePath ( ) const

inline

Get if path is relative or absolute.

References m_relativePath.

const PCaselessString& PURL::GetScheme ( ) const

inline

Get the scheme field of the URL.

References m_scheme.

const PString& PURL::GetUserName ( ) const

inline

Get the username field of the URL.

References m_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
	)

protectedvirtual

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

Referenced by LoadResource().

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

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,
		bool	merge = `false`
	)

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
	)

inlinestatic

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

protected

Referenced by GetContents().

PString PURL::m_fragment

protected

Referenced by GetFragment().

PCaselessString PURL::m_hostname

protected

Referenced by GetHostName().

PStringOptions PURL::m_paramVars

protected

Referenced by GetParamVars().

PString PURL::m_password

protected

Referenced by GetPassword().

PStringArray PURL::m_path

protected

Referenced by GetPath().

WORD PURL::m_port

protected

Referenced by GetPort().

bool PURL::m_portSupplied

protected

Referenced by GetPortSupplied().

PStringOptions PURL::m_queryVars

protected

Referenced by GetQueryVars().

bool PURL::m_relativePath

protected

port was supplied in string input

Referenced by GetRelativePath().

PCaselessString PURL::m_scheme

protected

Referenced by GetScheme().

const PURLScheme* PURL::m_schemeInfo

protected

PString PURL::m_urlString

protected

Referenced by IsEmpty().

PString PURL::m_username

protected

Referenced by GetUserName().

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

url.h

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

New functions for class.

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation