A flexible, protocol independent URI implementation. More...

#include <base_uri.h>

Classes
class	components
	The various components of a URI. This enum is used to indicate which URI component is being encoded to the encode_uri_component. This allows specific encoding to be performed. More...

Public Member Functions
	uri ()
	Creates an empty uri More...

_ASYNCRTIMP	uri (const utility::char_t *uri_string)
	Creates a URI from the given encoded string. This will throw an exception if the string does not contain a valid URI. Use uri::validate if processing user-input. More...

_ASYNCRTIMP	uri (const utility::string_t &uri_string)
	Creates a URI from the given encoded string. This will throw an exception if the string does not contain a valid URI. Use uri::validate if processing user-input. More...

	uri (const uri &other)
	Copy constructor. More...

uri &	operator= (const uri &other)
	Copy assignment operator. More...

	uri (uri &&other) CPPREST_NOEXCEPT
	Move constructor. More...

uri &	operator= (uri &&other) CPPREST_NOEXCEPT
	Move assignment operator More...

const utility::string_t &	scheme () const
	Get the scheme component of the URI as an encoded string. More...

const utility::string_t &	user_info () const
	Get the user information component of the URI as an encoded string. More...

const utility::string_t &	host () const
	Get the host component of the URI as an encoded string. More...

int	port () const
	Get the port component of the URI. Returns -1 if no port is specified. More...

const utility::string_t &	path () const
	Get the path component of the URI as an encoded string. More...

const utility::string_t &	query () const
	Get the query component of the URI as an encoded string. More...

const utility::string_t &	fragment () const
	Get the fragment component of the URI as an encoded string. More...

_ASYNCRTIMP uri	authority () const
	Creates a new uri object with the same authority portion as this one, omitting the resource and query portions. More...

_ASYNCRTIMP uri	resource () const
	Gets the path, query, and fragment portion of this uri, which may be empty. More...

bool	is_empty () const
	An empty URI specifies no components, and serves as a default value More...

bool	is_host_loopback () const
	A loopback URI is one which refers to a hostname or ip address with meaning only on the local machine. More...

bool	is_host_wildcard () const
	A wildcard URI is one which refers to all hostnames that resolve to the local machine (using the * or +) More...

bool	is_host_portable () const
	A portable URI is one with a hostname that can be resolved globally (used from another machine). More...

bool	is_port_default () const

bool	is_authority () const
	An "authority" URI is one with only a scheme, optional userinfo, hostname, and (optional) port. More...

bool	has_same_authority (const uri &other) const
	Returns whether the other URI has the same authority as this one More...

bool	is_path_empty () const
	Returns whether the path portion of this URI is empty More...

utility::string_t	to_string () const
	Returns the full (encoded) URI as a string. More...

_ASYNCRTIMP bool	operator== (const uri &other) const

bool	operator< (const uri &other) const

bool	operator!= (const uri &other) const

Static Public Member Functions
static _ASYNCRTIMP utility::string_t __cdecl	encode_uri (const utility::string_t &raw, uri::components::component=components::full_uri)
	Encodes a URI component according to RFC 3986. Note if a full URI is specified instead of an individual URI component all characters not in the unreserved set are escaped. More...

static _ASYNCRTIMP utility::string_t __cdecl	encode_data_string (const utility::string_t &utf8data)
	Encodes a string by converting all characters except for RFC 3986 unreserved characters to their hexadecimal representation. More...

static _ASYNCRTIMP utility::string_t __cdecl	decode (const utility::string_t &encoded)
	Decodes an encoded string. More...

static _ASYNCRTIMP std::vector< utility::string_t > __cdecl	split_path (const utility::string_t &path)
	Splits a path into its hierarchical components. More...

static _ASYNCRTIMP std::map< utility::string_t, utility::string_t > __cdecl	split_query (const utility::string_t &query)
	Splits a query into its key-value components. More...

static _ASYNCRTIMP bool __cdecl	validate (const utility::string_t &uri_string)
	Validates a string as a URI. More...

Friends
class	uri_builder

Detailed Description

A flexible, protocol independent URI implementation.

URI instances are immutable. Querying the various fields on an emtpy URI will return empty strings. Querying various diagnostic members on an empty URI will return false.

This implementation accepts both URIs ('http://msn.com/path') and URI relative-references ('/path?query::frag').

This implementation does not provide any scheme-specific handling – an example of this would be the following: 'http://path1/path'. This is a valid URI, but it's not a valid http-uri – that is, it's syntactically correct but does not conform to the requirements of the http scheme (http requires a host). We could provide this by allowing a pluggable 'scheme' policy-class, which would provide extra capability for validating and canonicalizing a URI according to scheme, and would introduce a layer of type-safety for URIs of differing schemes, and thus differing semantics.

One issue with implementing a scheme-independent URI facility is that of comparing for equality. For instance, these URIs are considered equal 'http://msn.com', 'http://msn.com:80'. That is – the 'default' port can be either omitted or explicit. Since we don't have a way to map a scheme to it's default port, we don't have a way to know these are equal. This is just one of a class of issues with regard to scheme-specific behavior.

Constructor & Destructor Documentation

web::uri::uri ( )

inline

Creates an empty uri

_ASYNCRTIMP web::uri::uri ( const utility::char_t * uri_string )

Creates a URI from the given encoded string. This will throw an exception if the string does not contain a valid URI. Use uri::validate if processing user-input.

Parameters

uri_string A pointer to an encoded string to create the URI instance.

_ASYNCRTIMP web::uri::uri ( const utility::string_t & uri_string )

Creates a URI from the given encoded string. This will throw an exception if the string does not contain a valid URI. Use uri::validate if processing user-input.

Parameters

uri_string An encoded URI string to create the URI instance.

web::uri::uri ( const uri & other )

inline

Copy constructor.

web::uri::uri ( uri && other )

inline

Move constructor.

Member Function Documentation

_ASYNCRTIMP uri web::uri::authority ( ) const

Creates a new uri object with the same authority portion as this one, omitting the resource and query portions.

Returns: The new uri object with the same authority.

static _ASYNCRTIMP utility::string_t __cdecl web::uri::decode ( const utility::string_t & encoded )

static

Decodes an encoded string.

Parameters

encoded The URI as a string.

Returns: The decoded string.

static _ASYNCRTIMP utility::string_t __cdecl web::uri::encode_data_string ( const utility::string_t & utf8data )

static

Encodes a string by converting all characters except for RFC 3986 unreserved characters to their hexadecimal representation.

Parameters

utf8data The UTF-8 string data.

Returns: The encoded string.

static _ASYNCRTIMP utility::string_t __cdecl web::uri::encode_uri	(	const utility::string_t &	raw,
		uri::components::component	= `components::full_uri`
	)

static

Encodes a URI component according to RFC 3986. Note if a full URI is specified instead of an individual URI component all characters not in the unreserved set are escaped.

Parameters

raw	The URI as a string.

Returns: The encoded string.

const utility::string_t& web::uri::fragment ( ) const

inline

Get the fragment component of the URI as an encoded string.

Returns: The URI fragment as a string.

bool web::uri::has_same_authority ( const uri & other ) const

inline

Returns whether the other URI has the same authority as this one

Parameters

other The URI to compare the authority with.

Returns: true if both the URI's have the same authority, false otherwise.

const utility::string_t& web::uri::host ( ) const

inline

Get the host component of the URI as an encoded string.

Returns: The URI host as a string.

bool web::uri::is_authority ( ) const

inline

An "authority" URI is one with only a scheme, optional userinfo, hostname, and (optional) port.

Returns: true if this is an "authority" URI, false otherwise.

bool web::uri::is_empty ( ) const

inline

An empty URI specifies no components, and serves as a default value

bool web::uri::is_host_loopback ( ) const

inline

A loopback URI is one which refers to a hostname or ip address with meaning only on the local machine.

Examples include "locahost", or ip addresses in the loopback range (127.0.0.0/24).

Returns: true if this URI references the local host, false otherwise.

bool web::uri::is_host_portable ( ) const

inline

A portable URI is one with a hostname that can be resolved globally (used from another machine).

Returns: true if this URI can be resolved globally (used from another machine), false otherwise.

The hostname "localhost" is a reserved name that is guaranteed to resolve to the local machine, and cannot be used for inter-machine communication. Likewise the hostnames "*" and "+" on Windows represent wildcards, and do not map to a resolvable address.

bool web::uri::is_host_wildcard ( ) const

inline

A wildcard URI is one which refers to all hostnames that resolve to the local machine (using the * or +)

http://*:80

bool web::uri::is_path_empty ( ) const

inline

Returns whether the path portion of this URI is empty

Returns: true if the path portion of this URI is empty, false otherwise.

bool web::uri::is_port_default ( ) const

inline

A default port is one where the port is unspecified, and will be determined by the operating system. The choice of default port may be dictated by the scheme (http -> 80) or not.

Returns: true if this URI instance has a default port, false otherwise.

uri& web::uri::operator= ( const uri & other )

inline

Copy assignment operator.

uri& web::uri::operator= ( uri && other )

inline

Move assignment operator

const utility::string_t& web::uri::path ( ) const

inline

Get the path component of the URI as an encoded string.

Returns: The URI path as a string.

int web::uri::port ( ) const

inline

Get the port component of the URI. Returns -1 if no port is specified.

Returns: The URI port as an integer.

const utility::string_t& web::uri::query ( ) const

inline

Get the query component of the URI as an encoded string.

Returns: The URI query as a string.

_ASYNCRTIMP uri web::uri::resource ( ) const

Gets the path, query, and fragment portion of this uri, which may be empty.

Returns: The new URI object with the path, query and fragment portion of this URI.

const utility::string_t& web::uri::scheme ( ) const

inline

Get the scheme component of the URI as an encoded string.

Returns: The URI scheme as a string.

static _ASYNCRTIMP std::vector<utility::string_t> __cdecl web::uri::split_path ( const utility::string_t & path )

static

Splits a path into its hierarchical components.

Parameters

path	The path as a string

Returns: A std::vector<utility::string_t> containing the segments in the path.

static _ASYNCRTIMP std::map<utility::string_t, utility::string_t> __cdecl web::uri::split_query ( const utility::string_t & query )

static

Splits a query into its key-value components.

Parameters

query The query string

Returns: A std::map<utility::string_t, utility::string_t> containing the key-value components of the query.

utility::string_t web::uri::to_string ( ) const

inline

Returns the full (encoded) URI as a string.

Returns: The full encoded URI string.

const utility::string_t& web::uri::user_info ( ) const

inline

Get the user information component of the URI as an encoded string.

Returns: The URI user information as a string.

static _ASYNCRTIMP bool __cdecl web::uri::validate ( const utility::string_t & uri_string )

static

Validates a string as a URI.

Parameters

uri_string The URI string to be validated.

Returns: true if the given string represents a valid URI, false otherwise.

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

include/cpprest/base_uri.h

Classes

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation