Adaptive Framework  0.9.0
All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Files | Data Structures | Macros | Typedefs | Functions | Variables
Uniform Resource Identifier (URI)

Files

file  afw_uri.h
 Header for Uniform Resource Identifier (URI) helpers.
 

Data Structures

struct  afw_uri_parsed_s
 Typedef for parsed URI returned from afw_uri_parse(). More...
 
struct  afw_uri_parser_s
 URI parser typedef. More...
 

Macros

#define AFW_URI_OCTET_INVALID   (afw_uri_octet_type_t)0x00000000
 
#define AFW_URI_OCTET_GEN_DELIM   (afw_uri_octet_type_t)0x00000001
 
#define AFW_URI_OCTET_SUB_DELIM   (afw_uri_octet_type_t)0x00000002
 
#define AFW_URI_OCTET_UNRESERVED   (afw_uri_octet_type_t)0x00000004
 
#define AFW_URI_OCTET_PCT_ENCODED   (afw_uri_octet_type_t)0x00000008
 
#define AFW_URI_OCTET_ALPHA_UPPER   (afw_uri_octet_type_t)0x00000010
 
#define AFW_URI_OCTET_ALPHA_LOWER   (afw_uri_octet_type_t)0x00000020
 
#define AFW_URI_OCTET_DIGIT   (afw_uri_octet_type_t)0x00000040
 
#define AFW_URI_OCTET_HEXDIGIT   (afw_uri_octet_type_t)0x00000080
 
#define AFW_URI_OCTET_ENCODE_URI   (afw_uri_octet_type_t)0x00000100
 encode except A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #
 
#define AFW_URI_OCTET_ENCODE_COMPONENT   (afw_uri_octet_type_t)0x00000200
 encode except A-Z a-z 0-9 - _ . ! ~ * ' ( )
 
#define AFW_URI_OCTET_ENCODE_COMPONENT_VALUE   (afw_uri_octet_type_t)0x00000400
 encode except A-Z a-z 0-9 - _ . ! ~ * '
 
#define AFW_URI_OCTET_AT   (afw_uri_octet_type_t)0x00010000
 
#define AFW_URI_OCTET_COLON   (afw_uri_octet_type_t)0x00020000
 
#define AFW_URI_OCTET_MINUS   (afw_uri_octet_type_t)0x00040000
 
#define AFW_URI_OCTET_PERCENT   (afw_uri_octet_type_t)0x00080000
 
#define AFW_URI_OCTET_PERIOD   (afw_uri_octet_type_t)0x00100000
 
#define AFW_URI_OCTET_PLUS   (afw_uri_octet_type_t)0x00200000
 
#define AFW_URI_OCTET_QUESTION   (afw_uri_octet_type_t)0x00400000
 
#define AFW_URI_OCTET_SLASH   (afw_uri_octet_type_t)0x00800000
 
#define AFW_URI_OCTET_MASK_IS_BITWISE_NOT   (afw_uri_octet_type_t)0x80000000
 
#define AFW_URI_OCTET_ALPHA
 Upper or lower ascii alpha uri octet type mask. More...
 
#define AFW_URI_OCTET_PCHAR
 pchar uri octet type mask. More...
 
#define AFW_URI_OCTET_SCHEME_START    ( AFW_URI_OCTET_ALPHA )
 Start char of scheme uri octet type mask.
 
#define AFW_URI_OCTET_SCHEME_CONTINUE
 Continue char of scheme uri octet type mask. More...
 
#define AFW_URI_OCTET_USERINFO
 Userinfo uri octet type mask. More...
 
#define AFW_URI_OCTET_QUERY
 Query uri octet type mask. More...
 
#define AFW_URI_OCTET_FRAGMENT
 Fragment uri octet type mask. More...
 
#define AFW_URI_OCTET_RESERVED
 Reserved uri octet type mask. More...
 
#define AFW_URI_OCTET_IS(type, mask)   ((type) & (AFW_URI_OCTET_ ## mask))
 Test uri octet type using mask. More...
 

Typedefs

typedef afw_uint32_t afw_uri_octet_type_t
 Token type typedef.
 
typedef struct afw_uri_parsed_s afw_uri_parsed_t
 Typedef for parsed URI returned from afw_uri_parse().
 
typedef struct afw_uri_parser_s afw_uri_parser_t
 URI parser typedef.
 

Functions

void afw_uri_parser_initialize (afw_uri_parser_t *parser, const afw_utf8_t *uri, const afw_pool_t *p, afw_xctx_t *xctx)
 Initialize a parser in specific pool. More...
 
const afw_uri_parser_tafw_uri_parser_create (const afw_utf8_t *uri, const afw_pool_t *p, afw_xctx_t *xctx)
 Create and initialize a parser in specific pool. More...
 
void afw_uri_parse_next_token (const afw_uri_parser_t *parser, afw_xctx_t *xctx)
 Parse next token. More...
 
void afw_uri_parse_reuse_token (const afw_uri_parser_t *parser, afw_xctx_t *xctx)
 Cause next call afw_uri_parse_get_next_token() to return current token. More...
 
void afw_uri_parse_set_consider_period_a_token (const afw_uri_parser_t *parser, afw_boolean_t consider_period_a_token, afw_xctx_t *xctx)
 Set consider_period_a_token flag. More...
 
afw_size_t afw_uri_encode_len (const afw_utf8_t *string, afw_uri_octet_type_t mask, afw_xctx_t *xctx)
 The length needed to URI encode a string. More...
 
afw_size_t afw_uri_encode_raw_len (const afw_memory_t *raw, afw_uri_octet_type_t mask, afw_xctx_t *xctx)
 The length needed to URI encode raw. More...
 
const afw_utf8_tafw_uri_encode (const afw_utf8_t *string, afw_uri_octet_type_t mask, const afw_pool_t *p, afw_xctx_t *xctx)
 URI encode a string. More...
 
const afw_utf8_tafw_uri_encode_create (const afw_utf8_octet_t *s, afw_size_t len, afw_uri_octet_type_t mask, const afw_pool_t *p, afw_xctx_t *xctx)
 Create a URI encode a string. More...
 
const afw_utf8_tafw_uri_encode_raw (const afw_memory_t *raw, afw_uri_octet_type_t mask, const afw_pool_t *p, afw_xctx_t *xctx)
 URI encode raw. More...
 
afw_size_t afw_uri_encode_to_preallocated (afw_utf8_octet_t *s, afw_size_t s_len, const afw_utf8_t *string, afw_uri_octet_type_t mask, const afw_pool_t *p, afw_xctx_t *xctx)
 URI encode a string using supplied afw_utf8_t. More...
 
afw_size_t afw_uri_encode_raw_to_preallocated (afw_utf8_octet_t *s, afw_size_t s_len, const afw_memory_t *raw, afw_uri_octet_type_t mask, const afw_pool_t *p, afw_xctx_t *xctx)
 URI encode from raw using supplied afw_utf8_t. More...
 
const afw_utf8_tafw_uri_decode (const afw_utf8_t *encoded, const afw_pool_t *p, afw_xctx_t *xctx)
 Decode a URI encoded string. More...
 
const afw_utf8_tafw_uri_decode_create (const afw_utf8_octet_t *s, afw_size_t len, const afw_pool_t *p, afw_xctx_t *xctx)
 Create a URI decoded string. More...
 
const afw_memory_tafw_uri_decode_to_raw_create (const afw_utf8_octet_t *s, afw_size_t len, const afw_pool_t *p, afw_xctx_t *xctx)
 Decode URI encoded string to raw. More...
 
const afw_memory_tafw_uri_decode_to_raw (const afw_utf8_t *encoded, const afw_pool_t *p, afw_xctx_t *xctx)
 Decode a URI encoded string to raw. More...
 
const afw_uri_parsed_tafw_uri_parse (const afw_utf8_t *uri, afw_boolean_t is_value_path, const afw_utf8_t *current_path, const afw_pool_t *p, afw_xctx_t *xctx)
 Parse a URI in specific pool. More...
 
const afw_object_tafw_uri_parsed_to_object (const afw_uri_parsed_t *parsed, const afw_pool_t *p, afw_xctx_t *xctx)
 Turn a parsed URI into an object representation. More...
 
const afw_object_tafw_uri_to_object (const afw_utf8_t *uri, afw_boolean_t is_value_path, const afw_utf8_t *current_path, const afw_pool_t *p, afw_xctx_t *xctx)
 Turn a URI into an object representation. More...
 
afw_boolean_t afw_uri_octet_test (afw_octet_t octet, afw_uri_octet_type_t mask)
 Test uri octet type mask. More...
 
afw_boolean_t afw_uri_parsed_are_equivalent (const afw_uri_parsed_t *parsed1, const afw_uri_parsed_t *parsed2, afw_xctx_t *xctx)
 Determine if two parsed URIs are equivalent. More...
 
afw_boolean_t afw_uri_are_equivalent (const afw_utf8_t *uri1, const afw_utf8_t *uri2, afw_boolean_t is_value_path, const afw_utf8_t *current_path2, const afw_pool_t *p, afw_xctx_t *xctx)
 Determine if two URIs are equivalent. More...
 

Variables

 afw_uri_octet_type [256]
 Token type table indexed by afw_octet_t ( 0 - 255 ).
 

Detailed Description

Uniform Resource Identifier (URI) support.

Macro Definition Documentation

◆ AFW_URI_OCTET_ALPHA

#define AFW_URI_OCTET_ALPHA
Value:
( AFW_URI_OCTET_ALPHA_UPPER | \
AFW_URI_OCTET_ALPHA_LOWER )

Upper or lower ascii alpha uri octet type mask.

Definition at line 68 of file afw_uri.h.

◆ AFW_URI_OCTET_FRAGMENT

#define AFW_URI_OCTET_FRAGMENT
Value:
AFW_URI_OCTET_SLASH | \
AFW_URI_OCTET_QUESTION )
#define AFW_URI_OCTET_PCHAR
pchar uri octet type mask.
Definition: afw_uri.h:73

Fragment uri octet type mask.

Definition at line 106 of file afw_uri.h.

◆ AFW_URI_OCTET_IS

#define AFW_URI_OCTET_IS (   type,
  mask 
)    ((type) & (AFW_URI_OCTET_ ## mask))

Test uri octet type using mask.

Parameters
typeto test.
maskfor true types.
Returns
boolean result of test.

Definition at line 123 of file afw_uri.h.

◆ AFW_URI_OCTET_PCHAR

#define AFW_URI_OCTET_PCHAR
Value:
( AFW_URI_OCTET_UNRESERVED | \
AFW_URI_OCTET_PCT_ENCODED | \
AFW_URI_OCTET_SUB_DELIM | \
AFW_URI_OCTET_COLON | \
AFW_URI_OCTET_AT )

pchar uri octet type mask.

Definition at line 73 of file afw_uri.h.

◆ AFW_URI_OCTET_QUERY

#define AFW_URI_OCTET_QUERY
Value:
AFW_URI_OCTET_SLASH | \
AFW_URI_OCTET_QUESTION )

Query uri octet type mask.

Definition at line 100 of file afw_uri.h.

◆ AFW_URI_OCTET_RESERVED

#define AFW_URI_OCTET_RESERVED
Value:
( AFW_URI_OCTET_GEN_DELIM | \
AFW_URI_OCTET_SUB_DELIM )

Reserved uri octet type mask.

Definition at line 112 of file afw_uri.h.

◆ AFW_URI_OCTET_SCHEME_CONTINUE

#define AFW_URI_OCTET_SCHEME_CONTINUE
Value:
AFW_URI_OCTET_DIGIT | \
AFW_URI_OCTET_PLUS | \
AFW_URI_OCTET_MINUS | \
AFW_URI_OCTET_PERIOD )
#define AFW_URI_OCTET_ALPHA
Upper or lower ascii alpha uri octet type mask.
Definition: afw_uri.h:68

Continue char of scheme uri octet type mask.

Definition at line 85 of file afw_uri.h.

◆ AFW_URI_OCTET_USERINFO

#define AFW_URI_OCTET_USERINFO
Value:
( AFW_URI_OCTET_UNRESERVED | \
AFW_URI_OCTET_PCT_ENCODED | \
AFW_URI_OCTET_SUB_DELIM | \
AFW_URI_OCTET_COLON )

Userinfo uri octet type mask.

Definition at line 93 of file afw_uri.h.

Function Documentation

◆ afw_uri_are_equivalent()

afw_boolean_t afw_uri_are_equivalent ( const afw_utf8_t uri1,
const afw_utf8_t uri2,
afw_boolean_t  is_value_path,
const afw_utf8_t current_path2,
const afw_pool_t p,
afw_xctx_t xctx 
)

Determine if two URIs are equivalent.

Parameters
uri1parsed uri.
uri2parsed uri.
is_value_pathindicates URIs are of adaptive values.
current_path2used for resolving asterisks in uri2 path or NULL.
pto use while determining equivalence.
xctxof caller
Returns
boolean result of equivalent test.

Definition at line 2143 of file afw_uri.c.

◆ afw_uri_decode()

const afw_utf8_t* afw_uri_decode ( const afw_utf8_t encoded,
const afw_pool_t p,
afw_xctx_t xctx 
)

Decode a URI encoded string.

Parameters
encodedstring.
pto use for result.
xctxof caller.
Returns
original encoded if no % is string otherwise decoded string.

The decoded value must be an Unicode NFC string or an error is thrown.

Definition at line 1000 of file afw_uri.c.

◆ afw_uri_decode_create()

const afw_utf8_t* afw_uri_decode_create ( const afw_utf8_octet_t s,
afw_size_t  len,
const afw_pool_t p,
afw_xctx_t xctx 
)

Create a URI decoded string.

Parameters
spoints to first octet.
lenis length in octets to decode.
pto use for result.
xctxof caller.
Returns
decoded string.

The decoded value must be an Unicode NFC string or an error is thrown.

Definition at line 1023 of file afw_uri.c.

◆ afw_uri_decode_to_raw()

const afw_memory_t* afw_uri_decode_to_raw ( const afw_utf8_t encoded,
const afw_pool_t p,
afw_xctx_t xctx 
)

Decode a URI encoded string to raw.

Parameters
encodedstring.
pto use for result.
xctxof caller.
Returns
original encoded if no % is string otherwise decoded raw.

Use this instead of afw_uri_decode() is decoded value might not be valid Unicode NFC.

Definition at line 1099 of file afw_uri.c.

◆ afw_uri_decode_to_raw_create()

const afw_memory_t* afw_uri_decode_to_raw_create ( const afw_utf8_octet_t s,
afw_size_t  len,
const afw_pool_t p,
afw_xctx_t xctx 
)

Decode URI encoded string to raw.

Parameters
spoints to first octet.
lenis length in octets to decode.
pto use for result.
xctxof caller.
Returns
original encoded if no % is string otherwise decoded raw.

Use this instead of afw_uri_decode() is decoded value might not be valid Unicode NFC.

Definition at line 1047 of file afw_uri.c.

◆ afw_uri_encode()

const afw_utf8_t* afw_uri_encode ( const afw_utf8_t string,
afw_uri_octet_type_t  mask,
const afw_pool_t p,
afw_xctx_t xctx 
)

URI encode a string.

Parameters
stringto encode.
maskidentifying octets to remain asis. See afw_uri_octet_test().
pto use for result.
xctxof caller.
Returns
encoded string.

If string does not contain octets that need to be encoded, the original string parameter will be returned as result.

Definition at line 814 of file afw_uri.c.

◆ afw_uri_encode_create()

const afw_utf8_t* afw_uri_encode_create ( const afw_utf8_octet_t s,
afw_size_t  len,
afw_uri_octet_type_t  mask,
const afw_pool_t p,
afw_xctx_t xctx 
)

Create a URI encode a string.

Parameters
spoints to first octet.
lenis length in octets of string.
maskidentifying octets to remain asis. See afw_uri_octet_test().
pto use for result.
xctxof caller.
Returns
encoded string.

If string does not contain octets that need to be encoded, the original string parameter will be returned as result.

Definition at line 866 of file afw_uri.c.

◆ afw_uri_encode_len()

afw_size_t afw_uri_encode_len ( const afw_utf8_t string,
afw_uri_octet_type_t  mask,
afw_xctx_t xctx 
)

The length needed to URI encode a string.

Parameters
stringto encode.
maskidentifying octets to remain asis. See afw_uri_octet_test().
xctxof caller.
Returns
len needed to encode string.

Definition at line 762 of file afw_uri.c.

◆ afw_uri_encode_raw()

const afw_utf8_t* afw_uri_encode_raw ( const afw_memory_t raw,
afw_uri_octet_type_t  mask,
const afw_pool_t p,
afw_xctx_t xctx 
)

URI encode raw.

Parameters
rawto encode.
maskidentifying octets to remain asis. See afw_uri_octet_test().
pto use for result.
xctxof caller.
Returns
encoded string.

Definition at line 884 of file afw_uri.c.

◆ afw_uri_encode_raw_len()

afw_size_t afw_uri_encode_raw_len ( const afw_memory_t raw,
afw_uri_octet_type_t  mask,
afw_xctx_t xctx 
)

The length needed to URI encode raw.

Parameters
rawto encode.
maskidentifying octets to remain asis. See afw_uri_octet_test().
xctxof caller.
Returns
len needed to encode raw.

The string should be a component or subcomponent since all reserved and invalid characters will be percent encoded.

Definition at line 788 of file afw_uri.c.

◆ afw_uri_encode_raw_to_preallocated()

afw_size_t afw_uri_encode_raw_to_preallocated ( afw_utf8_octet_t s,
afw_size_t  s_len,
const afw_memory_t raw,
afw_uri_octet_type_t  mask,
const afw_pool_t p,
afw_xctx_t xctx 
)

URI encode from raw using supplied afw_utf8_t.

Parameters
sis preallocated place for result.
s_lenis size of preallocated place.
rawto encode.
maskidentifying octets to remain asis. See afw_uri_octet_test().
pto use for result.
xctxof caller.
Returns
length of encoded string or -1 if error.

This form is useful if you do not want a afw_memory_t stuct to be allocated.

Definition at line 963 of file afw_uri.c.

◆ afw_uri_encode_to_preallocated()

afw_size_t afw_uri_encode_to_preallocated ( afw_utf8_octet_t s,
afw_size_t  s_len,
const afw_utf8_t string,
afw_uri_octet_type_t  mask,
const afw_pool_t p,
afw_xctx_t xctx 
)

URI encode a string using supplied afw_utf8_t.

Parameters
sis preallocated place for result.
s_lenis size of preallocated place.
stringto encode.
maskidentifying octets to remain asis. See afw_uri_octet_test().
pto use for result.
xctxof caller.
Returns
length of encoded string or -1 if error.

This form is useful if you do not want a afw_utf8_t stuct to be allocated.

Definition at line 925 of file afw_uri.c.

◆ afw_uri_octet_test()

afw_boolean_t afw_uri_octet_test ( afw_octet_t  octet,
afw_uri_octet_type_t  mask 
)

Test uri octet type mask.

Parameters
octetto test
mask(see details in description)
Returns
boolean result.

See #define AFW_URI_OCTET_* for values.

If (afw_uri_octet_type_t)0x80000000) & mask is not 0, ie high bit on, the mask parameter is the ~ of the bits to test.

afw_uri_octet_test(octet, mask) returns true if any bit in mask are 1.

afw_uri_octet_test(octet, ~mask) returns true if all bits in ~mask are 0.

Examples:

// Test to see if octet is to be left asis when encoding URI components afw_uri_octet_test(octet, AFW_URI_OCTET_ENCODE_COMPONENT)

// Test to see if octet should be % encoded when encoding URI components afw_uri_octet_test(octet, ~AFW_URI_OCTET_ENCODE_COMPONENT)

Definition at line 2161 of file afw_uri.c.

◆ afw_uri_parse()

const afw_uri_parsed_t* afw_uri_parse ( const afw_utf8_t uri,
afw_boolean_t  is_value_path,
const afw_utf8_t current_path,
const afw_pool_t p,
afw_xctx_t xctx 
)

Parse a URI in specific pool.

Parameters
urito parse.
is_value_pathindicates path is an adaptive value path.
current_pathto use to resolve relative value paths.
pto use for result.
xctxof caller
Returns
Parsed URI or NULL if invalid.

If is_value_path is true, afw_object_path_parse() will be called to further parse uri if it begins with a single slash.

Todo:
FIXME: Should syntax check v4 address.
Todo:
FIXME: Should syntax check v6 address.
Todo:
FIXME: Needs further parsing.
Todo:
FIXME: Needs further parsing.

Definition at line 1470 of file afw_uri.c.

◆ afw_uri_parse_next_token()

void afw_uri_parse_next_token ( const afw_uri_parser_t parser,
afw_xctx_t xctx 
)

Parse next token.

Parameters
parser.
xctxof caller.

See parser->token and parser->token_is_delimiter for results. If there are no more tokens, parser->token.s will be NULL.

Definition at line 1175 of file afw_uri.c.

◆ afw_uri_parse_reuse_token()

void afw_uri_parse_reuse_token ( const afw_uri_parser_t parser,
afw_xctx_t xctx 
)

Cause next call afw_uri_parse_get_next_token() to return current token.

Parameters
parser.
xctxof caller.

Definition at line 1265 of file afw_uri.c.

◆ afw_uri_parse_set_consider_period_a_token()

void afw_uri_parse_set_consider_period_a_token ( const afw_uri_parser_t parser,
afw_boolean_t  consider_period_a_token,
afw_xctx_t xctx 
)

Set consider_period_a_token flag.

Parameters
parser.
consider_period_a_tokenflag.
xctxof caller.

Use this function to tell parser to consider '.' as a token, even though it is normally not. This is useful when parsing dotted property names.

Definition at line 2057 of file afw_uri.c.

◆ afw_uri_parsed_are_equivalent()

afw_boolean_t afw_uri_parsed_are_equivalent ( const afw_uri_parsed_t parsed1,
const afw_uri_parsed_t parsed2,
afw_xctx_t xctx 
)

Determine if two parsed URIs are equivalent.

Parameters
parsed1parsed uri.
parsed2parsed uri.
xctxof caller
Returns
boolean result of equivalent test.
Todo:
FIXME: compare decoded tokens instead.
Todo:
FIXME: compare query and fragment part.

Definition at line 2070 of file afw_uri.c.

◆ afw_uri_parsed_to_object()

const afw_object_t* afw_uri_parsed_to_object ( const afw_uri_parsed_t parsed,
const afw_pool_t p,
afw_xctx_t xctx 
)

Turn a parsed URI into an object representation.

Parameters
parsedURI.
pto use for result.
xctxof caller
Returns
AdaptiveParsedURI representation of parsed URI.

Definition at line 1894 of file afw_uri.c.

◆ afw_uri_parser_create()

const afw_uri_parser_t* afw_uri_parser_create ( const afw_utf8_t uri,
const afw_pool_t p,
afw_xctx_t xctx 
)

Create and initialize a parser in specific pool.

Parameters
urito parse.
pto use for anything allocated while parsing.
xctxof caller.
Returns
initialized parser.

The URI parser can be used to parse a full URI or a URI component or subcomponent. In the case of a full URI you may want to consider using afw_uri_parse() instead.

Definition at line 1160 of file afw_uri.c.

◆ afw_uri_parser_initialize()

void afw_uri_parser_initialize ( afw_uri_parser_t parser,
const afw_utf8_t uri,
const afw_pool_t p,
afw_xctx_t xctx 
)

Initialize a parser in specific pool.

Parameters
parseris preallocated afw_uri_parser_t struct to initialize.
urito parse.
pto use for anything allocated while parsing.
xctxof caller.

The URI parser can be used to parse a full URI or a URI component or subcomponent. In the case of a full URI you may want to consider using afw_uri_parse() instead.

Definition at line 1146 of file afw_uri.c.

◆ afw_uri_to_object()

const afw_object_t* afw_uri_to_object ( const afw_utf8_t uri,
afw_boolean_t  is_value_path,
const afw_utf8_t current_path,
const afw_pool_t p,
afw_xctx_t xctx 
)

Turn a URI into an object representation.

Parameters
urito parse.
is_value_pathindicates path is an adaptive value path.
current_pathto use to resolve relative value paths.
pto use for result.
xctxof caller
Returns
AdaptiveParsedURI representation of parsed URI.

If is_value_path is true, afw_object_path_parse() will be called to further parse uri if it begins with a single slash.

Definition at line 2039 of file afw_uri.c.