uri Class

Article
12/06/2014

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.

Warning

This topic contains information for the C++ REST SDK 1.0 (codename "Casablanca"). If you are using a later version from the Codeplex Casablanca web page, then use the local documentation at https://casablanca.codeplex.com/documentation.

class uri;

Members

Public Classes

Name	Description
uri::components Class	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. Scheme and port don't allow '%' so they don't need to be encoded.

Public Constructors

Name	Description
uri::uri Constructor	Overloaded. Creates an empty uri

Public Methods

Name	Description
uri::authority Method	Creates a new uri object with the same authority portion as this one, omitting the resource and query portions.
uri::decode Method	Decodes an encoded string.
uri::encode_data_string Method	Encodes a string by converting all characters except for RFC 3986 unreserved characters to their hexadecimal representation.
uri::encode_uri Method	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.
uri::fragment Method	Get the fragment component of the URI as an encoded string.
uri::has_same_authority Method	Returns whether the other uri has the same authority as this one
uri::host Method	Get the host component of the URI as an encoded string.
uri::is_authority Method	An "authority" uri is one with only a scheme, optional userinfo, hostname, and (optional) port.
uri::is_empty Method	An empty uri specifies no components, and serves as a default value
uri::is_host_loopback Method	A loopback URI is one which refers to a hostname or ip address with meaning only on the local machine.
uri::is_host_portable Method	A portable URI is one with a hostname that can be resolved globally (used from another machine).
uri::is_host_wildcard Method	A wildcard URI is one which refers to all hostnames that resolve to the local machine (using the * or +)
uri::is_path_empty Method	Returns whether the path portion of this uri is empty
uri::is_port_default Method
uri::path Method	Get the path component of the URI as an encoded string.
uri::port Method	Get the port component of the URI. Returns -1 if no port is specified.
uri::query Method	Get the query component of the URI as an encoded string.
uri::resource Method	Gets the path, query, and fragment portion of this uri, which may be empty.
uri::scheme Method	Get the scheme component of the URI as an encoded string.
uri::split_path Method	Splits a path into its hierarchical components.
uri::split_query Method	Splits a query into its key-value components.
uri::to_string Method	Returns the full (encoded) uri as a string.
uri::user_info Method	Get the user information component of the URI as an encoded string.
uri::validate Method	Validates a string as a uri.

Public Operators

Name	Description
uri::operator!= Operator
uri::operator< Operator
uri::operator== Operator

Remarks

This implementation accepts both uris ('https://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: 'https://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 'https://msn.com', 'https://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.

Requirements

Header: base_uri.h

Namespace: web::http