URI module

The URI module contains all classes and free functions to manage Uniform Resource Identifier (URI) as specified with RFC 3986. More...

Classes
class	UPnPsdk::CComponent
	Base class of a component. More...
class	UPnPsdk::CScheme
	Scheme component of a URI. More...
class	UPnPsdk::CUserinfo
	Userinfo subcomponent from an authority component of a URI reference. More...
class	UPnPsdk::CHost
	Host subcomponent from an authority component of a URI reference. More...
class	UPnPsdk::CPort
	Port subcomponent from an authority component of a URI reference. More...
class	UPnPsdk::CAuthority
	Authority component of a URI reference. More...
class	UPnPsdk::CPath
	Path component of a URI reference. More...
class	UPnPsdk::CQuery
	Query component of a URI reference. More...
class	UPnPsdk::CFragment
	Fragment component of a URI reference. More...
class	UPnPsdk::CPrepUriStr
	Internal class to prepare the input URI string, Not publicly usable. More...
class	UPnPsdk::CUriRef
	This is a URI reference. More...
class	UPnPsdk::CUri
	Representing a URI that can be modified with a relative reference. More...

Functions
UPnPsdk_VIS void	UPnPsdk::remove_dot_segments (std::string &a_path)
	Remove dot segments from a path.
	UPnPsdk::CPrepUriStr::CPrepUriStr (std::string &a_uriref_str)
	Initialize the helper class.
UPnPsdk_VIS int	parse_uri (const char *in, size_t max, uri_type *out)
	Parses a uri as defined in RFC 3986 (Uniform Resource Identifier).
bool	UPnPsdk::anonymous_namespace{uri.cpp}::is_ipv4_addr (const std::string &ip)
	Check if string is a valid IPv4 address.
bool	UPnPsdk::anonymous_namespace{uri.cpp}::is_dns_name (const std::string &label)
	Check if a string conforms to a DNS name.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_scheme (std::string_view a_uri_sv)
	Separates the scheme component from a URI.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_authority (std::string_view a_uriref_sv)
	Separates the authority component from a URI reference.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_userinfo (std::string_view a_uriref_sv)
	Separates the authority userinfo subcomponent from a URI reference.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_host (std::string_view a_uriref_sv)
	Separates the authority host subcomponent from a URI reference.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_port (std::string_view a_uriref_sv)
	Separates the authority port subcomponent from a URI reference.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_path (std::string_view a_uriref_sv)
	Separates the path component from a URI reference.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_query (std::string_view a_uriref_sv)
	Separates the query component from a URI reference.
std::string_view	UPnPsdk::anonymous_namespace{uri.cpp}::get_fragment (std::string_view a_uriref_sv)
	Separates the fragment component from a URI reference.
void	UPnPsdk::anonymous_namespace{uri.cpp}::merge_paths (CPath &a_path, const CUriRef &a_base, const CUriRef &a_rel)
	Merge a relative reference to a base URI.

Detailed Description

The URI module contains all classes and free functions to manage Uniform Resource Identifier (URI) as specified with RFC 3986.

It follows the recommendation of RFC 3986 4.1.:

‍A URI-reference is typically parsed first into the five URI components, in order to determine what components are present and whether the reference is relative.

All thrown exceptions from this module are std::invalid_argument.

Classes and Abstraction of the URI module

Abstraction layer 0

It is the UPnPsdk::CComponent class. It specifies the common properties of a component and is base class of every named component class.

All five named components scheme, authority with subcomponents userinfo and host and port, path, query, fragment have its own class that is derived from UPnPsdk::CComponent. They are all initialized by their constructors with the whole input URI string to ensure they all have the same source for parsing and extract its specific information as defined by RFC 3986. Their Attributes are protected so there is only access to them with "getter" member functions.

The constructor of a named component class always tries to extract its component from the input URI string and reflects it in its UPnPsdk::CComponent::STATE. No dependencies with other components are checked on this abstraction layer. Only conditions like valid characters etc. defined for the component are checked. For example no error is reported if a "http" URI does not have a host component available. This is checked on a higher abstraction layer that manage the dependencies of components.

Abstraction layer 1

This is the UPnPsdk::CUriRef class, the representation of a URI reference. Its member variables are named component objects. The constructor only verifies a URI. It always accepts a valid relative reference because that only makes sense together with a URI that is used as base URI for a relative reference. Verifying the relative reference is made on a higher abstraction layer that merges the base URI and the relative reference.

Abstraction layer 2

This is the UPnPsdk::CUri class. Its member variables are mainly two UPnPsdk::CUriRef objects for base URI and resulting target URI. The constructor initializes the base URI. The class accepts an optional relative reference and will then transform it with the base URI to a resulting target URI if it is valid.

Function Documentation

remove_dot_segments()

void UPnPsdk::remove_dot_segments

(

std::string &

a_path

)

Remove dot segments from a path.

This function directly implements the "Remove Dot Segments" algorithm described in RFC 3986 section 5.2.4. If it cannot find something to remove it just do nothing with the path.

Examples:

remove_dot_segments("/foo/./bar"); // results to "/foo/bar"
remove_dot_segments("/foo/../bar"); // results to "/bar"
remove_dot_segments("../bar"); // results to "bar"
remove_dot_segments("./bar"); // results to "bar"
remove_dot_segments(".../bar"); // results to ".../bar" (do nothing)
remove_dot_segments("/./hello/foo/../bar"); // results to "/hello/bar"

Parameters

[in,out]

a_path

Reference of a string representing a path with '/' separators and possible containing ".." or "." segments. The path is modified in place.

Definition at line 73 of file uri.cpp.

Here is the caller graph for this function:

CPrepUriStr()

UPnPsdk::CPrepUriStr::CPrepUriStr

(

std::string &

a_uriref_str

)

Initialize the helper class.

Normalize percent encoded characters of a URI reference string to upper case hex digits (RFC3986_2.1.)

Corrections are made in place. The size of the corrected string doesn't change.

Exceptions

std::invalid_argument

if invalid percent encoding is detected.

Parameters

[in]

a_uriref_str

Input URI string

Definition at line 866 of file uri.cpp.

parse_uri()

UPnPsdk_VIS int parse_uri	(	const char *	in,
		size_t	max,
		uri_type *	out
	)

Parses a uri as defined in RFC 3986 (Uniform Resource Identifier).

Handles absolute, relative, and opaque uris. Parses into the following pieces: scheme, hostport, pathquery, fragment (host with port and path with query are treated as one token). Strings in output uri_type are treated as token with character chain and size. They are not null ('\0') terminated.

Caller should check for the pieces they require.

Returns

On success: HTTP_SUCCESS
On error: UPNP_E_INVALID_URL, accessing out (arg3) then, is undefined behavior.

Parameters

[in]	in	Character string containing uri information to be parsed. It is not expected to be terminated with zero ('\0'), but may have.
[in]	max	Number of characters (strlen()) of the input string.
[out]	out	Output parameter which will have the parsed uri information.

Definition at line 1111 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

is_ipv4_addr()

bool UPnPsdk::anonymous_namespace{uri.cpp}::is_ipv4_addr

(

const std::string &

ip

)

Check if string is a valid IPv4 address.

This checks that the address consists of four octets, each ranging from 0 to 255, separated by dots.

Returns

true  if the input string is a valid IPv4 pattern. It's not resolved by DNS.
false otherwise

Parameters

[in]

ip

String to test.

Definition at line 39 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

is_dns_name()

bool UPnPsdk::anonymous_namespace{uri.cpp}::is_dns_name

(

const std::string &

label

)

Check if a string conforms to a DNS name.

Returns

true  if the input string is a valid DNS label. It's not resolved by DNS.
false otherwise

Parameters

[in]

label

String to test.

Definition at line 57 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_scheme()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_scheme

(

std::string_view

a_uri_sv

)

Separates the scheme component from a URI.

Returns

• An empty string_view if scheme is undefined.
• Only separator ':' if the scheme is empty.
• A valid scheme pattern that always ends with separator ':'.

Parameters

[in]

a_uri_sv

URI to parse

Definition at line 203 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_authority()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_authority

(

std::string_view

a_uriref_sv

)

Separates the authority component from a URI reference.

A sender MUST NOT generate an "http" URI with an empty host identifier. A recipient that processes such a URI reference MUST reject it as invalid (RFC7230 2.7.1.). This means an authority component is mandatory for "http[s]".

Returns

• An empty string_view if authority is undefined.
• Double slash ("//") if the authority is empty.
• A valid authority pattern that always starts with "//" but with no end separator.

Parameters

[in]

a_uriref_sv

URI reference to parse.

Definition at line 292 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_userinfo()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_userinfo

(

std::string_view

a_uriref_sv

)

Separates the authority userinfo subcomponent from a URI reference.

Returns

• An empty string_view if userinfo is undefined.
• Only separator ':' or '@' if the userinfo is empty.
• A valid userinfo pattern without any separator.

Parameters

[in]

a_uriref_sv

URI reference to parse

Definition at line 332 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_host()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_host

(

std::string_view

a_uriref_sv

)

Separates the authority host subcomponent from a URI reference.

Returns

• An empty string_view if host is undefined.
• Only a separator ':' or '/' or '?' or '#' if the host is empty.
• A valid host pattern without any separator.

Exceptions

std::invalid_argument

if URI reference with invalid host address or host name pattern is detected. No DNS lookup is performed.

Parameters

[in]

a_uriref_sv

URI reference to parse

Definition at line 419 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_port()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_port

(

std::string_view

a_uriref_sv

)

Separates the authority port subcomponent from a URI reference.

Returns

• An empty string_view if port is undefined.
• Only a separator ':' if the port is empty.
• A valid port pattern without any separator.

Exceptions

std::invalid_argument

if invalid port number is detected.

Parameters

[in]

a_uriref_sv

URI reference to parse

Definition at line 533 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_path()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_path

(

std::string_view

a_uriref_sv

)

Separates the path component from a URI reference.

Returns

• An empty string_view if the path is empty. A path is always defined for a URI (RFC3986 3.3).
• A valid path pattern without any separator.

Parameters

[in]

a_uriref_sv

URI reference to parse

Definition at line 669 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_query()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_query

(

std::string_view

a_uriref_sv

)

Separates the query component from a URI reference.

Returns

• An empty string_view if the query component is undefined.
• Only a separator "?" if the query component is empty.
• A valid query component pattern without any separator.

Parameters

[in]

a_uriref_sv

URI reference to parse

Definition at line 747 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_fragment()

std::string_view UPnPsdk::anonymous_namespace{uri.cpp}::get_fragment

(

std::string_view

a_uriref_sv

)

Separates the fragment component from a URI reference.

Returns

• An empty string_view if fragment component is undefined.
• Only a separator '#' if the fragment component is empty.
• A valid fragment component pattern without any separator.

Parameters

[in]

a_uriref_sv

URI reference to parse

Definition at line 816 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

merge_paths()

void UPnPsdk::anonymous_namespace{uri.cpp}::merge_paths	(	CPath &	a_path,
		const CUriRef &	a_base,
		const CUriRef &	a_rel
	)

Merge a relative reference to a base URI.

Parameters

[out]	a_path	Resulting merged paths object
[in]	a_base	base URI object
[in]	a_rel	Relative reference object

Definition at line 1001 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function: