Tag Item Lists


Detailed Description

Object-oriented tag routines for Sofia utility library.

The <su_tag.h> defines a interface to object-oriented tag list routines. A tag list is a linear list (array) of tag items, tagi_t structures, terminated by a TAG_END() item. Each tag item has a label, tag, (t_tag) and a value (t_value). The tag is a pointer (tag_type_t) to a structure defining how the value should be interpreted, in other words, the name and the type of the value. The value or pointer to the actual value is stored as opaque data (tag_value_t). The tag item structure is defined as follows:

 typedef struct {
   tag_type_t   t_tag;
   tag_value_t  t_value;
 } tagi_t;

The tag lists are central concept in the Sofia APIs. The tags lists can be used to a list of named arguments to a tagarg function, to store variable amount of data in a memory area, and pass data between processes and threads.

The tagged argument lists can be used like named arguments in higher-level languages. The argument list consists of tag-value pairs; tags specify the name and type of the value. All the tag items are not necessarily interpreted by the called function, but it can pass the list to other functions. This feature is used also by the Sofia APIs, the lower-layer settings and options are frequently passed through the upper-layer API in the tag lists.

The tagged argument lists are constructed using special macros that expand to two function arguments, tag and value. Each tag item macro checks its arguments type so the tagged argument lists are typesafe if the list is correctly constructed.

Each function documents the tags it accepts and also the tags it may pass to the lower layers (at least in theory).

Special Tags
There are a new special tags that are used to control and modify the tag list processing itself. These special tags are as follows:

The tag type structures are declared as tag_typedef_t. They can be defined by the macros found in <su_tag_class.h>. See nta_tag.c or su_tag_test.c for an example.


Files

file  su_tag.h
 Object-oriented tags and tag list interface.
file  su_tag_class.h
 Tag class interface for object-oriented tags.
file  su_tag_inline.h
 Inline functions for object tags and tag lists.
file  su_tag_io.h
 I/O interface for tag lists.
file  su_tagarg.h
 Tagged argument lists.
file  su_tag.c
 Special tags.
file  su_tag_io.c
 Printing tag lists.
file  su_taglist.c
 Implementation of tag items and lists.


Sofia-SIP 1.12.6 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.