PURL Class Reference

#include <url.h>

Inheritance diagram for PURL:


New functions for class.
enum	UrlFormat { FullURL, PathOnly, URIOnly, HostPortOnly }
enum	TranslationType { LoginTranslation, PathTranslation, QueryTranslation }
	Type for translation of strings to URL format,. More...
BOOL	Parse (const char cstr, const char defaultScheme=NULL)
BOOL	Parse (const PString &str, const char *defaultScheme=NULL)
PString	AsString (UrlFormat fmt=FullURL) const
PFilePath	AsFilePath () const
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.
BOOL	GetRelativePath () const
	Get if path is relative or absolute.
const 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.
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)
	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.
BOOL	IsEmpty () const
	Return TRUE if the URL is an empty string.
static PString	TranslateString (const PString &str, TranslationType type)
static PString	UntranslateString (const PString &str, TranslationType type)
static void	SplitQueryVars (const PString &queryStr, PStringToString &queryVars)
static BOOL	OpenBrowser (const PString &url)
Public Member Functions
	PURL ()
	PURL (const char cstr, const char defaultScheme=NULL)
	PURL (const PString &str, const char *defaultScheme=NULL)
	PURL (const PFilePath &path)
BOOL	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
virtual PINDEX	HashFunction () const
virtual void	PrintOn (ostream &strm) const
virtual void	ReadFrom (istream &strm)
Protected Member Functions
virtual BOOL	InternalParse (const char cstr, const char defaultScheme)
void	Recalculate ()
Protected Attributes
PString	urlString
PCaselessString	scheme
PString	username
PString	password
PCaselessString	hostname
WORD	port
BOOL	portSupplied
BOOL	relativePath
	port was supplied in string input
PString	pathStr
PStringArray	path
PStringToString	paramVars
PString	fragment
PStringToString	queryVars

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

Enumeration values:

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.
Enumeration values:

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 = NULL

)

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 = NULL

)

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.

Member Function Documentation

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.

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.

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.

const PString& PURL::GetPathStr ( ) const [inline]

Get the path field of the URL as a string.

WORD PURL::GetPort ( ) const [inline]

Get the port field of the URL.

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.

BOOL 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 BOOL PURL::InternalParse ( const char * cstr,

const char * defaultScheme

) [protected, virtual]

Parameters:

cstr URL as a string to parse.

defaultScheme Default scheme for URL

BOOL PURL::IsEmpty ( ) const [inline]

Return TRUE if the URL is an empty string.

PString PURL::LegacyAsString ( PURL::UrlFormat fmt,

const PURLLegacyScheme * schemeInfo

) const

BOOL PURL::LegacyParse ( const PString & _url,

const PURLLegacyScheme * schemeInfo

)

static BOOL 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

BOOL 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

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

)

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

void PURL::SetParamVars ( const PStringToString & paramVars )

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

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.

void PURL::SetQueryVar ( const PString & key,

const PString & data

)

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

void PURL::SetQueryVars ( const PStringToString & queryVars )

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

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

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