#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

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

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.

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.

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

MStatus setQueryDelimiters	(	char	valueDelimiter,
		char	pairDelimiter
	)

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

MURI Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation