sofia-sip/su_tag.h File Reference

Detailed Description

Object-oriented tags and tag list interface.

Author:: Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Date:: Created: Tue Feb 20 19:48:18 2001 ppessi

#include <sofia-sip/su_config.h>
#include <sofia-sip/su_types.h>
#include <sofia-sip/su_alloc.h>
#include <stdarg.h>
#include <stddef.h>

Include dependency graph for su_tag.h:

Go to the source code of this file.

Data Structures

struct tagi_t

Tag item. More...

struct tag_type_s

Tag structure. More...

Defines

#define TAG_LIST

Tag list signature.

#define TAG_NULL()

Initialize a tag item marking the end of list.

#define TAG_END()

Initialize a tag item marking the end of list.

#define TAG_SKIP(x)

Initialize an empty tag item.

#define TAG_NEXT(next)

Initialize a tag item pointing to another tag list at next.

#define TAG_ANY()

Initialize a filter tag item accepting any item.

#define TAG_IF(condition, item)

Initialize a item if condition is true; otherwise, initialize an empty tag item.

#define TAG_FILTER(function)

Initialize a filter tag item accepting any item.

#define SU_ALIGN(x)

Align to pointer size.

Typedefs

typedef tag_type_s const * tag_type_t

Tag item type.

typedef intptr_t tag_value_t

Tag item value.

typedef tag_class_s const tag_class_t

Tag type class.

typedef tag_type_s const tag_typedef_t [1]

Definition of tag type.

typedef int tag_filter_f (tagi_t const *filter, tagi_t const *dest)

Prototype for filtering function used with TAG_FILTER().

Functions

int t_snprintf (tagi_t const *t, char b[], size_t size)

Convert tag item to a string.

int t_scan (tag_type_t tt, su_home_t *home, char const *s, tag_value_t *return_value)

Convert string to a tag value.

tagi_t * tl_tlist (su_home_t *, tag_type_t, tag_value_t,...)

Allocate and duplicate tagged arguments as a tag list using memory home.

size_t tl_tmove (tagi_t *dst, size_t, tag_type_t, tag_value_t,...)

Move a tag list.

int tl_gets (tagi_t const lst[], tag_type_t, tag_value_t,...)

Find tags from given list.

int tl_tgets (tagi_t lst[], tag_type_t, tag_value_t,...)

Find tags from given list.

tagi_t * tl_tfilter (su_home_t *, tagi_t const lst[], tag_type_t, tag_value_t,...)

Filter tag list src with given tags.

int tl_tremove (tagi_t lst[], tag_type_t, tag_value_t,...)

Remove listed tags from the list lst.

size_t tl_len (tagi_t const lst[])

Calculate effective length of a tag list as bytes.

size_t tl_vllen (tag_type_t tag, tag_value_t value, va_list ap)

Calculate length of a linear tag list.

size_t tl_xtra (tagi_t const lst[], size_t offset)

Calculate the size of extra memory areas associated with tag list.

tagi_t * tl_next (tagi_t const *lst)

Get next tag item from list.

tagi_t * tl_move (tagi_t *dst, tagi_t const src[])

Move a tag list.

tagi_t * tl_dup (tagi_t dst[], tagi_t const lst[], void **bb)

Duplicate a tag list.

tagi_t * tl_adup (su_home_t *, tagi_t const lst[])

Allocate and duplicate a tag list using memory home.

void tl_free (tagi_t list[])

Free a tag list.

tagi_t * tl_find (tagi_t const lst[], tag_type_t tt)

Find first tag item with type tt from list.

tagi_t * tl_find_last (tagi_t const lst[], tag_type_t tt)

Find last tag item with type tt from list.

tagi_t * tl_afilter (su_home_t *, tagi_t const filter[], tagi_t const lst[])

Filter a tag list.

tagi_t * tl_filtered_tlist (su_home_t *home, tagi_t const filter[], tag_type_t, tag_value_t,...)

Create a filtered tag list.

size_t tl_vlen (va_list ap)

Calculate length of a tag list with a va_list.

tagi_t * tl_list (tag_type_t tag, tag_value_t value,...)

Make a tag list until TAG_NEXT() or TAG_END().

tagi_t * tl_vlist (va_list ap)

Convert va_list to tag list.

tagi_t * tl_llist (tag_type_t tag, tag_value_t value,...)

Make a linear tag list until TAG_END().

tagi_t * tl_vllist (tag_type_t tag, tag_value_t value, va_list ap)

Make a linear tag list.

void tl_vfree (tagi_t *t)

Free a tag list allocated by tl_list(), tl_llist() or tl_vlist().

Variables

tag_typedef_t tag_null

End of tag list.

tag_typedef_t tag_skip

Ignore tag item.

tag_typedef_t tag_next

Jump to another tag list.

tag_typedef_t tag_any

Any tag accepted when filtering.

tag_typedef_t tag_filter

Filter tag using function as argument.

Define Documentation

#define TAG_END ( )

Initialize a tag item marking the end of list.
Equivalent to TAG_NULL().

#define TAG_FILTER ( function )

Initialize a filter tag item accepting any item.

Since:
New in 1.12.2.

#define TAG_NULL ( )

Initialize a tag item marking the end of list.
Equivalent to TAG_END().

Typedef Documentation

typedef int tag_filter_f(tagi_t const *filter, tagi_t const *dest)

Prototype for filtering function used with TAG_FILTER().

Since:
New in 1.12.2.

Function Documentation

tagi_t* tl_afilter ( su_home_t * home,

tagi_t const filter[],

tagi_t const src[]

)

Filter a tag list.
The function tl_afilter() will build a tag list containing tags specified in filter and extracted from src. It will allocate the memory used by tag list via the specified memory home, which may be also NULL.

See also:
tl_afilter(), tl_tfilter(), tl_filtered_tlist(), TAG_FILTER(), TAG_ANY(), ns_tag_class

tagi_t* tl_dup ( tagi_t dst[],

tagi_t const src[],

void ** bb

)

Duplicate a tag list.
Deep copy the tag list src to the buffer dst. Memory areas associated with src are copied to buffer at **bb.
This is a rather low-level function. See tl_adup() for a more convenient functionality.
The size of the dst buffer must be at least tl_len(src) bytes. The size of buffer **bb must be at least tl_dup_xtra(src) bytes.

Parameters:

[out] dst pointer to the destination buffer

[in] src tag list to be duplicated

[in,out] bb pointer to pointer to buffer

Returns:
A pointer to the dst list after last duplicated taglist element.
The pointer at *bb is updated to the byte after last duplicated memory area.

tagi_t* tl_filtered_tlist ( su_home_t * home,

tagi_t const filter[],

tag_type_t tag,

tag_value_t value,

...

)

Create a filtered tag list.

See also:
tl_afilter(), tl_tfilter(), TAG_FILTER(), TAG_ANY(), ns_tag_class

void tl_free ( tagi_t list[] )

Free a tag list.
The function tl_free() frees resources associated with a tag list. In other words, it calls t_free on each tag item on the list.

tagi_t* tl_move ( tagi_t * dst,

tagi_t const src[]

)

Move a tag list.
The function tl_move() copies the tag list src to the buffer dst. The size of the dst list must be at least tl_len(src) bytes.

Parameters:

dst pointer to the destination buffer

src tag list to be moved

Returns:
The function tl_move() returns a pointer to the dst list after last moved element.

tagi_t* tl_tfilter ( su_home_t * home,

tagi_t const src[],

tag_type_t tag,

tag_value_t value,

...

)

Filter tag list src with given tags.

See also:
tl_afilter(), tl_filtered_tlist(), TAG_FILTER(), TAG_ANY(), ns_tag_class

int tl_tgets ( tagi_t lst[],

tag_type_t tag,

tag_value_t value,

...

)

Find tags from given list.
Copies values of argument tag list into the reference tags in the tag list lst.

See also:
tl_gets()

size_t tl_tmove ( tagi_t * dst,

size_t size,

tag_type_t t_tag,

tag_value_t t_value,

...

)

Move a tag list.
The function tl_tmove() moves the tag list arguments to dst. The dst must have big enough for all arguments.

Parameters:

dst pointer to the destination buffer

size sizeof dst

t_tag,t_value,... tag list

Returns:
The function tl_tmove() returns number of tag list items initialized.

Variable Documentation

tag_typedef_t tag_filter

Filter tag using function as argument.

Since:
New in 1.12.2.


Data Structures
struct	tagi_t
	Tag item. More...
struct	tag_type_s
	Tag structure. More...
Defines
#define	TAG_LIST
	Tag list signature.
#define	TAG_NULL()
	Initialize a tag item marking the end of list.
#define	TAG_END()
	Initialize a tag item marking the end of list.
#define	TAG_SKIP(x)
	Initialize an empty tag item.
#define	TAG_NEXT(next)
	Initialize a tag item pointing to another tag list at next.
#define	TAG_ANY()
	Initialize a filter tag item accepting any item.
#define	TAG_IF(condition, item)
	Initialize a item if condition is true; otherwise, initialize an empty tag item.
#define	TAG_FILTER(function)
	Initialize a filter tag item accepting any item.
#define	SU_ALIGN(x)
	Align to pointer size.
Typedefs
typedef tag_type_s const *	tag_type_t
	Tag item type.
typedef intptr_t	tag_value_t
	Tag item value.
typedef tag_class_s const	tag_class_t
	Tag type class.
typedef tag_type_s const	tag_typedef_t [1]
	Definition of tag type.
typedef int	tag_filter_f (tagi_t const filter, tagi_t const dest)
	Prototype for filtering function used with TAG_FILTER().
Functions
int	t_snprintf (tagi_t const *t, char b[], size_t size)
	Convert tag item to a string.
int	t_scan (tag_type_t tt, su_home_t home, char const s, tag_value_t *return_value)
	Convert string to a tag value.
tagi_t *	tl_tlist (su_home_t *, tag_type_t, tag_value_t,...)
	Allocate and duplicate tagged arguments as a tag list using memory home.
size_t	tl_tmove (tagi_t *dst, size_t, tag_type_t, tag_value_t,...)
	Move a tag list.
int	tl_gets (tagi_t const lst[], tag_type_t, tag_value_t,...)
	Find tags from given list.
int	tl_tgets (tagi_t lst[], tag_type_t, tag_value_t,...)
	Find tags from given list.
tagi_t *	tl_tfilter (su_home_t *, tagi_t const lst[], tag_type_t, tag_value_t,...)
	Filter tag list src with given tags.
int	tl_tremove (tagi_t lst[], tag_type_t, tag_value_t,...)
	Remove listed tags from the list lst.
size_t	tl_len (tagi_t const lst[])
	Calculate effective length of a tag list as bytes.
size_t	tl_vllen (tag_type_t tag, tag_value_t value, va_list ap)
	Calculate length of a linear tag list.
size_t	tl_xtra (tagi_t const lst[], size_t offset)
	Calculate the size of extra memory areas associated with tag list.
tagi_t *	tl_next (tagi_t const *lst)
	Get next tag item from list.
tagi_t *	tl_move (tagi_t *dst, tagi_t const src[])
	Move a tag list.
tagi_t *	tl_dup (tagi_t dst[], tagi_t const lst[], void **bb)
	Duplicate a tag list.
tagi_t *	tl_adup (su_home_t *, tagi_t const lst[])
	Allocate and duplicate a tag list using memory home.
void	tl_free (tagi_t list[])
	Free a tag list.
tagi_t *	tl_find (tagi_t const lst[], tag_type_t tt)
	Find first tag item with type tt from list.
tagi_t *	tl_find_last (tagi_t const lst[], tag_type_t tt)
	Find last tag item with type tt from list.
tagi_t *	tl_afilter (su_home_t *, tagi_t const filter[], tagi_t const lst[])
	Filter a tag list.
tagi_t *	tl_filtered_tlist (su_home_t *home, tagi_t const filter[], tag_type_t, tag_value_t,...)
	Create a filtered tag list.
size_t	tl_vlen (va_list ap)
	Calculate length of a tag list with a `va_list`.
tagi_t *	tl_list (tag_type_t tag, tag_value_t value,...)
	Make a tag list until TAG_NEXT() or TAG_END().
tagi_t *	tl_vlist (va_list ap)
	Convert va_list to tag list.
tagi_t *	tl_llist (tag_type_t tag, tag_value_t value,...)
	Make a linear tag list until TAG_END().
tagi_t *	tl_vllist (tag_type_t tag, tag_value_t value, va_list ap)
	Make a linear tag list.
void	tl_vfree (tagi_t *t)
	Free a tag list allocated by tl_list(), tl_llist() or tl_vlist().
Variables
tag_typedef_t	tag_null
	End of tag list.
tag_typedef_t	tag_skip
	Ignore tag item.
tag_typedef_t	tag_next
	Jump to another tag list.
tag_typedef_t	tag_any
	Any tag accepted when filtering.
tag_typedef_t	tag_filter
	Filter tag using function as argument.