URL parser and constructor. More...

#include <Url.h>

Public Types
enum	Scheme { UnknownUrlScheme, SipUrlScheme, SipsUrlScheme, HttpUrlScheme, HttpsUrlScheme, FtpUrlScheme, FileUrlScheme, MailtoUrlScheme, RtspUrlScheme, NUM_SUPPORTED_URL_SCHEMES }
	Identifiers for all supported URI schemes. More...

Public Member Functions
	Url (const char *urlString=NULL, UtlBoolean isAddrSpec=FALSE)
	Default constructor from string. More...

	Url (const Url &rUrl)
	Copy constructor. More...

virtual	~Url ()
	Destructor. More...

Url &	operator= (const Url &rhs)
	Assignment operator. More...

Url &	operator= (const char *urlString)
	Assignment from string. More...

void	fromString (const UtlString &urlString, UtlBoolean isAddrSpec=FALSE)
	set the value of this url by parsing the given string. More...

void	toString (UtlString &urlString) const
	Serialize this URL to a string in name-addr format, suitable for use. More...

UtlString	toString () const
	Serialize this URL to a string in name-addr format, suitable for use. More...

void	dump ()
	Debug dump to STDOUT. More...

void	reset ()
	Clear the contents of this URL. More...

void	removeParameters ()
	Remove all of the URL, header and field parameters and values. More...

void	getIdentity (UtlString &identity) const
	Construct the cannonical identity. More...

void	getUrlType (UtlString &urlProtocol) const
	Get the URL application layer protocol scheme string. More...

void	setUrlType (const char *urlProtocol)
	Set the URL application layer protocol using the scheme name string. More...

void	getDisplayName (UtlString &displayName) const
	Get the URL display name if present. More...

void	setDisplayName (const char *displayName)
	Set the URL display name. More...

void	getUserId (UtlString &userId) const
	Get the URL user identity if present. More...

void	setUserId (const char *userId)
	Set the URL user identity. More...

UtlBoolean	getPassword (UtlString &userId) const
	Get the users password if present in the URL. More...

void	setPassword (const char *userId)
	Set the users password in the URL. More...

void	getHostAddress (UtlString &address) const
	Get the URL host name or IP address. More...

void	getHostWithPort (UtlString &domain) const
	Get the host and port together as a string "host:port". More...

void	setHostAddress (const char *address)
	Set the URL host name or IP address. More...

int	getHostPort () const
	Get the URL host port. More...

void	setHostPort (int port)
	Set the URL host port. More...

UtlBoolean	getPath (UtlString &path, UtlBoolean getStyle=FALSE)
	Get the file path from the URL. More...

void	setPath (const char *path)
	Set the file path. More...

UtlBoolean	getUrlParameter (const char *name, UtlString &value, int index=0)
	Get the named URL parameter value. More...

UtlBoolean	getUrlParameter (int urlIndex, UtlString &name, UtlString &value)
	Get the name and value of the URL parameter at the indicated index. More...

void	setUrlParameter (const char name, const char value)
	Set the named URL parameter to the given value. More...

void	removeUrlParameters ()
	Removes all of the URL parameters. More...

void	removeUrlParameter (const char *name)
	Removes all of the URL parameters with the given name. More...

UtlBoolean	getUrlParameters (int iMaxReturn, UtlString pNames, UtlString pValues, int &iActualReturn)
	Gets all of the URL parameters and values. More...

UtlBoolean	getHeaderParameter (const char *name, UtlString &value, int index=0)
	Get the named header parameter value. More...

UtlBoolean	getHeaderParameter (int headerIndex, UtlString &headerName, UtlString &headerValue)
	Get the name and value of the header parameter at the indicated index. More...

void	setHeaderParameter (const char name, const char value)
	Set the named header parameter to the given value. More...

void	removeHeaderParameters ()
	Removes all of the header parameters. More...

void	removeHeaderParameter (const char *name)
	Removes all of the header parameters with the given name. More...

UtlBoolean	getHeaderParameters (int iMaxReturn, UtlString pNames, UtlString pValues, int &iActualReturn)
	Gets all of the Header parameters. More...

UtlBoolean	getFieldParameter (const char *name, UtlString &value, int index=0) const
	Get the named field parameter value. More...

UtlBoolean	getFieldParameter (int fieldIndex, UtlString &name, UtlString &value)
	Get the name and value of the field parameter at the indicated index. More...

void	setFieldParameter (const char name, const char value)
	Set the named field parameter to the given value. More...

void	removeFieldParameters ()
	Removes all of the field parameters. More...

void	removeFieldParameter (const char *name)
	Removes all of the field parameters with the given name. More...

UtlBoolean	getFieldParameters (int iMaxReturn, UtlString pNames, UtlString pValues, int &iActualReturn)
	Gets all of the Header parameters. More...

void	includeAngleBrackets ()
	Forces the presence of angle brackets (i.e. <>) in the URL when serialized. More...

void	removeAngleBrackets ()
	Remove the angle brackets (i.e. <>) from the URL. More...

void	getUri (UtlString &Uri)
	Gets the serialized URL as a string (with no display name or field parameters) More...

UtlBoolean	isUserHostPortEqual (const Url &uri, int impliedPort=PORT_NONE) const
	Compare two URLs to see if the have the same user, host and port. More...

UtlBoolean	isUserHostEqual (const Url &uri) const
	Compare two URLs to see if the have the same user and host. More...

UtlBoolean	isIncludeAngleBracketsSet () const
	Are angle brackets explicitly included. More...

Scheme	scheme (const UtlString &schemeName)
	Translate a scheme string (not including the terminating colon) to a Scheme enum. More...

const char *	schemeName (Scheme scheme)
	Get the canonical (lowercase) name constant for a supported Scheme. More...

Scheme	getScheme () const
	Get the enumerator for the URL scheme type (more convenient than getUrlType). More...

void	setScheme (Scheme scheme)
	Set the scheme to be used (also see setUrlType). More...

Static Public Member Functions
static void	gen_value_escape (UtlString &escapedText)
	Escape a string as a gen_value, which is what field-parameters use for values. More...

static void	gen_value_unescape (UtlString &escapedText)
	Un-escape a string as a gen_value, which is what field-parameters use for values. More...

static UtlBoolean	isDigitString (const char *dialedCharacters)
	Is string all digits. More...

Detailed Description

URL parser and constructor.

This object is used to parse and construct URL strings. This object contains all of the parsed components of a URL. It has the ability to construct a serialized string of the object using the toString() method. It can also be used as a parser using the constructor which accepts a string as input. This is intended to be a generic URL parser for all schema/protocol types. It is currently tested and known to work for sip, sips, http, https, ftp, and file type URLs. There are accessors for the various parts of the URL These parts appear in URLs such as the following:

"display name"<protocol:[//]user:password@host:port;urlparm=value?headerParam=value>;fieldParam=value

The routines for the various parts are:

display name
- getDisplayName()
- setDisplayName()
protocol
- getUrlType()
- setUrlType()
user
- getUserId()
- setUserId()
password
- getPassword()
- setPassword()
host
- getHostAddress()
- setHostAddress()
port
- getHostPort()
- setHostPort()
URL parameter names and values
header (or CGI) parameter names and values
field parameter names and values

Member Enumeration Documentation

enum Scheme

Identifiers for all supported URI schemes.

Enumerator
UnknownUrlScheme	invalid or unset scheme
SipUrlScheme	sip: (RFC 3261)
SipsUrlScheme	sips: (RFC 3261)
HttpUrlScheme	http: (RFC 2616)
HttpsUrlScheme	https: (RFC 2818)
FtpUrlScheme	ftp: (RFC 1738)
FileUrlScheme	file: (RFC 1738)
MailtoUrlScheme	mailto: (RFC 2368)
RtspUrlScheme	rtsp: (RFC 2326)
NUM_SUPPORTED_URL_SCHEMES

Constructor & Destructor Documentation

Url	(	const char *	urlString = `NULL`,
		UtlBoolean	isAddrSpec = `FALSE`
	)

Default constructor from string.

Parameters

urlString	string to parse URL from
isAddrSpec	- TRUE if this is an addrspec (a Request URI) FALSE if this is a URL from a header field

Url ( const Url & rUrl )

Copy constructor.

~Url ( )

virtual

Destructor.

Member Function Documentation

Url & operator= ( const Url & rhs )

Assignment operator.

Url & operator= ( const char * urlString )

Assignment from string.

Parse the given null terminated string and set the URL parts as found in the string.

void fromString	(	const UtlString &	urlString,
		UtlBoolean	isAddrSpec = `FALSE`
	)

set the value of this url by parsing the given string.

all arguments are the same as for the constructor.

void toString ( UtlString & urlString ) const

Serialize this URL to a string in name-addr format, suitable for use.

UtlString toString ( ) const

Serialize this URL to a string in name-addr format, suitable for use.

void dump ( )

Debug dump to STDOUT.

void reset ( )

Clear the contents of this URL.

void removeParameters ( )

Remove all of the URL, header and field parameters and values.

void getIdentity ( UtlString & identity ) const

Construct the cannonical identity.

In some applications this is used to compare if this URL refers to the same destination. The identity is:

"user@host:port"

void getUrlType ( UtlString & urlProtocol ) const

Get the URL application layer protocol scheme string.

If you are going to make decisions based on the type, it is more efficient to use getScheme to get the Scheme enumerated form rather than comparing strings.

void setUrlType ( const char * urlProtocol )

Set the URL application layer protocol using the scheme name string.

also see setScheme.

void getDisplayName ( UtlString & displayName ) const

Get the URL display name if present.

void setDisplayName ( const char * displayName )

Set the URL display name.

void getUserId ( UtlString & userId ) const

Get the URL user identity if present.

void setUserId ( const char * userId )

Set the URL user identity.

UtlBoolean getPassword ( UtlString & userId ) const

Get the users password if present in the URL.

void setPassword ( const char * userId )

Set the users password in the URL.

Putting a password in a URL is a really really bad idea. RFC 3261 says:

While the SIP and SIPS URI syntax allows this field to be present, its use is NOT RECOMMENDED, because the passing of authentication information in clear text (such as URIs) has proven to be a security risk in almost every case where it has been used.

void getHostAddress ( UtlString & address ) const

Get the URL host name or IP address.

void getHostWithPort ( UtlString & domain ) const

Get the host and port together as a string "host:port".

void setHostAddress ( const char * address )

Set the URL host name or IP address.

int getHostPort ( ) const

Get the URL host port.

void setHostPort ( int port )

Set the URL host port.

UtlBoolean getPath	(	UtlString &	path,
		UtlBoolean	getStyle = `FALSE`
	)

Get the file path from the URL.

Parameters

getStyle TRUE will put header (or CGI) parameters in path in the format needed for an HTTP GET. FALSE will form the path without the header parameters as formated for a HTTP POST.

void setPath ( const char * path )

Set the file path.

Note: the path should not contain header (or CGI) parameters

UtlBoolean getUrlParameter	(	const char *	name,
		UtlString &	value,
		int	index = `0`
	)

Get the named URL parameter value.

Gets the index occurrence of the named parameter (the same parameter name may occur multiple times in a URL).

Returns: TRUE if the indicated parameter exists

Parameters

name	the parameter name to get
value	the value of the named parameter

UtlBoolean getUrlParameter	(	int	urlIndex,
		UtlString &	name,
		UtlString &	value
	)

Get the name and value of the URL parameter at the indicated index.

Returns: TRUE if the indicated parameter exists.

Parameters

urlIndex	the index indicting which URL parameter to get (starting at 0 for the first one).
name	the parameter name at urlIndex
value	the value of the parameter at urlIndex

void setUrlParameter	(	const char *	name,
		const char *	value
	)

Set the named URL parameter to the given value.

Adds the parameter if it does not exist, sets the value if it does exist.

Parameters

name	- the parameter name
value	- the value of the parameter

void removeUrlParameters ( )

Removes all of the URL parameters.

void removeUrlParameter ( const char * name )

Removes all of the URL parameters with the given name.

UtlBoolean getUrlParameters	(	int	iMaxReturn,
		UtlString *	pNames,
		UtlString *	pValues,
		int &	iActualReturn
	)

Gets all of the URL parameters and values.

Parameters

iMaxReturn	(in) - the maximum number of items to return
pNames	(out) - Pointer to a preallocated array of UtlStrings. If a null is specified, the function will return false and the iActualReturn will contain the actual number of parameters.
pValues	(out) - Pointer to a preallocated array of UtlStrings. If a null is specified, the function will return false and the iActualReturn will contain the actual number of parameters.
iActualReturn	(out) - The actual number of items returned

Returns: TRUE if values are returned otherwise FALSE

UtlBoolean getHeaderParameter	(	const char *	name,
		UtlString &	value,
		int	index = `0`
	)

Get the named header parameter value.

Parameters

name	- the parameter name to get
value	- the value of the named parameter
index	- gets the index occurance of the named parameter (the same parameter name may occur multiple times in the URL).

Returns: TRUE if the indicated parameter exists

UtlBoolean getHeaderParameter	(	int	headerIndex,
		UtlString &	headerName,
		UtlString &	headerValue
	)

Get the name and value of the header parameter at the indicated index.

Parameters

headerIndex	- the index indicting which header parameter to get (starting at 0 for the first one).
name	- the parameter name at headerIndex
value	- the value of the parameter at headerIndex

Returns: TRUE if the indicated parameter exists

void setHeaderParameter	(	const char *	name,
		const char *	value
	)

Set the named header parameter to the given value.

For sip and sips URLs, this sets the header parameter to the value if the header name is unique according to SipMessage::isUrlHeaderUnique, overwriting any previous value. If the header is not unique, then this appends the header parameter.

For all other URL schemes, the parameter is always appended.

To ensure that any previous value is replaced, call removeHeaderParameter(name) first.

Parameters

name	the parameter name
value	the value of the parameter

void removeHeaderParameters ( )

Removes all of the header parameters.

void removeHeaderParameter ( const char * name )

Removes all of the header parameters with the given name.

UtlBoolean getHeaderParameters	(	int	iMaxReturn,
		UtlString *	pNames,
		UtlString *	pValues,
		int &	iActualReturn
	)

Gets all of the Header parameters.

Parameters

iMaxReturn	(in) - the maximum number of items to return
pNames	(out) - Pointer to a preallocated collection of UtlStrings. If a null is specified, the function will return false and the iActualReturn will contain the actual number of parameters.
pValues	(out) - Pointer to a preallocated collection of UtlStrings. If a null is specified, the function will return false and the iActualReturn will contain the actual number of parameters.
iActualReturn	(out) - The actual number of items returned

Returns: TRUE if values are returned otherwise FALSE

UtlBoolean getFieldParameter	(	const char *	name,
		UtlString &	value,
		int	index = `0`
	)		const

Get the named field parameter value.

Parameters

name	- the parameter name to get
value	- the value of the named parameter
index	- gets the index occurance of the named parameter (the same parameter name may occur multiple times in the URL).

Returns: TRUE if the indicated parameter exists

UtlBoolean getFieldParameter	(	int	fieldIndex,
		UtlString &	name,
		UtlString &	value
	)

Get the name and value of the field parameter at the indicated index.

Parameters

fieldIndex	- the index indicting which field parameter to get (starting at 0 for the first one).
name	- the parameter name at fieldIndex
value	- the value of the parameter at fieldIndex

Returns: TRUE if the indicated parameter exists

void setFieldParameter	(	const char *	name,
		const char *	value
	)

Set the named field parameter to the given value.

Adds the parameter if it does not exist, sets the value if it does exist.

Parameters

name	- the parameter name
value	- the value of the parameter

void removeFieldParameters ( )

Removes all of the field parameters.

void removeFieldParameter ( const char * name )

Removes all of the field parameters with the given name.

UtlBoolean getFieldParameters	(	int	iMaxReturn,
		UtlString *	pNames,
		UtlString *	pValues,
		int &	iActualReturn
	)

Gets all of the Header parameters.

Parameters

iMaxReturn	(in) - the maximum number of items to return UtlStrings. If a null is specified, the function will return false and the iActualReturn will contain the actual number of parameters.
pValues	(out) - Pointer to a preallocated collection of UtlStrings. If a null is specified, the function will return false and the iActualReturn will contain the actual number of parameters.
iActualReturn	(out) - The actual number of items returned

Returns: TRUE if values are returned otherwise FALSE

void includeAngleBrackets ( )

Forces the presence of angle brackets (i.e. <>) in the URL when serialized.

void removeAngleBrackets ( )

Remove the angle brackets (i.e. <>) from the URL.

This does not really do anything - the toString function always puts out a canonical form that does not include angle brackets if it is possible to omit them.

void gen_value_escape ( UtlString & escapedText )

static

Escape a string as a gen_value, which is what field-parameters use for values.

void gen_value_unescape ( UtlString & escapedText )

static

Un-escape a string as a gen_value, which is what field-parameters use for values.

void getUri ( UtlString & Uri )

Gets the serialized URL as a string (with no display name or field parameters)

UtlBoolean isDigitString ( const char * dialedCharacters )

static

Is string all digits.

Parameters

dialedCharacters - null terminated string containing ascii test \ return TRUE if the dialedCharacters are all digits

UtlBoolean isUserHostPortEqual	(	const Url &	uri,
		int	impliedPort = `PORT_NONE`
	)		const

Compare two URLs to see if the have the same user, host and port.

Follows the rules of RFC 3261 section 19.1.4, especially that that no port specifies is NOT the same as the default port for the URL type/protocol (but see the description of impliedPort).

Assumes that host is not case sensitive (because DNS names are not by definition), but that user id is case sensitive.

If the impliedPort is some value other than PORT_NONE, then that port number is considered to be equal to an unspecified port number. For example:

Url implicitPortUrl("sip:user@example.com");
UtlBoolean result;
Url explicitPortUrl("<sip:user@Example.COM:5060>;param=x");
result = implicitPortUrl.isUserHostPortEqual(explicitPortUrl);
// result is FALSE because an implicit port != 5060
Url unspecifiedPortUrl("<sip:user@Example.COM>;param=x");
result = implicitPortUrl.isUserHostPortEqual(unspecifiedPortUrl);
// result is TRUE, despite case difference in domain name
Url otherPortUrl("<sip:user@Example.COM:5999>;param=x");
result = implicitPortUrl.isUserHostPortEqual(otherPortUrl, 5999);
// result is TRUE because the specified implicit port is
// considered to be that implied by the unspecified port in implicitPortUrl
result = implicitPortUrl.isUserHostPortEqual(otherPortUrl, 5060);
// result is FALSE because the specified implicit port does not match

Returns: TRUE if the user Id, host and port are the same

UtlBoolean isUserHostEqual ( const Url & uri ) const

Compare two URLs to see if the have the same user and host.

Assumes that host is not case sensitive, but that user id is case sensitive.

Returns: TRUE if the user Id and host are the same

UtlBoolean isIncludeAngleBracketsSet ( ) const

Are angle brackets explicitly included.

Note: does not test if angle brackets are required or will be added implicitly.

Returns: TRUE if angle brackets were found when parsing or if they are explicitly set to be inserted during serialization.

Url::Scheme scheme ( const UtlString & schemeName )

Translate a scheme string (not including the terminating colon) to a Scheme enum.

const char * schemeName ( Url::Scheme scheme )

Get the canonical (lowercase) name constant for a supported Scheme.

Get the canonical (lowercase) name of a supported Scheme.

Url::Scheme getScheme ( ) const

Get the enumerator for the URL scheme type (more convenient than getUrlType).

void setScheme ( Url::Scheme scheme )

Set the scheme to be used (also see setUrlType).

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

sipXtackLib home page