Tag Item Lists

Object-oriented tag routines for Sofia utility library. More...

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.
Functions
void	tl_print (FILE *f, char const *title, tagi_t const lst[])
	Print tags.

---

Detailed Description

Object-oriented tag routines for Sofia utility library.

The <sofia-sip/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:

• TAG_NULL() or TAG_END() - indicates the end of tag list
• TAG_SKIP() - indicates an empty (overwritten) tag item
• TAG_NEXT() - contains a pointer to the next tag list.

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