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

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.

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().


←Products
© 2005-2012 - KoanLogic S.r.l. - All rights reserved