Avis Client Library: avis/attributes.h File Reference

# 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