avis/attributes.h File Reference

Detailed Description

Elvin attributes (name/value pairs) support.

#include <avis/stdtypes.h>
#include <avis/errors.h>
#include <avis/values.h>

Go to the source code of this file.

Data Structures

struct Attributes

A map of string names to polymorphic Value instances. More...

struct AttributesIter

An iterator over an Attributes collection. More...

Defines

#define EMPTY_ATTRIBUTES   (&_empty_attributes)

#define attributes_create()   (attributes_init ((Attributes *)avis_emalloc (sizeof (Attributes))))

Create a new attributes instance on the heap.

#define attributes_destroy(attributes)

Free and NULL a named attributes instance.

#define attributes_clone(source)   attributes_copy (attributes_create (), source)

Create a new set of attributes cloned from a source set.

#define attributes_iter_create(attributes)

Create and initialise an AttributesIter instance.

#define attributes_iter_destroy(iter)   (free (iter), (iter) = NULL)

Free and NULL an attributes iterator.

#define attributes_iter_has_next(iter)   ((iter)->has_next)

#define attributes_set_int32(attributes, name, value)   (attributes_set (attributes, name, value_create_int32 (value)))

Convenience to set an int32 value.

#define attributes_set_int64(attributes, name, value)   (attributes_set (attributes, name, value_create_int64 (value)))

Convenience to set an int64 value.

#define attributes_set_real64(attributes, name, value)   (attributes_set (attributes, name, value_create_real64 (value)))

Convenience to set a real64 value.

#define attributes_set_string(attributes, name, value)   (attributes_set (attributes, name, value_create_string (value)))

Convenience to set a string value.

#define attributes_set_opaque(attributes, name, value)   (attributes_set (attributes, name, value_create_opaque (value)))

Convenience to set an opaque value.

Functions

AVIS_PUBLIC Attributes * attributes_init (Attributes *)

Initialise an attributes instance to empty.

AVIS_PUBLIC void attributes_free (Attributes *attributes)

Free resources held by a named attributes instance.

AVIS_PUBLIC void attributes_clear (Attributes *attributes)

Clear and deallocate all entries, leaving an empty set of attributes.

AVIS_PUBLIC Attributes * attributes_copy (Attributes *target, const Attributes *source)

Copy a set of attributes from a source to a target.

AVIS_PUBLIC unsigned int attributes_size (Attributes *attributes)

The number of entries in a set of named attributes.

AVIS_PUBLIC AttributesIter * attributes_iter_init (AttributesIter *iter, const Attributes *attributes)

Initialise an attributes iterator to iterate over the given attributes set.

AVIS_PUBLIC const char * attributes_iter_name (const AttributesIter *iter)

Returns the name of the attribute pointed to by the iterator, or NULL if the iterator is finished.

AVIS_PUBLIC const Value * attributes_iter_value (const AttributesIter *iter)

Returns the value of the attribute pointed to by the iterator, or NULL if the iterator is finished.

AVIS_PUBLIC bool attributes_iter_next (AttributesIter *iter)

Advanced the iterator to the next attribute.

AVIS_PUBLIC void attributes_set (Attributes *attributes, const char *name, Value *value)

Set the value mapped to a name.

AVIS_PUBLIC void attributes_set_nocopy (Attributes *attributes, char *name, Value *value)

Same as attributes_set(), but does not copy the name first.

AVIS_PUBLIC Value * attributes_get (Attributes *attributes, const char *name)

Get the value mapped to a name.

AVIS_PUBLIC bool attributes_contains (Attributes *attributes, const char *name)

Test if the attributes contains a mapping for a given field name.

AVIS_PUBLIC Value * attributes_remove (Attributes *attributes, const char *name)

Remove the value mapped to a name.

AVIS_PUBLIC int32_t attributes_get_int32 (Attributes *attributes, const char *name)

Convenience to get an int32 value.

AVIS_PUBLIC int64_t attributes_get_int64 (Attributes *attributes, const char *name)

Convenience to get an int64 value.

AVIS_PUBLIC real64_t attributes_get_real64 (Attributes *attributes, const char *name)

Convenience to get a real64 value.

AVIS_PUBLIC const char * attributes_get_string (Attributes *attributes, const char *name)

Convenience to get a string value.

AVIS_PUBLIC Array * attributes_get_opaque (Attributes *attributes, const char *name)

Convenience to get an opaque value.

Variables

AVIS_PUBLIC_DATA Attributes _empty_attributes

Define Documentation

#define attributes_clone ( source ) attributes_copy (attributes_create (), source)

Create a new set of attributes cloned from a source set.

Parameters:

source

The source to copy from.

Returns:: A pointer to the target.

See also:: attributes_copy()

#define attributes_create ( ) (attributes_init ((Attributes *)avis_emalloc (sizeof (Attributes))))

Create a new attributes instance on the heap.

See also:

attributes_init()

attributes_free()

attributes_destroy()

#define attributes_destroy ( attributes )

Value:

if ((attributes) && (attributes) != EMPTY_ATTRIBUTES) \
  { \
    attributes_free (attributes), free (attributes), attributes = NULL; \
  }

Free and NULL a named attributes instance.

See also:: attributes_free()

#define attributes_iter_create ( attributes )

Value:

attributes_iter_init \
    ((AttributesIter *)avis_emalloc (sizeof (AttributesIter)), (attributes))

Create and initialise an AttributesIter instance.

#define attributes_iter_destroy ( iter ) (free (iter), (iter) = NULL)

Free and NULL an attributes iterator.

#define attributes_iter_has_next ( iter ) ((iter)->has_next)

#define attributes_set_int32	(	attributes,
		name,
		value	)	(attributes_set (attributes, name, value_create_int32 (value)))

Convenience to set an int32 value.

Parameters:

	attributes	The attributes to update.
	name	The name to use. This will be copied before being put into the set.
	value	The value to associate with name.

See also:: attributes_set()

#define attributes_set_int64	(	attributes,
		name,
		value	)	(attributes_set (attributes, name, value_create_int64 (value)))

Convenience to set an int64 value.

Parameters:

	attributes	The attributes to update.
	name	The name to use. This will be copied before being put into the set.
	value	The value to associate with name.

See also:: attributes_set()

#define attributes_set_opaque	(	attributes,
		name,
		value	)	(attributes_set (attributes, name, value_create_opaque (value)))

Convenience to set an opaque value.

Parameters:

	attributes	The attributes to update.
	name	The name to use. This will be copied before being put into the set.
	value	The opaque value to associate with name (an Array instance). Unlike string attributes, this will NOT be copied before being added to the set: the set will take ownership of the array's data and free it when appropriate.

See also:: attributes_set()

#define attributes_set_real64	(	attributes,
		name,
		value	)	(attributes_set (attributes, name, value_create_real64 (value)))

Convenience to set a real64 value.

Parameters:

	attributes	The attributes to update.
	name	The name to use. This will be copied before being put into the set.
	value	The value to associate with name.

See also:: attributes_set()

#define attributes_set_string	(	attributes,
		name,
		value	)	(attributes_set (attributes, name, value_create_string (value)))

Convenience to set a string value.

Parameters:

	attributes	The attributes to update.
	name	The name to use. This will be copied before being put into the set.
	value	The value to associate with name. The string will be copied before being added to the set. This must be a valid UTF-8 string: an invalid UTF-8 string will likely trigger a protocol violation in the router and result in disconnection.

See also:: attributes_set()

#define EMPTY_ATTRIBUTES (&_empty_attributes)

Function Documentation

AVIS_PUBLIC void attributes_clear ( Attributes * attributes )

Clear and deallocate all entries, leaving an empty set of attributes.

AVIS_PUBLIC bool attributes_contains	(	Attributes *	attributes,
		const char *	name
	)

Test if the attributes contains a mapping for a given field name.

AVIS_PUBLIC Attributes* attributes_copy	(	Attributes *	target,
		const Attributes *	source
	)

Copy a set of attributes from a source to a target.

Copies the values also.

Parameters:

	target	The target for the copied attributes.
	source	The source to copy from.

Returns:: A pointer to the target.

See also:: attributes_clone()

AVIS_PUBLIC void attributes_free ( Attributes * attributes )

Free resources held by a named attributes instance.

See also:: attributes_create()
attributes_clear()

AVIS_PUBLIC Value* attributes_get	(	Attributes *	attributes,
		const char *	name
	)

Get the value mapped to a name.

Parameters:

	attributes	The attributes to use.
	name	The name to lookup

Returns:: The value associated with name, or NULL if no value.

See also:: attributes_set()

AVIS_PUBLIC int32_t attributes_get_int32	(	Attributes *	attributes,
		const char *	name
	)

Convenience to get an int32 value.

Parameters:

	attributes	The attributes to read from.
	name	The name to use.

Returns:: The integer associated with name, or 0 if not set or value is not an integer.

See also:: attributes_set_int32()
attributes_get()

AVIS_PUBLIC int64_t attributes_get_int64	(	Attributes *	attributes,
		const char *	name
	)

Convenience to get an int64 value.

Parameters:

	attributes	The attributes to read from.
	name	The name to use.

Returns:: The integer associated with name, or 0 if not set or value is not an integer.

See also:: attributes_set_int64()
attributes_get()

AVIS_PUBLIC Array* attributes_get_opaque	(	Attributes *	attributes,
		const char *	name
	)

Convenience to get an opaque value.

Parameters:

	attributes	The attributes to read from.
	name	The name to use.

Returns:: The opaque value associated with name, or NULL if not set or value is not an opaque.

See also:: attributes_set_opaque()
attributes_get()

AVIS_PUBLIC real64_t attributes_get_real64	(	Attributes *	attributes,
		const char *	name
	)

Convenience to get a real64 value.

Parameters:

	attributes	The attributes to read from.
	name	The name to use.

Returns:: The real64 associated with name, or 0 if not set or value is not an real64 value.

See also:: attributes_set_real64()
attributes_get()

AVIS_PUBLIC const char* attributes_get_string	(	Attributes *	attributes,
		const char *	name
	)

Convenience to get a string value.

Parameters:

	attributes	The attributes to read from.
	name	The name to use.

Returns:: The string associated with name, or NULL if not set or value is not a string.

See also:: attributes_set_string()
attributes_get()

AVIS_PUBLIC Attributes* attributes_init ( Attributes * )

Initialise an attributes instance to empty.

See also:: attributes_create()
attributes_clear()

AVIS_PUBLIC AttributesIter* attributes_iter_init	(	AttributesIter *	iter,
		const Attributes *	attributes
	)

Initialise an attributes iterator to iterate over the given attributes set.

Example usage:

 Attributes *attrs = ...;
 AttributesIter i;

 attributes_iter_init (&i, attrs);

 while (attributes_iter_has_next (&i))
 {
   const char *name = attributes_iter_name (&i);
   const Value *value = attributes_iter_value (&i);

...

   attributes_iter_next (&i);
 }

See also:

attributes_iter_has_next()

attributes_iter_next()

attributes_iter_name()

attributes_iter_value()

AVIS_PUBLIC const char* attributes_iter_name ( const AttributesIter * iter )

Returns the name of the attribute pointed to by the iterator, or NULL if the iterator is finished.

AVIS_PUBLIC bool attributes_iter_next ( AttributesIter * iter )

Advanced the iterator to the next attribute.

Returns:: True if attributes_iter_has_next() would return true after the advance (i.e. the iterator points to an attribute).

AVIS_PUBLIC const Value* attributes_iter_value ( const AttributesIter * iter )

Returns the value of the attribute pointed to by the iterator, or NULL if the iterator is finished.

AVIS_PUBLIC Value* attributes_remove	(	Attributes *	attributes,
		const char *	name
	)

Remove the value mapped to a name.

Parameters:

	attributes	The attributes to modify.
	name	The name to remove.

Returns:: The value associated with name, or NULL if no value. This value must be deallocated by the caller with value_destroy() when no longer needed.

See also:: attributes_set()

AVIS_PUBLIC void attributes_set	(	Attributes *	attributes,
		const char *	name,
		Value *	value
	)

Set the value mapped to a name.

If an existing value exists, it will be replaced and deleted.

Parameters:

	attributes	The attributes to update.
	name	The name to use. This will be copied before being put into the set.
	value	The value to associate with name.

See also:

attributes_get()

attributes_set_direct()

attributes_remove()

AVIS_PUBLIC void attributes_set_nocopy	(	Attributes *	attributes,
		char *	name,
		Value *	value
	)

Same as attributes_set(), but does not copy the name first.

If an existing value exists, it will be replaced and deleted.

Parameters:

	attributes	The attributes to update.
	name	The name to use.
	value	The value to associate with name.

See also:

attributes_get()

attributes_set()

attributes_remove()

value_create_string_nocopy()

AVIS_PUBLIC unsigned int attributes_size ( Attributes * attributes )

The number of entries in a set of named attributes.

Variable Documentation

AVIS_PUBLIC_DATA Attributes _empty_attributes


Data Structures
struct	Attributes
	A map of string names to polymorphic Value instances. More...
struct	AttributesIter
	An iterator over an Attributes collection. More...
Defines
#define	EMPTY_ATTRIBUTES (&_empty_attributes)
#define	attributes_create() (attributes_init ((Attributes *)avis_emalloc (sizeof (Attributes))))
	Create a new attributes instance on the heap.
#define	attributes_destroy(attributes)
	Free and NULL a named attributes instance.
#define	attributes_clone(source) attributes_copy (attributes_create (), source)
	Create a new set of attributes cloned from a source set.
#define	attributes_iter_create(attributes)
	Create and initialise an AttributesIter instance.
#define	attributes_iter_destroy(iter) (free (iter), (iter) = NULL)
	Free and NULL an attributes iterator.
#define	attributes_iter_has_next(iter) ((iter)->has_next)
#define	attributes_set_int32(attributes, name, value) (attributes_set (attributes, name, value_create_int32 (value)))
	Convenience to set an int32 value.
#define	attributes_set_int64(attributes, name, value) (attributes_set (attributes, name, value_create_int64 (value)))
	Convenience to set an int64 value.
#define	attributes_set_real64(attributes, name, value) (attributes_set (attributes, name, value_create_real64 (value)))
	Convenience to set a real64 value.
#define	attributes_set_string(attributes, name, value) (attributes_set (attributes, name, value_create_string (value)))
	Convenience to set a string value.
#define	attributes_set_opaque(attributes, name, value) (attributes_set (attributes, name, value_create_opaque (value)))
	Convenience to set an opaque value.
Functions
AVIS_PUBLIC Attributes *	attributes_init (Attributes *)
	Initialise an attributes instance to empty.
AVIS_PUBLIC void	attributes_free (Attributes *attributes)
	Free resources held by a named attributes instance.
AVIS_PUBLIC void	attributes_clear (Attributes *attributes)
	Clear and deallocate all entries, leaving an empty set of attributes.
AVIS_PUBLIC Attributes *	attributes_copy (Attributes target, const Attributes source)
	Copy a set of attributes from a source to a target.
AVIS_PUBLIC unsigned int	attributes_size (Attributes *attributes)
	The number of entries in a set of named attributes.
AVIS_PUBLIC AttributesIter *	attributes_iter_init (AttributesIter iter, const Attributes attributes)
	Initialise an attributes iterator to iterate over the given attributes set.
AVIS_PUBLIC const char *	attributes_iter_name (const AttributesIter *iter)
	Returns the name of the attribute pointed to by the iterator, or NULL if the iterator is finished.
AVIS_PUBLIC const Value *	attributes_iter_value (const AttributesIter *iter)
	Returns the value of the attribute pointed to by the iterator, or NULL if the iterator is finished.
AVIS_PUBLIC bool	attributes_iter_next (AttributesIter *iter)
	Advanced the iterator to the next attribute.
AVIS_PUBLIC void	attributes_set (Attributes attributes, const char name, Value *value)
	Set the value mapped to a name.
AVIS_PUBLIC void	attributes_set_nocopy (Attributes attributes, char name, Value *value)
	Same as attributes_set(), but does not copy the name first.
AVIS_PUBLIC Value *	attributes_get (Attributes attributes, const char name)
	Get the value mapped to a name.
AVIS_PUBLIC bool	attributes_contains (Attributes attributes, const char name)
	Test if the attributes contains a mapping for a given field name.
AVIS_PUBLIC Value *	attributes_remove (Attributes attributes, const char name)
	Remove the value mapped to a name.
AVIS_PUBLIC int32_t	attributes_get_int32 (Attributes attributes, const char name)
	Convenience to get an int32 value.
AVIS_PUBLIC int64_t	attributes_get_int64 (Attributes attributes, const char name)
	Convenience to get an int64 value.
AVIS_PUBLIC real64_t	attributes_get_real64 (Attributes attributes, const char name)
	Convenience to get a real64 value.
AVIS_PUBLIC const char *	attributes_get_string (Attributes attributes, const char name)
	Convenience to get a string value.
AVIS_PUBLIC Array *	attributes_get_opaque (Attributes attributes, const char name)
	Convenience to get an opaque value.
Variables
AVIS_PUBLIC_DATA Attributes	_empty_attributes