A flexible, protocol independent URI implementation.
More...
#include <base_uri.h>
Classes
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
_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 (
uri &&other) CPPREST_NOEXCEPT
const utility::string_t &
scheme () const
Get the scheme component of the URI as an encoded string.
More...
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...
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...
Creates a new uri object with the same authority portion as this one, omitting the resource and query portions.
More...
Gets the path, query, and fragment portion of this uri, which may be empty.
More...
An empty URI specifies no components, and serves as a default value
More...
A loopback URI is one which refers to a hostname or ip address with meaning only on the local machine.
More...
A wildcard URI is one which refers to all hostnames that resolve to the local machine (using the * or +)
More...
A portable URI is one with a hostname that can be resolved globally (used from another machine).
More...
An "authority" URI is one with only a scheme, optional userinfo, hostname, and (optional) port.
More...
Returns whether the other URI has the same authority as this one
More...
Returns whether the path portion of this URI is empty
More...
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)
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
_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 )
web::uri::uri
(
uri &&
other )
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
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
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: