uri.hpp File Reference

Modify and parse URIs. More...

#include <UPnPsdk/visibility.hpp>

Include dependency graph for uri.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	token
	Buffer used in parsinghttp messages, urls, etc. Generally this simply holds a pointer into a larger array. More...
struct	hostport_type
	Represents a host port, e.g. "127.127.0.1:80". More...
struct	uri_type
	Represents a URI used in parse_uri and elsewhere. More...
struct	URL_list
	Represents a list of URLs as in the "callback" header of SUBSCRIBE message in GENA. More...

Namespaces
namespace	compa
	Refactored pupnp program code that is compatible to the original pupnp code.

Enumerations
enum struct	compa::uriType { Absolute , Relative }
	Type of the URI. More...
enum struct	compa::pathType { ABS_PATH , REL_PATH , OPAQUE_PART }
	Type of the "path" part of the URI. More...

Functions
UPnPsdk_VIS int	replace_escaped (char *in, size_t index, size_t *max)
	Replaces one single escaped character within a string with its unescaped version.
UPnPsdk_VIS int	copy_URL_list (URL_list *in, URL_list *out)
	Copies one URL_list into another.
UPnPsdk_VIS void	free_URL_list (URL_list *list)
	Frees the memory associated with a URL_list.
void	print_uri (uri_type *in)
	Function useful in debugging for printing a parsed uri.
void	print_token (token *in)
	Function useful in debugging for printing a token.
UPnPsdk_VIS int	token_string_casecmp (token *in1, const char *in2)
	Compares buffer in the token object with the buffer in in2 case insensitive.
UPnPsdk_VIS int	token_cmp (token *in1, token *in2)
	Compares two tokens.
UPnPsdk_VIS int	remove_escaped_chars (char *in, size_t *size)
	Removes http escaped characters such as: "%20" and replaces them with their character representation.
UPnPsdk_VIS int	remove_dots (char *buf, size_t size)
	Removes ".", and ".." from a path.
UPnPsdk_VIS char *	resolve_rel_url (char *base_url, char *rel_url)
	Resolves a relative url with a base url.
UPnPsdk_VIS int	parse_uri (const char *in, size_t max, uri_type *out)
	Parses a uri as defined in RFC 2396 (explaining URIs).
int	parse_token (char *in, token *out, int max_size)

Variables
constexpr int	HTTP_SUCCESS {1}
	Yet another success code.

Detailed Description

Modify and parse URIs.

Definition in file uri.hpp.

---

Class Documentation

token

struct token

Buffer used in parsinghttp messages, urls, etc. Generally this simply holds a pointer into a larger array.

Definition at line 76 of file uri.hpp.

Class Members
const char *	buff	Buffer.
size_t	size	Size of the buffer.

hostport_type

struct hostport_type

Represents a host port, e.g. "127.127.0.1:80".

Definition at line 84 of file uri.hpp.

Collaboration diagram for hostport_type:

Class Members
token	text	Pointing to the full host:port string representation.
sockaddr_storage	IPaddress	Network socket address.

uri_type

struct uri_type

Represents a URI used in parse_uri and elsewhere.

Definition at line 92 of file uri.hpp.

Collaboration diagram for uri_type:

Class Members
uriType	type	Member variable.
token	scheme	Member variable.
pathType	path_type	Member variable.
token	pathquery	Member variable.
token	fragment	Member variable.
hostport_type	hostport	Member variable.

URL_list

struct URL_list

Represents a list of URLs as in the "callback" header of SUBSCRIBE message in GENA.

Definition at line 108 of file uri.hpp.

Collaboration diagram for URL_list:

Class Members
size_t	size	size
char *	URLs	Dynamic memory for all urls, delimited by <>
uri_type *	parsedURLs	parsed URLs

Function Documentation

replace_escaped()

UPnPsdk_VIS int replace_escaped	(	char *	in,
		size_t	index,
		size_t *	max
	)

Replaces one single escaped character within a string with its unescaped version.

This is spezified in RFC 2396 (explaining URIs). The index must exactly point to the '%' character, otherwise the function will return unsuccessful. Size of array is NOT checked (MUST be checked by caller).

Note

This function modifies the string and the max size. If the sequence is an escaped sequence it is replaced, the other characters in the string are shifted over, and NULL characters are placed at the end of the string.

Returns

1 - if an escaped character was converted
0 - otherwise

Parameters

[in,out]	in	String of characters.
[in]	index	Index at which to start checking the characters; must point to ''.
[in,out]	max	Maximal size of the string buffer will be reduced by 2 if a character is converted.

Definition at line 396 of file uri.cpp.

Here is the caller graph for this function:

copy_URL_list()

UPnPsdk_VIS int copy_URL_list	(	URL_list *	in,
		URL_list *	out
	)

Copies one URL_list into another.

This includes dynamically allocating the out->URLs field (the full string), and the structures used to hold the parsedURLs. This memory MUST be freed by the caller through: free_URL_list(&out).

Returns

On success: HTTP_SUCCESS
On error: UPNP_E_OUTOF_MEMORY - On Failure to allocate memory.

Parameters

[in]	in	Source URL list.
[out]	out	Destination URL list.

Definition at line 431 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

free_URL_list()

UPnPsdk_VIS void free_URL_list

(

URL_list *

list

)

Frees the memory associated with a URL_list.

Frees the dynamically allocated members of of list. Does NOT free the pointer to the list itself ( i.e. does NOT free(list)).

Parameters

[in]

list

URL list object.

Definition at line 480 of file uri.cpp.

Here is the caller graph for this function:

print_uri()

void print_uri

(

uri_type *

in

)

Function useful in debugging for printing a parsed uri.

This is only available when compiled with DEBUG enabled.

Parameters

[in]

in

URI object to print.

Definition at line 492 of file uri.cpp.

Here is the call graph for this function:

print_token()

void print_token

(

token *

in

)

Function useful in debugging for printing a token.

This is only available when compiled with DEBUG enabled.

Parameters

[in]

in

Token object to print.

Definition at line 499 of file uri.cpp.

Here is the caller graph for this function:

token_string_casecmp()

UPnPsdk_VIS int token_string_casecmp	(	token *	in1,
		const char *	in2
	)

Compares buffer in the token object with the buffer in in2 case insensitive.

Returns

• < 0, if string1 is less than string2.
• == 0, if string1 is identical to string2 .
• > 0, if string1 is greater than string2.

Parameters

[in]	in1	Token object whose buffer is to be compared.
[in]	in2	String of characters to compare with.

Definition at line 510 of file uri.cpp.

Here is the caller graph for this function:

token_cmp()

UPnPsdk_VIS int token_cmp	(	token *	in1,
		token *	in2
	)

Compares two tokens.

Returns

• < 0, if string1 is less than string2.
• == 0, if string1 is identical to string2 .
• > 0, if string1 is greater than string2.

Parameters

[in]	in1	First token object whose buffer is to be compared.
[in]	in2	Second token object used for the comparison.

Definition at line 518 of file uri.cpp.

Here is the caller graph for this function:

remove_escaped_chars()

UPnPsdk_VIS int remove_escaped_chars	(	char *	in,
		size_t *	size
	)

Removes http escaped characters such as: "%20" and replaces them with their character representation.

For example: "hello%20foo" -> "hello foo". The input IS MODIFIED in place (shortened). Extra characters are replaced with NULL.

Returns

UPNP_E_SUCCESS.

Todo:

Optimize with prechecking the delimiter '%'.

Parameters

[in,out]	in	String of characters to be modified.
[in,out]	size	Size limit for the number of characters.

Definition at line 526 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

remove_dots()

UPnPsdk_VIS int remove_dots	(	char *	buf,
		size_t	size
	)

Removes ".", and ".." from a path.

If a ".." can not be resolved (i.e. the .. would go past the root of the path) an error is returned. The input IS modified in place. This function directly implements the "Remove Dot Segments" algorithm described in RFC 3986 section 5.2.4.

Examples:
 uchar path[30]="/../hello";
 uremove_dots(path, strlen(path)) -> UPNP_E_INVALID_URL
 uchar path[30]="/./hello";
 uremove_dots(path, strlen(path)) -> UPNP_E_SUCCESS,
 uin = "/hello"
 uchar path[30]="/./hello/foo/../goodbye" ->
 uUPNP_E_SUCCESS, in = "/hello/goodbye"

Returns

On success: UPNP_E_SUCCESS
On error:

• UPNP_E_OUTOF_MEMORY - On failure to allocate memory.
• UPNP_E_INVALID_URL - Failure to resolve URL.

Parameters

[in]	buf	String of characters from which "dots" have to be removed.
[in]	size	Size limit for the number of characters.

Definition at line 538 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_rel_url()

UPnPsdk_VIS char * resolve_rel_url	(	char *	base_url,
		char *	rel_url
	)

Resolves a relative url with a base url.

• If the base_url is a nullptr, then a copy of the rel_url is passed back.
• If the rel_url is absolute then a copy of the rel_url is passed back.
• If neither the base nor the rel_url are absolute then a nullptr is returned.
• Otherwise it tries and resolves the relative url with the base as described in RFC 2396 (explaining URIs).

The resolution of '..' is NOT implemented, but '.' is resolved.

Returns

Pointer to a new with malloc dynamically allocated full URL or a nullptr.

Parameters

[in]	base_url	Base URL.
[in]	rel_url	Relative URL.

Definition at line 605 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

parse_uri()

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

Parses a uri as defined in RFC 2396 (explaining URIs).

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

Parameters

[in]	in	Character string containing uri information to be parsed.
[in]	max	Number of characters (strlen()) of the input string.
[out]	out	Output parameter which will have the parsed uri information.

Definition at line 733 of file uri.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

parse_token()

int parse_token	(	char *	in,
		token *	out,
		int	max_size
	)

Returns

Parameters

[in]	in	.
[out]	out	.
[in]	max_size	.

Variable Documentation

HTTP_SUCCESS

constexpr int HTTP_SUCCESS {1}

inlineconstexpr

Yet another success code.

Definition at line 70 of file uri.hpp.