anx_params.h File Reference

Manipulation of name=value parameters, with parsing of URI query strings and HTTP-style headers, and printing to these formats and XML meta and param tags. More...

Go to the source code of this file.

Typedefs
typedef void	AnxParams
	A set of parameters.

Enumerations
enum	AnxParamStyle { ANX_PARAMS_QUERY = 0 , ANX_PARAMS_HEADERS = 1 , ANX_PARAMS_METATAGS = 1000 , ANX_PARAMS_PARAMTAGS = 1001 }
	Formatting styles for parsing and printing AnxParams objects. More...

Functions
AnxParams *	anx_params_new_parse (char *input, AnxParamStyle style)
	Create a new AnxParms object by parsing text input of a given format.
int	anx_params_snprint (char *buf, size_t n, AnxParams *params, AnxParamStyle style)
	Print an AnxParms object with a given formatting style.
char *	anx_params_get (AnxParams *params, char *name)
	Retrieve a parameter from an AnxParams object.
AnxParams *	anx_params_replace (AnxParams *params, char *name, char *value)
	Add a parameter to an AnxParams object.
AnxParams *	anx_params_append (AnxParams *params, char *name, char *value)
	Add a parameter to an AnxParams object.
AnxParams *	anx_params_remove (AnxParams *params, char *name)
	Remove a parameter from an AnxParams object.
AnxParams *	anx_params_merge (AnxParams *dest, AnxParams *src)
	Merge two AnxParams objects.
AnxParams *	anx_params_clone (AnxParams *params)
	Create a new AnxParams object by cloning an existing one.
AnxParams *	anx_params_free (AnxParams *params)
	Free an AnxParams object.

Detailed Description

Manipulation of name=value parameters, with parsing of URI query strings and HTTP-style headers, and printing to these formats and XML meta and param tags.

• Field names are case-insensitive
• Field names are unique within an AnxParams object. When parsing URI query strings or HTTP-style headers, if multiple entries for the same field name are found, the successive values are concatenated and separated by commas (as per RFC2616 sec 4.2)

Typedef Documentation

AnxParams

typedef void AnxParams

A set of parameters.

• NULL is equivalent to an empty parameter set
• Create with anx_params_new_parse() or anx_params_clone(), or by adding a parameter to the empty set (NULL)
• The base value of an AnxParams object is updated by calls to anx_params_replace(), anx_params_append(), anx_params_remove(), anx_params_merge() and anx_params_clone(). Hence the return value from these functions must be assigned back to the params object.

Enumeration Type Documentation

AnxParamStyle

enum AnxParamStyle

Formatting styles for parsing and printing AnxParams objects.

Enumerator
ANX_PARAMS_QUERY	URI query format, eg. fish=haddock&color=green
ANX_PARAMS_HEADERS	SMTP/HTTP/AnxData header format, eg. Fish: haddock\r\n Color: Green\r\n
ANX_PARAMS_METATAGS	XHTML/CMML meta tag format, eg.: <meta name="fish" content="haddock"> <meta name="color" content="green">
ANX_PARAMS_PARAMTAGS	CMML param tag format, eg.: Parameters fish Parameters color

Function Documentation

anx_params_append()

AnxParams * anx_params_append	(	AnxParams *	params,
		char *	name,
		char *	value
	)

Add a parameter to an AnxParams object.

If a parameter with the given name already exists in params, the new value is appended to the old one, separated by a comma.

Parameters

params	An AnxParams object
name	The parameter name
value	The new parameter value

Returns

The updated AnxParams object

anx_params_clone()

AnxParams * anx_params_clone

(

AnxParams *

params

)

Create a new AnxParams object by cloning an existing one.

Parameters

params

An existing AnxParams object.

Returns

A new AnxParams object with copied parameters. All names and values in \params are duplicated in the returned object.

anx_params_free()

AnxParams * anx_params_free

(

AnxParams *

params

)

Free an AnxParams object.

Parameters

params

An AnxParams object

Returns

NULL on success

anx_params_get()

char * anx_params_get	(	AnxParams *	params,
		char *	name
	)

Retrieve a parameter from an AnxParams object.

Parameters

params	An AnxParams object
name	The parameter name

Returns

The parameter value

Return values

NULL	No such parameter

anx_params_merge()

AnxParams * anx_params_merge	(	AnxParams *	dest,
		AnxParams *	src
	)

Merge two AnxParams objects.

Copies of all parameters in src are appended (as for anx_params_append()) to dest.

Parameters

dest	The AnxParams object into which new values are appended
src	An AnxParams object with the new values.

Returns

An updated reference to dest.

Note

src is not modified by anx_params_merge().

anx_params_new_parse()

AnxParams * anx_params_new_parse	(	char *	input,
		AnxParamStyle	style
	)

Create a new AnxParms object by parsing text input of a given format.

Parameters

input	The text to parse
style	The formatting style of the text. Only ANX_PARAMS_QUERY and ANX_PARAMS_HEADERS are supported.

Returns

A new AnxParams object

Return values

NULL	no parameters found in input, or unsupported style

anx_params_remove()

AnxParams * anx_params_remove	(	AnxParams *	params,
		char *	name
	)

Remove a parameter from an AnxParams object.

Parameters

params	An AnxParams object
name	The parameter name

Returns

The updated AnxParams object

anx_params_replace()

AnxParams * anx_params_replace	(	AnxParams *	params,
		char *	name,
		char *	value
	)

Add a parameter to an AnxParams object.

If a parameter with the given name already exists in params, the new value replaces the old one.

Parameters

params	An AnxParams object
name	The parameter name
value	The new parameter value

Returns

The updated AnxParams object

anx_params_snprint()

int anx_params_snprint	(	char *	buf,
		size_t	n,
		AnxParams *	params,
		AnxParamStyle	style
	)

Print an AnxParms object with a given formatting style.

Parameters

buf	The output buffer
n	The maximum number of bytes to write
params	The AnxParams object
style	The formatting style of the generated text.

Returns

The number of characters printed, not including the trailing '\0'

Truncation:

• On systems conforming to ISO C99, anx_snprint_params() returns the number of characters (not including the trailing '\0') that would have been written to the output string if enough space had been available.
• On non-C99 systems, anx_snprint_params() returns -1 on truncation.