prtx::URIUtils Namespace Reference

Description

A collection of utility functions which create or operate on prtx::URI instances.

Functions
URIPtr	addFragment (const URIPtr &uri, const std::wstring &key, const std::wstring &value)
URIPtr	addFragment (const URIPtr &uri, const std::map< std::wstring, std::wstring > &fragments)
URIPtr	addFragment (const URIPtr &uri, const std::wstring &fragment)
URIPtr	addQuery (const URIPtr &uri, const std::wstring &key, const std::wstring &value)
URIPtr	addQuery (const URIPtr &uri, const std::map< std::wstring, std::wstring > &queries)
URIPtr	addQuery (const URIPtr &uri, const std::wstring &query)
URIPtr	createBuiltinURI (const std::wstring &name)
URIPtr	createCompositeURI (const URIPtr &nestedURI, const std::wstring &outerScheme, const std::wstring &outerPath, const std::wstring &outerQuery={}, const std::wstring &outerFragment={})
URIPtr	createDataURI (const std::string &mediaType, bool base64, const uint8_t *data, size_t dataSize)
URIPtr	createFileURI (const std::wstring &percentEncodedAbsolutePath)
URIPtr	createMemoryURI (const uint8_t *ptr, size_t size, const std::wstring &ext)
uint64_t	getUniqueId ()
void	parseMemoryURI (const URIPtr &uri, const uint8_t *&address, size_t &byteCount)
std::string	percentDecode (const std::string &percentEncodedString)
std::string	percentEncode (const std::string &s)
std::wstring	percentEncode (const std::wstring &s)
URIPtr	removeFragment (const URIPtr &uri)
URIPtr	removeQuery (const URIPtr &uri)
URIPtr	replaceExtension (const URIPtr &uri, const std::wstring &newExtWithSep)
URIPtr	replaceFilename (const URIPtr &uri, const std::wstring &newFileName)

Function Documentation

addFragment() [1/3]

URIPtr prtx::URIUtils::addFragment	(	const URIPtr &	uri,
		const std::wstring &	key,
		const std::wstring &	value
	)

Appends to the fragment part in the form "[&]key=value" and returns a new URI instance.

Note: Key and value must be UTF-16 encoded and not contain percent-encoded characters.

addFragment() [2/3]

URIPtr prtx::URIUtils::addFragment	(	const URIPtr &	uri,
		const std::map< std::wstring, std::wstring > &	fragments
	)

Appends to the fragment part in the form "[&]key=value" and returns a new URI instance.

Note: The map entries are used as key and value and must be UTF-16 encoded and not contain percent-encoded characters.

addFragment() [3/3]

URIPtr prtx::URIUtils::addFragment	(	const URIPtr &	uri,
		const std::wstring &	fragment
	)

Appends a complete fragment of the form "key=value[&key1=value1&...]" and returns a new URI instance.

Note: The fragment string must be UTF-16 encoded and not contain percent-encoded characters.

addQuery() [1/3]

URIPtr prtx::URIUtils::addQuery	(	const URIPtr &	uri,
		const std::wstring &	key,
		const std::wstring &	value
	)

Appends to the query part in the form "[&]key=value" and returns a new URI instance.

Note: Key and value must be UTF-16 encoded and not contain percent-encoded characters.

addQuery() [2/3]

URIPtr prtx::URIUtils::addQuery	(	const URIPtr &	uri,
		const std::map< std::wstring, std::wstring > &	queries
	)

Appends to the query part in the form "[&]key=value" and returns a new URI instance.

Note: The map entries are used as key and value and must be UTF-16 encoded and not contain percent-encoded characters.

addQuery() [3/3]

URIPtr prtx::URIUtils::addQuery	(	const URIPtr &	uri,
		const std::wstring &	query
	)

Appends a complete query part and returns a new URI instance.

Note: The query string must be UTF-16 encoded and not contain percent-encoded characters.

createBuiltinURI()

URIPtr prtx::URIUtils::createBuiltinURI

(

const std::wstring &

name

)

Factory call to create a builtin uri, e.g. "builtin:default"

Parameters

name	name is expected to be an percent-encoded UTF8 string

createCompositeURI()

URIPtr prtx::URIUtils::createCompositeURI	(	const URIPtr &	nestedURI,
		const std::wstring &	outerScheme,
		const std::wstring &	outerPath,
		const std::wstring &	outerQuery = {},
		const std::wstring &	outerFragment = {}
	)

Creates a composite URI from a nested/inner URI and outer components in the following manner: <outerScheme>:<nestedURI>!<outerPath>[?<outerQuery>#<outerFragment>] outerQuery and outerFragment are optional.

Parameters

outerScheme	Must be non-empty, percent encoded and not end with a colon (:).
outerPath	Must be non-empty, percent encoded and start with a forward slash.
outerQuery	Optional, must be percent encoded.
outerFragment	Optional, must be percent encoded.

createDataURI()

URIPtr prtx::URIUtils::createDataURI	(	const std::string &	mediaType,
		bool	base64,
		const uint8_t *	data,
		size_t	dataSize
	)

Factory call to create a data URI according to http://tools.ietf.org/html/rfc2397. The URI follows the syntax 'data:<mediatype>[;base64],<data>'

Parameters

mediaType	The MIME type of the data.
base64	If true, the data will be base64 encoded. If false, the data is expected to be a percent-encoded, null-terminated ASCII string.
dataSize	Number of bytes in data.

Returns

The data URI.

createFileURI()

URIPtr prtx::URIUtils::createFileURI

(

const std::wstring &

percentEncodedAbsolutePath

)

Factory call to create an absolute file system URI, e.g. "file:/my/path/file.txt" NOTE: for paths starting with windows drive letters (e.g. P:/tmp), a slash is prepended if necessary.

Parameters

absolutePath

absolutePath is expected to be an percent-encoded UTF8 string

createMemoryURI()

URIPtr prtx::URIUtils::createMemoryURI	(	const uint8_t *	ptr,
		size_t	size,
		const std::wstring &	ext
	)

Factory call to create an URI from a memory block, e.g. "memory://ffa09/5.ext", i.e. the address is stored in the <host> component, the byte count is stored in the <path> component. will throw std::invalid_argument if the <host> and <path> component contain unexpected values.

Parameters

ext	is expected to be an percent-encoded UTF8 string

getUniqueId()

uint64_t prtx::URIUtils::getUniqueId

(

)

Utility function to get a unique id. Can be used to uniquify a memory URI. Guaranteed to be unique over the PRT process lifetime.

parseMemoryURI()

void prtx::URIUtils::parseMemoryURI	(	const URIPtr &	uri,
		const uint8_t *&	address,
		size_t &	byteCount
	)

Tries to parse an URI according to the memory URI syntax (memory:/<address hex>="">/<byte count="" hex>="">) into address and byte count.

Exceptions

std::invalid_argument

If the URI cannot be parsed.

Parameters

[in]	uri	The URI to be parsed as memory URI. Must be valid, else an exception is thrown.
[out]	address	Receives the address stored in the memory URI.
[out]	byteCount	Receives the byte count specified by the memory URI.

percentDecode()

std::string prtx::URIUtils::percentDecode

(

const std::string &

percentEncodedString

)

Utility function to percent decode a string according to RFC3986.

Returns

An UTF-8 encoded string.

percentEncode() [1/2]

std::string prtx::URIUtils::percentEncode

(

const std::string &

s

)

Utility function to percent encode a string according to RFC3986.

Parameters

s	An UTF-8 encoded string.

percentEncode() [2/2]

std::wstring prtx::URIUtils::percentEncode

(

const std::wstring &

s

)

Utility function to percent encode an UTF-16 string according to RFC3986. NOTE: s will be converted to UTF-8 first (as required by the RFC).

removeFragment()

URIPtr prtx::URIUtils::removeFragment

(

const URIPtr &

uri

)

Returns a copy of the URI with the the whole fragment component removed. If uri does not contain any fragment component, it is returned as-is.

removeQuery()

URIPtr prtx::URIUtils::removeQuery

(

const URIPtr &

uri

)

Returns a copy of the URI with the the whole query component removed. If uri does not contain any query component, it is returned as-is.

replaceExtension()

URIPtr prtx::URIUtils::replaceExtension	(	const URIPtr &	uri,
		const std::wstring &	newExtWithSep
	)

Returns a copy where the extension in the path component has been replaced with newExtWithSep (includes the separator).

Note: newFileName must be UTF-16 encoded and not contain percent-encoded characters.

replaceFilename()

URIPtr prtx::URIUtils::replaceFilename	(	const URIPtr &	uri,
		const std::wstring &	newFileName
	)

Returns a copy where the filename (= last segment of path) in the path component has been replaced with newFileName (includes the extension).

Note: newFileName must be UTF-16 encoded and not contain percent-encoded characters.