The App Control URI API provides functions for URI.

Required Header

#include <app_control_uri.h>

Overview

Provides functions to set/get/build URI data conform to RFC 3986.

Functions
int	app_control_uri_builder_create (app_control_uri_builder_h *handle)
	Creates a URI builder handle.
int	app_control_uri_builder_set_scheme (app_control_uri_builder_h handle, const char *scheme)
	Sets the scheme component.
int	app_control_uri_builder_set_authority (app_control_uri_builder_h handle, const char *auth)
	Sets the authority component.
int	app_control_uri_builder_set_path (app_control_uri_builder_h handle, const char *path)
	Sets the path component.
int	app_control_uri_builder_add_path (app_control_uri_builder_h handle, const char *path)
	Adds the path component.
int	app_control_uri_builder_set_fragment (app_control_uri_builder_h handle, const char *fragment)
	Sets the fragment identifier component.
int	app_control_uri_builder_add_query (app_control_uri_builder_h handle, const char key, const char val)
	Adds the key-value pair attribute of the query component.
int	app_control_uri_builder_build (app_control_uri_builder_h builder, app_control_uri_h *app_control_uri)
	Creates a URI handle with the attributes set by calling URI builder functions.
int	app_control_uri_builder_destroy (app_control_uri_builder_h handle)
	Destroys the URI builder handle.
int	app_control_uri_create (const char encoded_app_control_uri, app_control_uri_h handle)
	Creates a URI handle from an encoded URI string.
int	app_control_uri_destroy (app_control_uri_h handle)
	Destroys the URI handle.
int	app_control_uri_encode (app_control_uri_h handle, char **encoded_app_control_uri)
	Encodes the URI handle to string. The string is RFC 3986-compliant.
int	app_control_uri_get_scheme (app_control_uri_h handle, const char **scheme)
	Gets the scheme component from a URI handle.
int	app_control_uri_get_authority (app_control_uri_h handle, const char **auth)
	Gets the authority component from a URI handle.
int	app_control_uri_get_path (app_control_uri_h handle, const char **path)
	Gets the path component from a URI handle.
int	app_control_uri_get_fragment (app_control_uri_h handle, const char **fragment)
	Gets the fragment identifier component from a URI handle.
int	app_control_uri_get_query (app_control_uri_h handle, app_control_uri_query_h *query_handle)
	Gets the handle of the query component from a URI handle.
int	app_control_uri_get_host (app_control_uri_h handle, const char **host)
	Gets the host subcomponent from a URI handle.
int	app_control_uri_get_port (app_control_uri_h handle, const char **port)
	Gets the port subcomponent from a URI handle.
int	app_control_uri_get_user (app_control_uri_h handle, const char **user)
	Gets the user subcomponent from a URI handle.
int	app_control_uri_query_foreach (app_control_uri_query_h handle, app_control_uri_query_foreach_cb callback, void *user_data)
	Retrieves key-value pair attributes in the query component.
Typedefs
typedef void *	app_control_uri_builder_h
	The URI builder handle.
typedef void *	app_control_uri_h
	The URI handle.
typedef const void *	app_control_uri_query_h
	The query component handle of the URI.
typedef bool(*	app_control_uri_query_foreach_cb )(const char key, const char val, void *user_data)
	Called to retrieve key-value pair attributes contained in the query component.

Typedef Documentation

typedef void* app_control_uri_builder_h

The URI builder handle.

Since :: 5.5

typedef void* app_control_uri_h

The URI handle.

Since :: 5.5

typedef bool(* app_control_uri_query_foreach_cb)(const char *key, const char *val, void *user_data)

Called to retrieve key-value pair attributes contained in the query component.

Since :: 5.5

Remarks:: key and val must not be released. The platform will release them when the query object is released (see app_control_uri_get_query())

Parameters:

[in]	key	The name of the query component key-value pairs
[in]	val	The value associated with the given key
[in]	user_data	The user data passed from the foreach function

Returns:: true to continue with the next iteration of the loop, otherwise false to break out of the loop

See also:: app_control_uri_query_foreach()

typedef const void* app_control_uri_query_h

The query component handle of the URI.

Since :: 5.5

Enumeration Type Documentation

enum app_control_uri_error_e

Enumeration for error codes of the App Control URI submodule.

Since :: 5.5

Enumerator:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_IO_ERROR	Internal I/O error
APP_CONTROL_URI_ERROR_OUT_OF_MEMORY	Out of memory
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

Function Documentation

int app_control_uri_builder_add_path	(	app_control_uri_builder_h	handle,
		const char *	path
	)

Adds the path component.

Builder appends path component to the path. If path doesn't start with a '/', builder will prepend the given path with a '/'.

Since :: 5.5

Parameters:

[in]	handle	The URI builder handle
[in]	path	The path component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_builder_add_query	(	app_control_uri_builder_h	handle,
		const char *	key,
		const char *	val
	)

Adds the key-value pair attribute of the query component.

Since :: 5.5

Parameters:

[in]	handle	The URI builder handle
[in]	key	The name of the query component key-value pairs
[in]	val	The value associated with the given key

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_builder_build	(	app_control_uri_builder_h	builder,
		app_control_uri_h *	app_control_uri
	)

Creates a URI handle with the attributes set by calling URI builder functions.

Since :: 5.5

Remarks:: The app_control_uri should be released using app_control_uri_destroy().

Parameters:

[in]	builder	The URI builder handle
[out]	app_control_uri	The URI handle

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter
APP_CONTROL_URI_ERROR_OUT_OF_MEMORY	Out of memory

int app_control_uri_builder_create ( app_control_uri_builder_h * handle )

Creates a URI builder handle.

Since :: 5.5

Remarks:: The handle should be released using app_control_uri_builder_destroy().

Parameters:

[out] handle The URI builder handle

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter
APP_CONTROL_URI_ERROR_OUT_OF_MEMORY	Out of memory

See also:: app_control_uri_builder_destroy()

int app_control_uri_builder_destroy ( app_control_uri_builder_h handle )

Destroys the URI builder handle.

Since :: 5.5

Parameters:

[in] handle The URI builder handle

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_builder_set_authority	(	app_control_uri_builder_h	handle,
		const char *	auth
	)

Sets the authority component.

Since :: 5.5

Parameters:

[in]	handle	The URI builder handle
[in]	auth	The authority component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_builder_set_fragment	(	app_control_uri_builder_h	handle,
		const char *	fragment
	)

Sets the fragment identifier component.

Since :: 5.5

Parameters:

[in]	handle	The URI builder handle
[in]	fragment	The fragment identifier component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_builder_set_path	(	app_control_uri_builder_h	handle,
		const char *	path
	)

Sets the path component.

If the path was already set, it will be replaced with path.

Since :: 5.5

Parameters:

[in]	handle	The URI builder handle
[in]	path	The path component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_builder_set_scheme	(	app_control_uri_builder_h	handle,
		const char *	scheme
	)

Sets the scheme component.

Since :: 5.5

Parameters:

[in]	handle	The URI builder handle
[in]	scheme	The scheme component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_create	(	const char *	encoded_app_control_uri,
		app_control_uri_h *	handle
	)

Creates a URI handle from an encoded URI string.

Since :: 5.5

Remarks:: The handle should be released using app_control_uri_destroy().

Parameters:

[in]	encoded_app_control_uri	The encoded URI string
[out]	handle	The URI handle

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter
APP_CONTROL_URI_ERROR_OUT_OF_MEMORY	Out of memory

See also:: app_control_uri_encode()

int app_control_uri_destroy ( app_control_uri_h handle )

Destroys the URI handle.

Since :: 5.5

Parameters:

[in] handle The URI handle

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_encode	(	app_control_uri_h	handle,
		char **	encoded_app_control_uri
	)

Encodes the URI handle to string. The string is RFC 3986-compliant.

Since :: 5.5

Remarks:: The encoded_app_control_uri URI string should be released using free().

Parameters:

[in]	handle	The URI handle
[out]	encoded_app_control_uri	The encoded URI string

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter
APP_CONTROL_URI_ERROR_OUT_OF_MEMORY	Out of memory

int app_control_uri_get_authority	(	app_control_uri_h	handle,
		const char **	auth
	)

Gets the authority component from a URI handle.

Since :: 5.5

Remarks:: The authority must not be released. The platform will release it when the App Control URI object containing it is released.

Parameters:

[in]	handle	The URI handle
[out]	auth	The authority component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_get_fragment	(	app_control_uri_h	handle,
		const char **	fragment
	)

Gets the fragment identifier component from a URI handle.

Since :: 5.5

Remarks:: The fragment must not be released. The platform will release it when the App Control URI object containing it is released.

Parameters:

[in]	handle	The URI handle
[out]	fragment	The fragment identifier component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_get_host	(	app_control_uri_h	handle,
		const char **	host
	)

Gets the host subcomponent from a URI handle.

Since :: 5.5

Remarks:: The host must not be released. The platform will release it when the App Control URI object containing it is released.

Parameters:

[in]	handle	The URI handle
[out]	host	The host subcomponent of authority

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_get_path	(	app_control_uri_h	handle,
		const char **	path
	)

Gets the path component from a URI handle.

Since :: 5.5

Remarks:: The path must not be released. The platform will release it when the App Control URI object containing it is released.

Parameters:

[in]	handle	The URI handle
[out]	path	The path component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_get_port	(	app_control_uri_h	handle,
		const char **	port
	)

Gets the port subcomponent from a URI handle.

Since :: 5.5

Remarks:: The port must not be released. The platform will release it when the App Control URI object containing it is released.

Parameters:

[in]	handle	The URI handle
[out]	port	The port subcomponent of authority

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_get_query	(	app_control_uri_h	handle,
		app_control_uri_query_h *	query_handle
	)

Gets the handle of the query component from a URI handle.

Since :: 5.5

Remarks:: The query_handle will be released by the platform when the App Control URI object which contains the query is released.

Parameters:

[in]	handle	The URI handle
[out]	query_handle	The query component handle of the URI

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_get_scheme	(	app_control_uri_h	handle,
		const char **	scheme
	)

Gets the scheme component from a URI handle.

Since :: 5.5

Remarks:: The scheme must not be released. The platform will release it when the App Control URI object containing it is released.

Parameters:

[in]	handle	The URI handle
[out]	scheme	The scheme component

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_get_user	(	app_control_uri_h	handle,
		const char **	user
	)

Gets the user subcomponent from a URI handle.

Since :: 5.5

Remarks:: The user must not be released. The platform will release it when the App Control URI object containing it is released.

Parameters:

[in]	handle	The URI handle
[out]	user	The user subcomponent of authority

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successfully
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

int app_control_uri_query_foreach	(	app_control_uri_query_h	handle,
		app_control_uri_query_foreach_cb	callback,
		void *	user_data
	)

Retrieves key-value pair attributes in the query component.

Since :: 5.5

Parameters:

[in]	handle	The query component handle of the URI
[in]	callback	The iteration callback function
[in]	user_data	The user data to be passed the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

APP_CONTROL_URI_ERROR_NONE	Successful
APP_CONTROL_URI_ERROR_INVALID_PARAMETER	Invalid parameter

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation