wxURI Class Reference

#include <wx/uri.h>

Inheritance diagram for wxURI:

Detailed Description

wxURI is used to extract information from a URI (Uniform Resource Identifier).

For information about URIs, see RFC 3986 (http://www.ietf.org/rfc/rfc3986.txt).

In short, a URL is a URI. In other words, URL is a subset of a URI - all acceptable URLs are also acceptable URIs.

wxURI automatically escapes invalid characters in a string, so there is no chance of wxURI "failing" on construction/creation.

wxURI supports copy construction and standard assignment operators. wxURI can also be inherited from to provide further functionality.

To obtain individual components you can use one of the GetXXX() methods. However, you should check HasXXX() before calling a get method, which determines whether or not the component referred to by the method is defined according to RFC 2396. Consider an undefined component equivalent to a NULL C string.

Example:

// protocol will hold the http protocol (i.e. "http")
wxString protocol;
wxURI myuri("http://mysite.com");
if( myuri.HasScheme() )
    protocol = myuri.GetScheme();

Note

On URIs with a "file" scheme wxURI does not parse the userinfo, server, or port portion. This is to keep compatibility with wxFileSystem, the old wxURL, and older url specifications.

Library:  wxBase

Category:  Networking

See Also

wxURL

Public Member Functions
	wxURI ()
	Creates an empty URI.
	wxURI (const wxString &uri)
	Constructor for quick creation.
	wxURI (const wxURI &uri)
	Copies this URI from another URI.
wxString	BuildURI () const
	Builds the URI from its individual components and adds proper separators.
wxString	BuildUnescapedURI () const
	Builds the URI from its individual components, adds proper separators, and returns escape sequences to normal characters.
bool	Create (const wxString &uri)
	Creates this URI from the uri string.
const wxString &	GetFragment () const
	Obtains the fragment of this URI.
wxURIHostType	GetHostType () const
	Obtains the host type of this URI, which is one of wxURIHostType.
wxString	GetPassword () const
	Returns the password part of the userinfo component of this URI.
const wxString &	GetPath () const
	Returns the (normalized) path of the URI.
const wxString &	GetPort () const
	Returns a string representation of the URI's port.
const wxString &	GetQuery () const
	Returns the Query component of the URI.
const wxString &	GetScheme () const
	Returns the Scheme component of the URI.
const wxString &	GetServer () const
	Returns the Server component of the URI.
wxString	GetUser () const
	Returns the username part of the userinfo component of this URI.
const wxString &	GetUserInfo () const
	Returns the UserInfo component of the URI.
bool	HasFragment () const
	Returns true if the Fragment component of the URI exists.
bool	HasPath () const
	Returns true if the Path component of the URI exists.
bool	HasPort () const
	Returns true if the Port component of the URI exists.
bool	HasQuery () const
	Returns true if the Query component of the URI exists.
bool	HasScheme () const
	Returns true if the Scheme component of the URI exists.
bool	HasServer () const
	Returns true if the Server component of the URI exists.
bool	HasUserInfo () const
	Returns true if the User component of the URI exists.
bool	IsReference () const
	Returns true if a valid [absolute] URI, otherwise this URI is a URI reference and not a full URI, and this function returns false.
void	Resolve (const wxURI &base, int flags=wxURI_STRICT)
	Inherits this URI from a base URI - components that do not exist in this URI are copied from the base, and if this URI's path is not an absolute path (prefixed by a '/'), then this URI's path is merged with the base's path.
bool	operator== (const wxURI &uricomp) const
	Compares this URI to another URI, and returns true if this URI equals uricomp, otherwise it returns false.
Public Member Functions inherited from wxObject
	wxObject ()
	Default ctor; initializes to NULL the internal reference data.
	wxObject (const wxObject &other)
	Copy ctor.
virtual	~wxObject ()
	Destructor.
virtual wxClassInfo *	GetClassInfo () const
	This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar).
wxObjectRefData *	GetRefData () const
	Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
bool	IsKindOf (const wxClassInfo *info) const
	Determines whether this class is a subclass of (or the same class as) the given class.
bool	IsSameAs (const wxObject &obj) const
	Returns true if this object has the same data pointer as obj.
void	Ref (const wxObject &clone)
	Makes this object refer to the data in clone.
void	SetRefData (wxObjectRefData *data)
	Sets the wxObject::m_refData pointer.
void	UnRef ()
	Decrements the reference count in the associated data, and if it is zero, deletes the data.
void	UnShare ()
	This is the same of AllocExclusive() but this method is public.
void	operator delete (void *buf)
	The delete operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.
void *	operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
	The new operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.

Static Public Member Functions
static wxString	Unescape (const wxString &uri)
	Translates all escape sequences (normal characters and returns the result.

Additional Inherited Members
Protected Member Functions inherited from wxObject
void	AllocExclusive ()
	Ensure that this object's data is not shared with any other object.
virtual wxObjectRefData *	CreateRefData () const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it.
virtual wxObjectRefData *	CloneRefData (const wxObjectRefData *data) const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data.
Protected Attributes inherited from wxObject
wxObjectRefData *	m_refData
	Pointer to an object which is the object's reference-counted data.

Constructor & Destructor Documentation

wxURI::wxURI

(

)

Creates an empty URI.

wxURI::wxURI

(

const wxString &

uri

)

Constructor for quick creation.

Parameters

uri	URI (Uniform Resource Identifier) to initialize with.

wxURI::wxURI

(

const wxURI &

uri

)

Copies this URI from another URI.

Parameters

uri	URI (Uniform Resource Identifier) to initialize with.

Member Function Documentation

wxString wxURI::BuildUnescapedURI

(

)

const

Builds the URI from its individual components, adds proper separators, and returns escape sequences to normal characters.

Note

It is preferred to call this over Unescape(BuildURI()) since BuildUnescapedURI() performs some optimizations over the plain method.

wxString wxURI::BuildURI

(

)

const

Builds the URI from its individual components and adds proper separators.

If the URI is not a reference or is not resolved, the URI that is returned is the same one passed to the constructor or Create().

bool wxURI::Create

(

const wxString &

uri

)

Creates this URI from the uri string.

Returns true if this instance was correctly initialized.

Parameters

uri	String to initialize from.

const wxString& wxURI::GetFragment

(

)

const

Obtains the fragment of this URI.

The fragment of a URI is the last value of the URI, and is the value after a "#" character after the path of the URI.

"http://mysite.com/mypath#<fragment>"

wxURIHostType wxURI::GetHostType

(

)

const

Obtains the host type of this URI, which is one of wxURIHostType.

wxString wxURI::GetPassword

(

)

const

Returns the password part of the userinfo component of this URI.

Note that this is explicitly depreciated by RFC 1396 and should generally be avoided if possible.

"http://<user>:<password>@mysite.com/mypath"

const wxString& wxURI::GetPath

(

)

const

Returns the (normalized) path of the URI.

The path component of a URI comes directly after the scheme component if followed by zero or one slashes ('/'), or after the server/port component.

Absolute paths include the leading '/' character.

"http://mysite.com<path>"

const wxString& wxURI::GetPort

(

)

const

Returns a string representation of the URI's port.

The Port of a URI is a value after the server, and must come after a colon (:).

"http://mysite.com:<port>"

Note

You can easily get the numeric value of the port by using wxAtoi() or wxString::Format().

const wxString& wxURI::GetQuery

(

)

const

Returns the Query component of the URI.

The query component is what is commonly passed to a cgi application, and must come after the path component, and after a '?' character.

"http://mysite.com/mypath?<query>"

const wxString& wxURI::GetScheme

(

)

const

Returns the Scheme component of the URI.

The first part of the URI.

"<scheme>://mysite.com"

const wxString& wxURI::GetServer

(

)

const

Returns the Server component of the URI.

The server of the URI can be a server name or a type of IP address. See GetHostType() for the possible values for the host type of the server component.

"http://<server>/mypath"

wxString wxURI::GetUser

(

)

const

Returns the username part of the userinfo component of this URI.

Note that this is explicitly depreciated by RFC 1396 and should generally be avoided if possible.

"http://<user>:<password>@mysite.com/mypath"

const wxString& wxURI::GetUserInfo

(

)

const

Returns the UserInfo component of the URI.

The component of a URI before the server component that is postfixed by a '@' character.

"http://<userinfo>@mysite.com/mypath"

bool wxURI::HasFragment

(

)

const

Returns true if the Fragment component of the URI exists.

bool wxURI::HasPath

(

)

const

Returns true if the Path component of the URI exists.

bool wxURI::HasPort

(

)

const

Returns true if the Port component of the URI exists.

bool wxURI::HasQuery

(

)

const

Returns true if the Query component of the URI exists.

bool wxURI::HasScheme

(

)

const

Returns true if the Scheme component of the URI exists.

bool wxURI::HasServer

(

)

const

Returns true if the Server component of the URI exists.

bool wxURI::HasUserInfo

(

)

const

Returns true if the User component of the URI exists.

bool wxURI::IsReference

(

)

const

Returns true if a valid [absolute] URI, otherwise this URI is a URI reference and not a full URI, and this function returns false.

bool wxURI::operator==

(

const wxURI &

uricomp

)

const

Compares this URI to another URI, and returns true if this URI equals uricomp, otherwise it returns false.

Parameters

uricomp

URI to compare to.

void wxURI::Resolve	(	const wxURI &	base,
		int	flags = wxURI_STRICT
	)

Inherits this URI from a base URI - components that do not exist in this URI are copied from the base, and if this URI's path is not an absolute path (prefixed by a '/'), then this URI's path is merged with the base's path.

For instance, resolving "../mydir" from "http://mysite.com/john/doe" results in the scheme (http) and server ("mysite.com") being copied into this URI, since they do not exist. In addition, since the path of this URI is not absolute (does not begin with '/'), the path of the base's is merged with this URI's path, resulting in the URI "http://mysite.com/john/mydir".

Parameters

base	Base URI to inherit from. Must be a full URI and not a reference.
flags	Currently either wxURI_STRICT or 0, in non-strict mode some compatibility layers are enabled to allow loopholes from RFCs prior to 2396.

static wxString wxURI::Unescape ( const wxString &  uri )

static

Translates all escape sequences (normal characters and returns the result.

If you want to unescape an entire wxURI, use BuildUnescapedURI() instead, as it performs some optimizations over this method.

Parameters

uri	String with escaped characters to convert.