MURI Class Reference

#include <MURI.h>

Class Description

Manipulating Uniform Resource Identifiers.

The MURI class implements the W3 URI standard. It can parse and and construct URIs (Uniform Resource Identifiers). It is based on URI specification RFC 3986 (Uniform Resource Identifier: Generic Syntax).

"The generic URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, query, and fragment." -Section 3 of Network Working Group RFC 3986

foo://username:password@example.com:8042/over/there/index.dtb?type=animal;name=narwhal#nose
\_/   \_______________/ \_________/ \__/            \___/ \_/ \______________________/ \__/
 |           |               |       |                |    |            |                |
 |       userinfo         hostname  port              |    |          query          fragment
 |    \________________________________/\_____________|____|/
scheme                |                          |    |    |
                  authority                    path   |    |
                                                      |    |
                                        interpretable as filename
                                                           |
                                                           |
                                                interpretable as extension

The scheme and path components are required, although the path may be empty (no characters). When the authority is present, the path must either be empty or begin with a slash ("/") character. When the authority is not present, the path cannot begin with two slash characters ("//").

URI objects are often initialized using URI string values. An MURI object can be constructed from an MString value, or set from a string using the setURI() method.

A URI can also be constructed from its individual components using methods setScheme(), setUserName(), setPassword(), setHost(), setPort(), setPath(), addQueryItem() and setFragment().

Convenience methods such as setAuthority() and setUserInfo() are also available to initialize groups of related components. Methods for configuring the query components of the URI are also provided: setQueryItems(), addQueryItem(), removeQueryItem() and setQueryDelimiters().

The string representation of the URI object is obtained by calling asString(). Individual components of the URI are accessed by calling the corresponding get methods.

The MURI can be validated at any point by calling the isValid() method. In addition, a static method isValidURI() is available to determine if an MString represents a valid URI.

Public Member Functions
	MURI ()
	Class constructor. More...
	MURI (const MString &URI)
	Creates a new MURI object and initializes it using a URI string value. More...
	MURI (const MURI &other)
	Copy constructor. More...
	~MURI ()
	Class destructor.
MURI &	operator= (const MURI &rhs)
	Assignment operator. More...
MURI &	operator= (const MString &URI)
	Assignment operator. More...
bool	operator== (const MURI &rhs) const
	Equality operator. More...
bool	operator!= (const MURI &rhs) const
	Inequality operator. More...
MStatus	copy (const MURI &other)
	Copy the contents of one URI object to another. More...
MStatus	setURI (const MString &URI)
	Initialize the MURI from a string value. More...
MStatus	setScheme (const MString &scheme)
	Sets the scheme component of the URI. More...
MStatus	setPath (const MString &path)
	Sets the path component of the URI. More...
MStatus	setFragment (const MString &fragment)
	Sets the fragment component of the URI. More...
MStatus	setFileName (const MString &fileName)
	Sets just the filename portion of the URI (i.e. More...
MStatus	setDirectory (const MString &directory)
	Sets just the directory portion of the URI (i.e. More...
MStatus	setAuthority (const MString &authority)
	Set the authority portion of the URI. More...
MStatus	setUserInfo (const MString &userInfo)
	Decomposes the userInfo string to fill out the userInfo-related component values. More...
MStatus	setUserName (const MString &userName)
	Sets the user name part of the user info component. More...
MStatus	setPassword (const MString &password)
	Sets the password part of the user info component. More...
MStatus	setHost (const MString &host)
	Set the host component of the URI. More...
MStatus	setPort (int port)
	Set the port component of the URI. More...
MStatus	addQueryItem (const MString &key, const MString &value)
	Add a key/value pair to the query string of the URI. More...
MStatus	setQueryDelimiters (char valueDelimiter, char pairDelimiter)
	Sets the delimiter characters used in the query string of the URI. More...
MString	asString () const
	Returns the string representation of the URI. More...
MString	getScheme () const
	Returns the scheme of the URI. More...
MString	getPath () const
	Returns the path component of the URI. More...
MString	getFragment () const
	Returns the fragment component of the URI. More...
MString	getFileName (bool includeExtension=true) const
	Returns just the file name portion of the URI, with or without the extension. More...
MString	getDirectory () const
	Returns just the file directory portion of the URI, without the file name. More...
MString	getAuthority () const
	Returns the authority component of the URI. More...
MString	getUserInfo () const
	Returns the user info component of the URI. More...
MString	getUserName () const
	Returns the user name component of the URI. More...
MString	getPassword () const
	Returns the password component of the URI. More...
MString	getHost () const
	Returns the host component of the URI. More...
int	getPort () const
	Returns the port component of the URI, or -1 if the port is not defined. More...
MStringArray	getAllQueryItemKeys () const
	Returns an array containing the keys from all query string pairs. More...
MString	getQueryItemValue (const MString &key) const
	Returns the value from the first query string pair in the URI which has a given key. More...
MStringArray	getAllQueryItemValues (const MString &key) const
	Returns an array containing the values from all query string pairs which have a given key. More...
char	getQueryValueDelimiter () const
	Returns the character used to delimit keys and values in the query string of the URI. More...
char	getQueryPairDelimiter () const
	Returns the character used to delimit between key-value pairs in the query string of the URI. More...
MStatus	removeQueryItem (const MString &key)
	Removes the first query string pair with a given key from the URI. More...
MStatus	removeAllQueryItems (const MString &key)
	Removes all query string pairs having a given key from the URI. More...
bool	isEmpty () const
	Determines if the URI does not contain any data. More...
bool	isValid () const
	Determines if the URI is valid. More...
MStatus	clear ()
	Clears the contents of the MURI object. More...

Static Public Member Functions
static bool	isValidURI (const MString &URI)
	Determines if a string value represents a valid URI. More...
static const char *	className ()
	Returns the name of this class. More...

Constructor & Destructor Documentation

MURI

(

)

Class constructor.

Creates an empty MURI object.

MURI

(

const MString &

URI

)

Creates a new MURI object and initializes it using a URI string value.

Parameters

[in]

URI

The URI string. This must be a properly formatted URI (e.g. "file:///C:/dir/texture.jpg" on Windows). The individual components of the URI will be set based on the contents of the string.

Note that the directory separator for all platforms, including Windows, is a forward slash ('/'). Backslashes ('\') are treated as normal characters by this method but should be avoided as they may be interpreted as escape characters in other contexts. A regular file path (e.g. "C:\dir\texture.jpg" on Windows) is not a valid URI. See also isValid() and isValidURI().

MURI

(

const MURI &

other

)

Copy constructor.

Creates a new MURI object and initializes it with the value of another MURI object.

Parameters

[in]

other

The MURI to copy.

Member Function Documentation

MURI & operator=

(

const MURI &

rhs

)

Assignment operator.

Assigns the value of one MURI to another.

Parameters

[in]

rhs

Existing MURI object to copy.

Returns

Reference to this MURI instance.

MURI & operator=

(

const MString &

URI

)

Assignment operator.

Set the URI from a string value. The individual components of the URI will be set based on the contents of the string.

Parameters

[in]

URI

The URI string.

Returns

Reference to this MURI instance.

bool operator==

(

const MURI &

rhs

)

const

Equality operator.

Compares two MURI objects to see if they contain the same value.

Parameters

[in]

rhs

Right operand.

Returns

true if the two objects are equivalent, false otherwise.

bool operator!=

(

const MURI &

rhs

)

const

Inequality operator.

Compares two MURI objects to see if they differ.

Parameters

[in]

rhs

Right operand.

Returns

true if the two objects are different, false otherwise.

MStatus copy

(

const MURI &

other

)

Copy the contents of one URI object to another.

Parameters

[in]

other

The URI object to copy.

Returns

MS::kSuccess if the copy was successful and MS::kFailure otherwise

MStatus setURI

(

const MString &

URI

)

Initialize the MURI from a string value.

The individual components of the URI will be set based on the contents of the string.

Parameters

[in]

URI

The URI string.

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setScheme

(

const MString &

scheme

)

Sets the scheme component of the URI.

The scheme identifies the type of the URI. It is the first element of the URI and consists of all the characters preceeding the first ':'. The scheme is expected to contain only ASCII characters.

Parameters

[in]

scheme

The scheme to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setPath

(

const MString &

path

)

Sets the path component of the URI.

The path can contain both a directory and a file name. See also setFileName() and setDirectory().

Parameters

[in]

path

The path to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setFragment

(

const MString &

fragment

)

Sets the fragment component of the URI.

The fragment is the last part of the URI, after the '#'.

Parameters

[in]

fragment

The fragment to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setFileName

(

const MString &

fileName

)

Sets just the filename portion of the URI (i.e.

not including the directory). See also setPath() and setDirectory().

Parameters

[in]

fileName

The file name to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setDirectory

(

const MString &

directory

)

Sets just the directory portion of the URI (i.e.

not including the filename). See also setPath() and setFileName().

Note that the directory separator for all platforms, including Windows, is a forward slash ('/'). Backslashes ('\') are treated as normal characters by this method but should be avoided as they may be interpreted as escape characters in other contexts.

If there is no directory separator at the end of the directory path, one will be added.

Parameters

[in]

directory

The file directory to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setAuthority

(

const MString &

authority

)

Set the authority portion of the URI.

Decomposes the authority string to set the authority-related component values. The user info and host are separated by a '@', and the host and port are separated by a ':'. See also setUserName(), setPassword(), setHost() and setPort().

username:passw.nosp@m.ord@.nosp@m.examp.nosp@m.le.c.nosp@m.om:8042

Parameters

[in]

authority

The authority value to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setUserInfo

(

const MString &

userInfo

)

Decomposes the userInfo string to fill out the userInfo-related component values.

The user info consists of a user name and password separated by a colon ':'. The password is optional, if not specified, no colon is used. See also setAuthority(), setUserName(), setPassword().

username:password

Parameters

[in]

userInfo

The userInfo to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setUserName

(

const MString &

userName

)

Sets the user name part of the user info component.

See also setAuthority(), setUserInfo(), setPassword().

Parameters

[in]

userName

The user name to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setPassword

(

const MString &

password

)

Sets the password part of the user info component.

See also setAuthority(), setUserInfo(), setUserName().

Parameters

[in]

password

The password to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setHost

(

const MString &

host

)

Set the host component of the URI.

See also setAuthority(), setPort()

Parameters

[in]

host

The host to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setPort

(

int

port

)

Set the port component of the URI.

See also setAuthority(), setHost()

Parameters

[in]

port

The port to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus addQueryItem	(	const MString &	key,
		const MString &	value
	)

Add a key/value pair to the query string of the URI.

Parameters

[in]	key	The key to set
[in]	value	The value to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus setQueryDelimiters	(	char	valueDelimiter,
		char	pairDelimiter
	)

Sets the delimiter characters used in the query string of the URI.

The value delimiter is used between the key and the value in each pair. The pair delimeter separates pairs in the string.

The default value delimiter is '=' and the default pair delimiter is '&'.

See also getQueryValueDelimiter(), getQueryPairDelimiter().

Parameters

[in]	valueDelimiter	The valueDelimiter to set
[in]	pairDelimiter	The pairDelimiter to set

Returns

MS::kSuccess for success, otherwise MS::kFailure

MString asString

(

)

const

Returns the string representation of the URI.

Returns

The complete URI string.

MString getScheme

(

)

const

Returns the scheme of the URI.

An empty string is returned if the scheme is undefined or the current URI is invalid.

Returns

The scheme of the URI.

MString getPath

(

)

const

Returns the path component of the URI.

The path of the URI is composed of the file directory and file name. See also getFileName() and getDirectory() to access the file directory and file name components of the path individually.

Returns

The path of the URI.

MString getFragment

(

)

const

Returns the fragment component of the URI.

If the fragment is undefined, an empty string is returned.

Returns

The fragment of the URI.

MString getFileName

(

bool

includeExtension = true

)

const

Returns just the file name portion of the URI, with or without the extension.

The file directory is not included. See also getPath() and getDirectory().

Parameters

[in]

includeExtension

If true include the extension (e.g. "file.jpg"), otherwise do not (e.g. "file"). Its default value is true.

Returns

The file name defined in the URI.

MString getDirectory

(

)

const

Returns just the file directory portion of the URI, without the file name.

See also getPath() and getFileName().

Returns

The file directory defined in the URI.

MString getAuthority

(

)

const

Returns the authority component of the URI.

If the authority is undefined, an empty string is returned.

Returns

The authority of the URI.

MString getUserInfo

(

)

const

Returns the user info component of the URI.

If the user info is not defined, an empty string is returned. See also getUserName(), getPassword(), getHost(), getPort().

Returns

The user info of the URI.

MString getUserName

(

)

const

Returns the user name component of the URI.

If the user name is not defined, an empty string is returned. See also getUserInfo(), getPassword().

Returns

The user name of the URI.

MString getPassword

(

)

const

Returns the password component of the URI.

If the password is not defined, an empty string is returned. See also getUserInfo(), getUserName().

Returns

The password of the URI.

MString getHost

(

)

const

Returns the host component of the URI.

If the host is not defined, an empty string is returned. See also getUserInfo(), getPort().

Returns

The host of the URI.

int getPort

(

)

const

Returns the port component of the URI, or -1 if the port is not defined.

See also getUserInfo(), getHost().

Returns

The port of the URI.

MStringArray getAllQueryItemKeys

(

)

const

Returns an array containing the keys from all query string pairs.

Returns

Array of key string values.

MString getQueryItemValue

(

const MString &

key

)

const

Returns the value from the first query string pair in the URI which has a given key.

Parameters

[in]

key

The key to query

Returns

Query string value.

MStringArray getAllQueryItemValues

(

const MString &

key

)

const

Returns an array containing the values from all query string pairs which have a given key.

Parameters

[in]

key

The key to query

Returns

Array of query string values.

char getQueryValueDelimiter

(

)

const

Returns the character used to delimit keys and values in the query string of the URI.

See also setQueryDelimiters().

Returns

The character used to delimit between keys and values in the query string of the URI.

char getQueryPairDelimiter

(

)

const

Returns the character used to delimit between key-value pairs in the query string of the URI.

Returns

The character used to delimit between key-value pairs in the query string of the URI.

MStatus removeQueryItem

(

const MString &

key

)

Removes the first query string pair with a given key from the URI.

Parameters

[in]

key

The key of the query item to remove

Returns

MS::kSuccess for success, otherwise MS::kFailure

MStatus removeAllQueryItems

(

const MString &

key

)

Removes all query string pairs having a given key from the URI.

Parameters

[in]

key

The key of the query items to remove

Returns

MS::kSuccess for success, otherwise MS::kFailure

bool isEmpty

(

)

const

Determines if the URI does not contain any data.

Returns

true if the URI has no data, false otherwise.

bool isValid

(

)

const

Determines if the URI is valid.

Returns

true if the URI is valid, false otherwise.

MStatus clear

(

)

Clears the contents of the MURI object.

After clearing, the URI will be empty.

Returns

MS::kSuccess for success, otherwise MS::kFailure

bool isValidURI ( const MString &  URI )

static

Determines if a string value represents a valid URI.

Parameters

[in]

URI

the URI string to validate

Returns

true if the URI is valid, false otherwise.

const char * className ( )

static

Returns the name of this class.

Returns

Name of this class.

---

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

• MURI.h
• MURI.cpp