URI

Overview

The URI module allows the parsing and validation of URI strings as defined in RFC 3986.

It can be used for parsing a given uri string:

    u_uri_t *u = NULL;
    const char *uri = "ftp://ftp.is.co.za/rfc/rfc1808.txt";
    const char *authority, *scheme;

    // parse and tokenize the uri string 
    // note that no u_uri_opts_t have been supplied
    dbg_err_if (u_uri_crumble(uri, 0, &u));

    // get tokens you are interested in, e.g:
    dbg_err_if ((scheme = u_uri_get_scheme(u)) == NULL);
    dbg_err_if ((authority = u_uri_get_authority(u)) == NULL);
    
    // should give "ftp '://' ftp.is.co.za"
    con("%s \'://\' %s", scheme, authority);
    ...
    // free the uri object once you are done with it
    u_uri_free(u);

Or, the way round, to build a URI string starting from its components:

    u_uri_t *u = NULL;
    char s[U_URI_STRMAX];

    // make room for the new URI object
    dbg_err_if (u_uri_new(0, &u));

    // set the relevant attributes
    (void) u_uri_set_scheme(u, "http");
    (void) u_uri_set_authority(u, "www.ietf.org");
    (void) u_uri_set_path(u, "rfc/rfc3986.txt");

    // encode it to string 's'
    dbg_err_if (u_uri_knead(u, s));

    // should give: http://www.ietf.org/rfc/rfc3986.txt
    con("%s", s);
    ...
    u_uri_free(u);

Note:: u_uri_t objects are building blocks in the Networking module.

Defines
#define	U_URI_STRMAX 4096
	Maximum length allowed when encoding an URI string, see u_uri_knead.
Typedefs
typedef struct u_uri_s	u_uri_t
	Base type for all URI operations.
Enumerations
enum	u_uri_opts_t { U_URI_OPT_NONE = 0x00, U_URI_OPT_DONT_PARSE_USERINFO = 0x01 }
	Option that can or'ed together and supplied to u_uri_crumble or u_uri_new. More...
enum	u_uri_flags_t { U_URI_FLAGS_NONE = 0x00, U_URI_FLAGS_HOST_IS_IPADDRESS = 0x01, U_URI_FLAGS_HOST_IS_IPLITERAL = 0x02 }
	Flags set by the parsing machinery. More...
Functions
int	u_uri_new (u_uri_opts_t opts, u_uri_t **pu)
	Make room for a new u_uri_t object.
void	u_uri_free (u_uri_t *u)
	dispose memory allocated to `uri`
int	u_uri_crumble (const char uri, u_uri_opts_t opts, u_uri_t *pu)
	Parse an URI string and create the corresponding u_uri_t object.
int	u_uri_knead (u_uri_t *u, char s[U_URI_STRMAX])
	Assemble an URI string starting from its atoms.
void	u_uri_print (u_uri_t *u, int extended)
	Print an u_uri_t object to `stderr` (DEBUG/TEST).
const char *	u_uri_get_scheme (u_uri_t *uri)
	Get the scheme value from the supplied `uri`.
int	u_uri_set_scheme (u_uri_t uri, const char val)
	Set the scheme value to `val` on the supplied `uri`.
const char *	u_uri_get_userinfo (u_uri_t *uri)
	Get the userinfo value from the supplied `uri`.
int	u_uri_set_userinfo (u_uri_t uri, const char val)
	Set the userinfo value to `val` on the supplied `uri`.
const char *	u_uri_get_user (u_uri_t *uri)
	Get the user value from the supplied `uri`.
int	u_uri_set_user (u_uri_t uri, const char val)
	Set the user value to `val` on the supplied `uri`.
const char *	u_uri_get_pwd (u_uri_t *uri)
	Get the pwd value from the supplied `uri`.
int	u_uri_set_pwd (u_uri_t uri, const char val)
	Set the pwd value to `val` on the supplied `uri`.
const char *	u_uri_get_host (u_uri_t *uri)
	Get the host value from the supplied `uri`.
int	u_uri_set_host (u_uri_t uri, const char val)
	Set the host value to `val` on the supplied `uri`.
const char *	u_uri_get_port (u_uri_t *uri)
	Get the port value from the supplied `uri`.
u_uri_flags_t	u_uri_get_flags (u_uri_t *uri)
	Get flags set by the parser (if any.).
int	u_uri_set_port (u_uri_t uri, const char val)
	Set the port value to `val` on the supplied `uri`.
const char *	u_uri_get_authority (u_uri_t *uri)
	Get the authority value from the supplied `uri`.
int	u_uri_set_authority (u_uri_t uri, const char val)
	Set the authority value to `val` on the supplied `uri`.
const char *	u_uri_get_path (u_uri_t *uri)
	Get the path value from the supplied `uri`.
int	u_uri_set_path (u_uri_t uri, const char val)
	Set the path value to `val` on the supplied `uri`.
const char *	u_uri_get_query (u_uri_t *uri)
	Get the query value from the supplied `uri`.
int	u_uri_set_query (u_uri_t uri, const char val)
	Set the query value to `val` on the supplied `uri`.
const char *	u_uri_get_fragment (u_uri_t *uri)
	Get the fragment value from the supplied `uri`.
int	u_uri_set_fragment (u_uri_t uri, const char val)
	Set the fragment value to `val` on the supplied `uri`.

Enumeration Type Documentation

enum u_uri_flags_t

Enumerator:

U_URI_FLAGS_NONE	use default parsing algorithm
U_URI_FLAGS_HOST_IS_IPADDRESS	host is in IP-literal or IPv4address format (otherwise assume reg-name.)
U_URI_FLAGS_HOST_IS_IPLITERAL	host is in IP-literal. User must set this flag if she wants to correctly knead an IP-literal address, i.e. one surrounded by square brackets.

Definition at line 37 of file uri.h.

enum u_uri_opts_t

Enumerator:

U_URI_OPT_NONE	use default parsing algorithm
U_URI_OPT_DONT_PARSE_USERINFO	do not try to split user":"password in userinfo

Definition at line 27 of file uri.h.

Function Documentation

int u_uri_crumble	(	const char *	uri,
		u_uri_opts_t	opts,
		u_uri_t **	pu
	)

Parse the NUL-terminated string uri and create an u_uri_t object at *pu

Parameters:

	uri	the NUL-terminated string that must be parsed
	opts	bitmask of or'ed u_uri_opts_t values
	pu	the newly created u_uri_t object containing the b

Return values:

	0	on success
	~0	on error

Definition at line 125 of file srcs/toolbox/uri.c.

References u_lexer_free(), and u_lexer_new().

Referenced by u_net_uri2addr().

void u_uri_free ( u_uri_t * u )

Free the previously (via u_uri_crumble or u_uri_new) allocated u_uri_t object u.

Parameters:

u

reference to the u_uri_t object that needs to be disposed

Returns:: nothing

Definition at line 275 of file srcs/toolbox/uri.c.

References u_free().

Referenced by u_net_uri2addr().

int u_uri_knead	(	u_uri_t *	u,
		char	s[U_URI_STRMAX]
	)

Assemble an URI string at s, starting from its pieces stored in the supplied u_uri_t object u

Parameters:

	u	reference to an already filled in u_uri_t object
	s	reference to an already alloc'd string of size U_URI_STRMAX

Return values:

	0	on success
	~0	on error

Definition at line 152 of file srcs/toolbox/uri.c.

References u_strlcat().

int u_uri_new	(	u_uri_opts_t	opts,
		u_uri_t **	pu
	)

Make room for a new u_uri_t object at *pu. The returned object is completely empty: use the needed setter methods to fill it before passing it to the encoder.

Parameters:

	opts	bitmask of or'ed u_uri_opts_t values
	pu	Reference to an u_uri_t that, on success, will point to the newly created object

Return values:

	0	on success
	~0	on error

Definition at line 250 of file srcs/toolbox/uri.c.

References U_URI_FLAGS_NONE, u_uri_set_path(), and u_zalloc().

URI

Overview

Defines

Typedefs

Enumerations

Functions

Enumeration Type Documentation

Function Documentation