sofia-sip/su_tag.h File Reference

Object-oriented tags and tag list interface. More...

#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	SU_TAG_H
	Defined when <sofia-sip/su_tag.h> has been included.
#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 struct tag_type_s const *	tag_type_t
	Tag item type.
typedef intptr_t	tag_value_t
	Tag item value.
typedef struct tag_class_s const	tag_class_t
	Tag type class.
typedef struct 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.

---

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

---

Define Documentation

#define SU_TAG_H

Defined when <sofia-sip/su_tag.h> has been included.

#define TAG_ANY

(

)

Initialize a filter tag item accepting any item.

#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_IF	(		condition,
			item
	)

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

#define TAG_NEXT

(

next

)

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

#define TAG_NULL

(

)

Initialize a tag item marking the end of list.

Equivalent to TAG_END().

#define TAG_SKIP

(

x

)

Initialize an empty tag item.

---

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.

typedef struct tag_type_s const tag_typedef_t[1]

Definition of tag type.

---

Function Documentation

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

Allocate and duplicate a tag list using memory home.

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

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.

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.

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

Find tags from given list.

size_t tl_len

(

tagi_t const

lst[]

)

Calculate effective length of a tag list as bytes.

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()

tagi_t* tl_tlist	(	su_home_t *	home,
		tag_type_t	tag,
		tag_value_t	value,
			...
	)

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

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.

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

Remove listed tags from the list lst.

void tl_vfree

(

tagi_t *

t

)

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

size_t tl_vlen

(

va_list

ap

)

Calculate length of a tag list with a va_list.

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

Calculate length of a linear tag list.

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

Make 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.

---

Variable Documentation

tag_typedef_t tag_any

Any tag accepted when filtering.

tag_typedef_t tag_filter

Filter tag using function as argument.

Since:

New in 1.12.2.

tag_typedef_t tag_skip

Ignore tag item.