Common libraries for SIP Express Router

Václav Kubart

Table of Contents

Usage of common libraries

1. Introduction

1. About

2. Dependencies

2.1. libcds dependencies
2.2. libxcap dependencies
2.3. libpresence dependencies

2. Installation and usage

1. Usage with SIP Express Router

1.1. Installation steps
1.2. Running SER

Common Data Structures (libcds)

Preface

1. Conventions
2. Dependencies

I. Reference

I. Memory operations

cds_malloc — memory allocation
cds_free — free allocated memory
cds_malloc_ptr — pointer to cds_malloc function independent on cds_malloc implementation (macro, ...)
cds_free_ptr — pointer to cds_free function independent on cds_free implementation (macro, ...)

II. String

str_t — data structure for string representation
str_dup — string duplication functions
str_clear — string initialization function
str_free — destroys string
str_free_content — frees content of a string
helper functions — various string helper functions

III. Dynamic string

dstring_t — data structure for dynamic string representation
dstr_init — initialization and destruction of dstring_t structure
dstr_append — append string to dstring_t structure
dstr_get_data — exporting data from dstring_t structure

IV. Serialization

sstream_t — input/output serialization stream
init_input_sstream — initializes input serialization stream
init_output_sstream — initializes serialization stream for output
get_serialized_sstream — get output stream data
destroy_sstream — destroys input/output serialization stream
sstream_put — store data into output stream
sstream_put_str — store data into output stream
sstream_put_zt — store data into output stream
sstream_get — read data from input stream
sstream_get_str — read data from input stream
sstream_get_str_ex — read data from input stream
serialize_int — integer serialization
serialize_uint — unsigned integer serialization
serialize_char — character serialization
serialize_uchar — unsigned character serialization
serialize_str — string serialization

V. Synchronization

cds_mutex_t — wrapper type for mutex
cds_mutex_init — mutex initialization
cds_mutex_destroy — mutex destruction
cds_mutex_lock — mutex lock
cds_mutex_unlock — mutex unlock

VI. Message queue

msg_queue_t — message queue data structure
mq_message_t — message data structure
msg_queue_init — message queue initialization
msg_queue_init_ex — message queue initialization
msg_queue_destroy — destroy message queue
push_message — push message into message queue
pop_message — pop message from the queue
is_msg_queue_empty — test if message queue empty
create_message — allocates and initializes message
create_message_ex — create and initialize message
init_message_ex — initialize message
set_data_destroy_function — set function used to deallocate message data
free_message — free message

XCAP operations (libxcap)

Preface

1. Dependencies

Presence utilities and data types (libpresence)

Preface

1. Dependencies

Usage of common libraries

Václav Kubart

Abstract

Installation and usage of common libraries.

Table of Contents

1. Introduction

1. About

2. Dependencies

2.1. libcds dependencies
2.2. libxcap dependencies
2.3. libpresence dependencies

2. Installation and usage

1. Usage with SIP Express Router

1.1. Installation steps
1.2. Running SER

Chapter 1. Introduction

Table of Contents

1. About

2. Dependencies

2.1. libcds dependencies
2.2. libxcap dependencies
2.3. libpresence dependencies

1. About

Common libraries are originaly determined for usage with SER - as a collection of useful functions which are not present in the SER's code. But as the time goes it seems to be good to make them usable without SER too, at least for testing parts of SER modules and thus it is possible to use them alone now.

2. Dependencies

2.1. libcds dependencies

This library depends only on standard C libraries and needs no other external libraries.

2.2. libxcap dependencies

libcds (distributed with SER)
libxml2 (external library for parsing XML documents)
libcurl3 (external library for HTTP operations, used only in nonSER version!)

2.3. libpresence dependencies

libcds (distributed with SER)

Chapter 2. Installation and usage

Table of Contents

1. Usage with SIP Express Router

1.1. Installation steps
1.2. Running SER

Before installation is needed to install external libraries according to dependencies.

1. Usage with SIP Express Router

These libraries are distributed together with SER, but they are not compiled together with other SER code. They must be compiled separately, before compiling SER modules which use them.

There is standalone makefile for compilation with SER named Makefile.ser.

1.1. Installation steps

There is an example of steps which need to be done while installing SER with these libraries into directory /base/ser/directory (if no directory specified - no prefix parameter given - default value is used: /usr/local/)

Download current ser sources:

cvs -d :pserver:anonymous@cvs.berlios.de:/cvsroot/ser checkout sip_router
Compile and install libraries for usage with SER:

cd sip_router/lib

make -f Makefile.ser install prefix=/base/ser/directory
Compile and install SER

cd ..

make install prefix=/base/ser/directory

1.2. Running SER

Linker used for dynamic linking must know, where to find these libraries. This may be done by setting LD_LIBRARY_PATH before startup.

export LD_LIBRARY_PATH=/base/ser/directory/lib/ser

/base/ser/directory/sbin/ser -f /base/ser/directory/etc/ser/ser.cfg

Common Data Structures (libcds)

Václav Kubart

Abstract

Description of CDS (Common Data Structures) library.

Table of Contents

Preface

1. Conventions
2. Dependencies

I. Reference

I. Memory operations

cds_malloc — memory allocation
cds_free — free allocated memory
cds_malloc_ptr — pointer to cds_malloc function independent on cds_malloc implementation (macro, ...)
cds_free_ptr — pointer to cds_free function independent on cds_free implementation (macro, ...)

II. String

str_t — data structure for string representation
str_dup — string duplication functions
str_clear — string initialization function
str_free — destroys string
str_free_content — frees content of a string
helper functions — various string helper functions

III. Dynamic string

dstring_t — data structure for dynamic string representation
dstr_init — initialization and destruction of dstring_t structure
dstr_append — append string to dstring_t structure
dstr_get_data — exporting data from dstring_t structure

IV. Serialization

sstream_t — input/output serialization stream
init_input_sstream — initializes input serialization stream
init_output_sstream — initializes serialization stream for output
get_serialized_sstream — get output stream data
destroy_sstream — destroys input/output serialization stream
sstream_put — store data into output stream
sstream_put_str — store data into output stream
sstream_put_zt — store data into output stream
sstream_get — read data from input stream
sstream_get_str — read data from input stream
sstream_get_str_ex — read data from input stream
serialize_int — integer serialization
serialize_uint — unsigned integer serialization
serialize_char — character serialization
serialize_uchar — unsigned character serialization
serialize_str — string serialization

V. Synchronization

cds_mutex_t — wrapper type for mutex
cds_mutex_init — mutex initialization
cds_mutex_destroy — mutex destruction
cds_mutex_lock — mutex lock
cds_mutex_unlock — mutex unlock

VI. Message queue

msg_queue_t — message queue data structure
mq_message_t — message data structure
msg_queue_init — message queue initialization
msg_queue_init_ex — message queue initialization
msg_queue_destroy — destroy message queue
push_message — push message into message queue
pop_message — pop message from the queue
is_msg_queue_empty — test if message queue empty
create_message — allocates and initializes message
create_message_ex — create and initialize message
init_message_ex — initialize message
set_data_destroy_function — set function used to deallocate message data
free_message — free message

List of Examples

1. Usage with create_message_ex
2. Usage with create_message

Preface

Table of Contents

1. Conventions
2. Dependencies

This library contains many useful functions and data structures. It is possible to use it with Sip Express Router (SER) or without it. In the first case it is able to use some internal SER's data types like strings.

1. Conventions

There is list of conventions used in this library:

data types (structures, enums, ...) have their names with suffix “_t” (dstring_t, str_t, ...)
many functions have prefix according to data structure on which are operating (like dstr_append which operates on dstring_t data structure)
most functions return 0 as successful result and nonzero value as error

2. Dependencies

This library depends only on standard C libraries and needs no other external libraries.

Part I. Reference

Table of Contents

I. Memory operations

cds_malloc — memory allocation
cds_free — free allocated memory
cds_malloc_ptr — pointer to cds_malloc function independent on cds_malloc implementation (macro, ...)
cds_free_ptr — pointer to cds_free function independent on cds_free implementation (macro, ...)

II. String

str_t — data structure for string representation
str_dup — string duplication functions
str_clear — string initialization function
str_free — destroys string
str_free_content — frees content of a string
helper functions — various string helper functions

III. Dynamic string

dstring_t — data structure for dynamic string representation
dstr_init — initialization and destruction of dstring_t structure
dstr_append — append string to dstring_t structure
dstr_get_data — exporting data from dstring_t structure

IV. Serialization

sstream_t — input/output serialization stream
init_input_sstream — initializes input serialization stream
init_output_sstream — initializes serialization stream for output
get_serialized_sstream — get output stream data
destroy_sstream — destroys input/output serialization stream
sstream_put — store data into output stream
sstream_put_str — store data into output stream
sstream_put_zt — store data into output stream
sstream_get — read data from input stream
sstream_get_str — read data from input stream
sstream_get_str_ex — read data from input stream
serialize_int — integer serialization
serialize_uint — unsigned integer serialization
serialize_char — character serialization
serialize_uchar — unsigned character serialization
serialize_str — string serialization

V. Synchronization

cds_mutex_t — wrapper type for mutex
cds_mutex_init — mutex initialization
cds_mutex_destroy — mutex destruction
cds_mutex_lock — mutex lock
cds_mutex_unlock — mutex unlock

VI. Message queue

msg_queue_t — message queue data structure
mq_message_t — message data structure
msg_queue_init — message queue initialization
msg_queue_init_ex — message queue initialization
msg_queue_destroy — destroy message queue
push_message — push message into message queue
pop_message — pop message from the queue
is_msg_queue_empty — test if message queue empty
create_message — allocates and initializes message
create_message_ex — create and initialize message
init_message_ex — initialize message
set_data_destroy_function — set function used to deallocate message data
free_message — free message

Memory operations

Memory operations are common for whole CDS library. Because it must work together with SER's memory management and must work without it too, there are wrapper macros for memory allocation/deallocation.

These macros were functions and it may change in the future, but macros are probably better - they allow better debuging than functions. There are defined another macros (see cds_malloc_ptr(3), cds_free_ptr(3)), which point and will point to allocation/deallocation functions, thus they may be used as function pointers.

It is possible to redefine these macros/functions to help with memory debugging or for monitoring purposes or so.

Table of Contents

cds_malloc — memory allocation
cds_free — free allocated memory
cds_malloc_ptr — pointer to cds_malloc function independent on cds_malloc implementation (macro, ...)
cds_free_ptr — pointer to cds_free function independent on cds_free implementation (macro, ...)

Name

cds_malloc — memory allocation

Synopsis

#include <cds/memory.h>

void *cds_malloc( size);

unsigned int size;

Description

Allocates Memory of given size. If compiled with SER it internaly uses shm_malloc, if compiled without SER it uses malloc.

Return value

Returns NULL on error, pointer to allocated memory otherwise.

Name

cds_free — free allocated memory

Synopsis

#include <cds/memory.h>

void cds_free( ptr);

void *ptr;

Description

Frees memory allocated using cds_malloc.

Return value

Returns 0 on success, non-zero on error.

Name

cds_malloc_ptr — pointer to cds_malloc function independent on cds_malloc implementation (macro, ...)

Synopsis

#include <cds/memory.h>

void *cds_malloc_ptr( size);

unsigned int size;

Description

Pointer to memory allocation function. It is independent on cds_malloc implementation.

Name

cds_free_ptr — pointer to cds_free function independent on cds_free implementation (macro, ...)

Synopsis

#include <cds/memory.h>

void cds_free_ptr( ptr);

void *ptr;

Description

Pointer to memory deallocation function. It is independent on cds_free implementation.

String

String is basic data structure. Standard zero terminated C strings have some bad properties which may slow down processing or disallow use of binary values. This structure is an attempt to do it better :-).

This structure was taken from SIP Express Router due to it's usability and need of testing some parts of SER's code outside of “SER's environment”. Many of string functions were inspired by or directly taken from SER's code. Another reason for this structure was to put string operations to one place and not leave them independently and often duplictly in SER's modules.

Table of Contents

str_t — data structure for string representation
str_dup — string duplication functions
str_clear — string initialization function
str_free — destroys string
str_free_content — frees content of a string
helper functions — various string helper functions

Name

str_t — data structure for string representation

Synopsis

#include <cds/sstr.h>

outside of SIP Express Router:

typedef struct {
	char *s;
	int len;
} str_t;

inside of SIP Express Router:

typedef str str_t;

Description

This structure represents string. If compiled with SER it is defined using SER string defined elsewhere:

typedef str str_t;

Otherwise it is defined as structure containing pointer to data buffer and length of this buffer.

Name

str_dup, str_dup_new, str_dup_zt — string duplication functions

Synopsis

#include <cds/sstr.h>

`int str_dup(`	`dst`,
	`src)`;

str_t *dst;
const str_t *src;

`int str_dup_new(`	`dst`,
	`src)`;

str_t *dst;
const char *src;

int str_dup_zt( src);

const str_t *src;

Description

All these functions allocates necessary memory using cds_malloc.

str_dup takes as source the string given in src

str_dup_zt takes as source zero-terminated string given in src

str_dup_new works like str_dup with the difference, that it allocates not only the data buffer, but the destination str_t structure too.

Return value

All these functions return 0 if successful, nonzero otherwise.

Name

str_clear — string initialization function

Synopsis

#include <cds/sstr.h>

void str_clear( s);

str_t *s;

Description

Clears the given string - it sets string length to 0 and pointer to data to NULL

Name

str_free — destroys string

Synopsis

#include <cds/sstr.h>

void str_free( s);

str_t *s;

Description

Frees string's data like str_free_content, and the frees the str_t structure too. It uses cds_free as memory deallocation function.

Name

str_free_content — frees content of a string

Synopsis

#include <cds/sstr.h>

void str_free_content( s);

str_t *s;

Description

Frees string's data if allocated (length > 0 and pointer is not NULL) and clears its content like str_clear. It uses cds_free as memory deallocation function.

Name

zt2str, is_str_empty, zt_strdup, str_prefix, str_strchr — various string helper functions

Synopsis

#include <cds/sstr.h>

str_t zt2str( s);

char *s;

int is_str_empty( s);

const str_t *s;

char *zt_strdup( src);

const char *src;

`int str_prefix(`	`a`,
	`b)`;

const str_t *a;
const str_t *b;

`char *str_strchr(`	`s`,
	`c)`;

const str_t *s;
char c;

Description

zt2str converts zero terminated string to str_t. It doesn't copy data - both strings use the same buffer!

is_str_empty returns 1 if given string is empty (NULL pointer or length < 1 or NULL pointer to string data)

zt_strdup duplicates given zero terminated string to another zero terminated string using cds_malloc function

str_prefix returns 0 if string b is prefix of a, nonzero otherwise (deprecated)

str_strchr searches for given character. It returns pointer to it in the string or NULL if not found.

Dynamic string

Dynamic string is data structure used for simple string operations hiding internal operations like memory allocations from the user.

Functions and data structures for dynamic string are declared in dstring.h.

Table of Contents

dstring_t — data structure for dynamic string representation
dstr_init — initialization and destruction of dstring_t structure
dstr_append — append string to dstring_t structure
dstr_get_data — exporting data from dstring_t structure

Name

dstring_t — data structure for dynamic string representation

Synopsis

#include <cds/dstring.h>

typedef struct _dstring_t {
	dlink_t buffers;
	int len;
	int buff_size;
} dstring_t;

Description

This structure represents dynamic string. It allows concatenation of multiple strings without worry about memory allocations.

Internaly it uses list of data buffers which are allocated if needed. The content of dynamic string may be copied out from internal buffers using simple function call (see dstr_get_data(3)). Internal buffers are allocated in package memory (when compiled with SER)!

This structure is used as base for simple object serialization (see Serialization).

Members

buffers: linked list of allocated data buffers
len: whole string length
buff_size: size of newly allocated buffers

Warning - structure internals may change! For manipulation use manipulation functions.

Example

#include <cds/dstring.h>
#include <cds/sstr.h>

int main(int argc, char **argv)
{
	dstring_t str;
	str_t s;

	dstr_init(&str, 256);
	dstr_append_zt(&str,"This is a ");
	dstr_append_zt(&str,"very long ");
	dstr_append_zt(&str,"string.");
	if (dstr_get_str(&str, &s) == 0) {
		printf("result: %.*s\n", FMT_STR(s));	
		str_free_content(&s);
	}
	dstr_destroy(&str);

	return 0;
}

This will result in

result: This is a very long string.

Todo

Create a function like sprintf.

Name

dstr_init, dstr_destroy — initialization and destruction of dstring_t structure

Synopsis

#include <cds/dstring.h>

`int dstr_init(`	`dstr`,
	`buff_size)`;

dstring_t *dstr;
int buff_size;

int dstr_destroy( dstr);

dstring_t *dstr;

Description

dstr_init function initializes dstring_t structure. The value of buff_size is the size of newly allocated data buffers. These buffers are internal and are allocated if needed by any of dstring functions.

dstr_destroy function destroys all allocated data buffers. After calling dstr_destroy can't be called any of dstring manipulation functions except dstr_init.

Return value

Both functions return 0 if successful, nonzero otherwise.

Name

dstr_append, dstr_append_str, dstr_append_zt — append string to dstring_t structure

Synopsis

#include <cds/dstring.h>

`int dstr_append(`	`dstr`,
	`s`,
	`len)`;

dstring_t *dstr;
const char *s;
int len;

`int dstr_append_str(`	`dstr`,
	`s)`;

dstring_t *dstr;
const str_t *s;

`int dstr_append_zt(`	`dstr`,
	`s)`;

dstring_t *dstr;
const char *s;

Description

All these functions are used for appending strings to dynamic string. They differ only in the string and its length specification.

dstr_append: appends data from buffer s of length len
dstr_append_str: appends content of string s (see str_t(3))
dstr_append_zt: appends content of zero terminated string s

Return value

All these functions return 0 if successful, nonzero otherwise.

Name

dstr_get_data, dstr_get_data_length, dstr_get_data_str — exporting data from dstring_t structure

Synopsis

#include <cds/dstring.h>

int dstr_get_data_length( dstr);

dstring_t *dstr;

`int dstr_get_data(`	`dstr`,
	`dst)`;

dstring_t *dstr;
char *dst;

`int dstr_get_data_str(`	`dstr`,
	`dst)`;

dstring_t *dstr;
str_t *dst;

Description

dstr_get_data_length function is used to determine the size of data present in dynamic string. It returns negative value on error.

dstr_get_data copies data from internal buffers into given character array allocated by caller. The data size can be determined by dstr_get_data_length call.

dstr_get_data_str copies data from internal buffers into internally allocated string. This string is returned in the dst parameter.

Return value

Functions dstr_get_data and dstr_get_data_str return 0 if successful, nonzero otherwise.

Function dstr_get_data_length returns negative value on error, zero if there is no data in dynamic string and positive if there was no error and data present.

Serialization

Serialization is a simple way to store and load data structures. It is used for example for storing SIP dialogs into database in SER's PA module.

There is a set of functions for serializing basic data elements (strings, numbers, ...). These functions can be used as base for complex structures serialization (see the section called “Example”).

Table of Contents

sstream_t — input/output serialization stream
init_input_sstream — initializes input serialization stream
init_output_sstream — initializes serialization stream for output
get_serialized_sstream — get output stream data
destroy_sstream — destroys input/output serialization stream
sstream_put — store data into output stream
sstream_put_str — store data into output stream
sstream_put_zt — store data into output stream
sstream_get — read data from input stream
sstream_get_str — read data from input stream
sstream_get_str_ex — read data from input stream
serialize_int — integer serialization
serialize_uint — unsigned integer serialization
serialize_char — character serialization
serialize_uchar — unsigned character serialization
serialize_str — string serialization

Name

sstream_t — input/output serialization stream

Synopsis

#include <cds/serialize.h>

typedef struct {
	dstring_t out;
	str_t in;
	int in_pos;
	enum { sstream_in, sstream_out } type;
} sstream_t;

Description

This structure represents input and output serialization stream.

Members

out: Dynamic string holding output data in the case of output stream.
in: String holding input data in the case of input stream.
in_pos: Actual position in input data (points to first unread char) in the case of input stream.
type: Member holding stream type - input or output.

Warning - internals of this data structure may change! Use it only through manipulation functions.

Example

#include <cds/sstr.h>
#include <cds/serialize.h>

typedef struct {
	str_t name;
	int number;
	char c;
} test_t;

int serialize_test_struct(sstream_t *store, test_t *t)
{
	if (serialize_str(store, &t->name) != 0) return -1;
	if (serialize_int(store, &t->number) != 0) return -1;
	if (serialize_char(store, &t->c) != 0) return -1;
	return 0;
}

int main(int argc, char **argv)
{
	sstream_t store;
	str_t data;
	test_t a = { name: {"test A", 6}, number: 13, c: 'x' };
	test_t b;

	str_clear(&data);

	/* storing structure to the string */
	
	init_output_sstream(&store, 256);
	if (serialize_test_struct(&store, &a) == 0) {
		if (get_serialized_sstream(&store, &data) != 0)
			printf("can't get data\n");
	}
	else printf("can't serialize\n");
	destroy_sstream(&store);

	/* loading structure from the string */
	
	init_input_sstream(&store, data.s, data.len);
	if (serialize_test_struct(&store, &b) == 0) {
		printf("test_t = { %.*s, %d, %c }\n", 
			FMT_STR(b.name), b.number, b.c);
		
		/* cleanup */
		str_free_content(&b.name);
	}
	else printf("can't deserialize\n");
	destroy_sstream(&store);

	/* cleanup */
	str_free_content(&data);

	return 0;
}

Name

init_input_sstream — initializes input serialization stream

Synopsis

#include <cds/serialize.h>

`int init_input_sstream(`	`ss`,
	`data_in`,
	`data_len)`;

sstream_t *ss;
char *data_in;
int data_len;

Description

Initializes serialization stream as input. Input data are read from char array given by pointer data_in and length data_len.

Return value

Returns 0 if successful, nonzero otherwise.

Name

init_output_sstream — initializes serialization stream for output

Synopsis

#include <cds/serialize.h>

`int init_output_sstream(`	`ss`,
	`out_buff_resize)`;

sstream_t *ss;
int out_buff_resize;

Description

Initializes given serialization stream for output. Parameter out_buff_resize is stored into sstream_t structure and specifies the size of newly allocated data buffers. Data buffers are allocated when needed during output.

Return value

Returns 0 on success, non-zero on error.

Name

get_serialized_sstream — get output stream data

Synopsis

#include <cds/serialize.h>

`int get_serialized_sstream(`	`ss`,
	`dst)`;

sstream_t *ss;
str_t *dst;

Description

Copies data stored during output serialization into given destination. It allocates buffer necessary for serialized data using cds_malloc function. These data can be freed using str_free_content.

Return value

Returns 0 on success, non-zero on error.

Name

destroy_sstream — destroys input/output serialization stream

Synopsis

#include <cds/serialize.h>

void destroy_sstream( ss);

sstream_t *ss;

Description

Destroys serialization stream and frees all internal data buffers. After calling this function can NOT be called any other serialization stream manipulation function except init_input_sstream or init_ouput_stream.

Name

sstream_put — store data into output stream

Synopsis

#include <cds/serialize.h>

`int sstream_put(`	`ss`,
	`s`,
	`len)`;

sstream_t *ss;
const char *s;
int len;

Description

Stores data into output stream. It copies data of size len from memory at address s into internal data buffers.

Return value

Returns 0 on success, non-zero on error.

Name

sstream_put_str — store data into output stream

Synopsis

#include <cds/serialize.h>

`int sstream_put_str(`	`ss`,
	`s)`;

sstream_t *ss;
const str_t *s;

Description

Stores data into output stream. It copies data from given string into internal data buffers.

Return value

Returns 0 on success, non-zero on error.

Name

sstream_put_zt — store data into output stream

Synopsis

#include <cds/serialize.h>

`int sstream_put_zt(`	`ss`,
	`s)`;

sstream_t *ss;
const char *s;

Description

Stores data into output stream. It copies data from zero-terminated string s into internal data buffers.

Return value

Returns 0 on success, non-zero on error.

Name

sstream_get — read data from input stream

Synopsis

#include <cds/serialize.h>

`int sstream_get(`	`ss`,
	`c)`;

sstream_t *ss;
char *c;

Description

Reads a character from input stream into c.

Return value

Returns 0 on success, non-zero on error.

Name

sstream_get_str — read data from input stream

Synopsis

#include <cds/serialize.h>

`int sstream_get_str(`	`ss`,
	`length`,
	`dst)`;

sstream_t *ss;
int length;
str_t *dst;

Description

Reads len bytes from input stream makes a copy of them and returns them in string dst. For allocation it uses cds_malloc function. The string may be freed using for example str_free_content. If there is not enough data to read (less than len bytes), the function returns error.

Return value

Returns 0 on success, non-zero on error.

Name

sstream_get_str_ex — read data from input stream

Synopsis

#include <cds/serialize.h>

`int sstream_get_str_ex(`	`ss`,
	`len`,
	`dst)`;

sstream_t *ss;
int len;
str_t *dst;

Description

Returns data buffer of requested length (len). If there is not enough data to read (less than len bytes), the function returns error. The memory can NOT be freed becausse it is a part of input buffer!

Return value

Returns 0 on success, non-zero on error.

Name

serialize_int — integer serialization

Synopsis

#include <cds/serialize.h>

`int serialize_int(`	`ss`,
	`num)`;

sstream_t *ss;
int *num;

Description

Serializes number. This means that in case of input stream this functions sets value of given integer parameter to value read from stream, in case of output stream it writes the number given in parameter into that stream.

Return value

Returns 0 on success, non-zero on error.

Name

serialize_uint — unsigned integer serialization

Synopsis

#include <cds/serialize.h>

`int serialize_uint(`	`ss`,
	`num)`;

sstream_t *ss;
unsigned int *num;

Description

Serializes number. This means that in the case of input stream this functions sets value of given unsigned integer parameter to value read from stream, in the case of output stream it writes the number given in parameter into that stream.

Return value

Returns 0 on success, non-zero on error.

Name

serialize_char — character serialization

Synopsis

#include <cds/serialize.h>

`int serialize_char(`	`ss`,
	`c)`;

sstream_t *ss;
char *c;

Description

Serializes character. This means that in the case of input stream this functions sets value of given character parameter to value read from stream, in the case of output stream it writes the character given in parameter into that stream.

Return value

Returns 0 on success, non-zero on error.

Name

serialize_uchar — unsigned character serialization

Synopsis

#include <cds/serialize.h>

`int serialize_uchar(`	`ss`,
	`c)`;

sstream_t *ss;
unsigned char *c;

Description

Serializes unsigned character. This means that in the case of input stream this functions sets value of given character parameter to value read from stream, in the case of output stream it writes the character given in parameter into that stream.

Return value

Returns 0 on success, non-zero on error.

Name

serialize_str — string serialization

Synopsis

#include <cds/serialize.h>

`int serialize_str(`	`ss`,
	`s)`;

sstream_t *ss;
str_t *s;

Description

Serializes string. This means that in the case of input stream this functions reads string from the stream (allocated using cds_malloc), in the case of output stream it writes the given string into that stream.

Return value

Returns 0 on success, non-zero on error.

Synchronization

Interprocess synchronization functions and data structures are specific for SER. There are some wrapper macros for them in the CDS library.

Table of Contents

cds_mutex_t — wrapper type for mutex
cds_mutex_init — mutex initialization
cds_mutex_destroy — mutex destruction
cds_mutex_lock — mutex lock
cds_mutex_unlock — mutex unlock

Name

cds_mutex_t — wrapper type for mutex

Synopsis

#include <cds/sync.h>

outside of SIP Express Router:

#include <pthread.h>
#define cds_mutex_t   pthread_mutex_t

inside of SIP Express Router:

#define cds_mutex_t   gen_lock_t

Description

Wrapper type for mutex. It is defined as macro now, but this may change.

Name

cds_mutex_init — mutex initialization

Synopsis

#include <cds/sync.h>

int cds_mutex_init( m);

cds_mutex_t *m;

Description

Initializes mutex. It is defined as macro now thus type control and return value specification may be problematic!

Name

cds_mutex_destroy — mutex destruction

Synopsis

#include <cds/sync.h>

int cds_mutex_destroy( m);

cds_mutex_t *m;

Description

Destroys mutex. It is defined as macro now thus type control and return value specification may be problematic!

Name

cds_mutex_lock — mutex lock

Synopsis

#include <cds/sync.h>

int cds_mutex_lock( m);

cds_mutex_t *m;

Description

Locks mutex. It is defined as macro now thus type control and return value specification may be problematic!

Name

cds_mutex_unlock — mutex unlock

Synopsis

#include <cds/sync.h>

int cds_mutex_unlock( m);

cds_mutex_t *m;

Description

Unlocks mutex. It is defined as macro now thus type control and return value specification may be problematic!

Message queue

Message queue is implementation of simple FIFO. It is declared in msg_queue.h.

Table of Contents

msg_queue_t — message queue data structure
mq_message_t — message data structure
msg_queue_init — message queue initialization
msg_queue_init_ex — message queue initialization
msg_queue_destroy — destroy message queue
push_message — push message into message queue
pop_message — pop message from the queue
is_msg_queue_empty — test if message queue empty
create_message — allocates and initializes message
create_message_ex — create and initialize message
init_message_ex — initialize message
set_data_destroy_function — set function used to deallocate message data
free_message — free message

Name

msg_queue_t — message queue data structure

Synopsis

#include <cds/msg_queue.h>

typedef struct msg_queue {
	mq_message_t *first;
	mq_message_t *last;
	cds_mutex_t q_mutex;
	int use_mutex;
} msg_queue_t;

Description

Message queue is implemented as simple linked list of elements. Message queue may be locked or not - it depends on initialization.

Warning: internal implementation of this structure may change, use it only through existing functions.

Name

mq_message_t — message data structure

Synopsis

#include <cds/msg_queue.h>

typedef struct _mq_message_t {
	void *data;
	int data_len;
	struct _mq_message_t *next;
	destroy_function_f destroy_function;
	enum { 
		message_allocated_with_data, 
		message_holding_data_ptr 
	} allocation_style;
	char data_buf[1];
} mq_message_t;

Description

Data structure used as basic element in message queue. Pointer to message data should be obtained by get_message_data.

There are more possibilities how to allocate message data:

explicitly, data buffer is allocated outside of mq_message_t structure and only pointer to it is stored in this structure, see create_message(3)
implicitly, data buffer is allocated together with mq_message_t structure - data must be copied into it after structure allocation, see create_message_ex(3)
there is third possibility, that data and message - both - are allocated by caller without using create_message, create_message_ex and msg_free, see init_message_ex(3)

More different data allocation methods are due to more efficiency - less memory allocation calls and less fragmentation in second case, but more common and may be simpler for usage in first case.

Warning: internal implementation of this structure may change, use it only through existing functions.

Name

msg_queue_init — message queue initialization

Synopsis

#include <cds/msg_queue.h>

int msg_queue_init( q);

msg_queue_t *q;

Description

Initializes synchronized (using internal mutex) message queue structure.

Return value

Returns 0 on success, non-zero on error.

Name

msg_queue_init_ex — message queue initialization

Synopsis

#include <cds/msg_queue.h>

`int msg_queue_init_ex(`	`q`,
	`synchronized)`;

msg_queue_t *q;
int synchronized;

Description

Initializes message queue structure. The value of synchronized may be 0 or 1. Zero means, that the message queue will not use mutex for internal data access (will be NOT synchronized), 1 means that message queue will be synchronized by mutex created internaly.

Return value

Returns 0 on success, non-zero on error.

Name

msg_queue_destroy — destroy message queue

Synopsis

#include <cds/msg_queue.h>

void msg_queue_destroy( q);

msg_queue_t *q;

Description

Destroys initialized message queue. After calling msg_queue_destroy can not be called any of message queue manipulation functions except msg_queue_init.

All messages which stay in the queue are automaticaly freed using free_message.

Name

push_message — push message into message queue

Synopsis

#include <cds/msg_queue.h>

`int push_message(`	`q`,
	`msg)`;

msg_queue_t *q;
mq_message_t *msg;

Description

Function pushes initialized message into message queue. This message may be removed from the queue using pop_message. Unremoved messages are automaticaly freed by msg_queue_destroy (depending on message initialization, see create_message(3), create_message_ex(3) and init_message_ex(3)).

Return value

Returns 0 on success, non-zero on error.

Name

pop_message — pop message from the queue

Synopsis

#include <cds/msg_queue.h>

mq_message_t *pop_message( q);

msg_queue_t *q;

Description

Removes first message from the queue. If the queue is empty or an error occured it returns NULL value. Removed messages are NOT automaticaly freed - caller must use free_message or free it itself (see free_message(3))!

Return value

Returns pointer to message removed from the queue. If the queue is empty or an error occured the return value is NULL.

Name

is_msg_queue_empty — test if message queue empty

Synopsis

#include <cds/msg_queue.h>

int is_msg_queue_empty( q);

msg_queue_t *q;

Description

Tests message queue if it is empty.

Return value

Returns nonzero if message queue empty, zero otherwise.

Name

create_message — allocates and initializes message

Synopsis

#include <cds/msg_queue.h>

`int create_message(`	`data`,
	`data_len)`;

void *data;
int data_len;

Description

Allocates message using cds_malloc and initializes its content so it will be freed automaticaly. Pointer to the explicitly allocated data is set to data and its length is set to data_len. Message created by create_message should be freed using message_free.

Unremoved messages created this way are freed automaticaly in msg_queue_destroy using free_message.

Calling free_message to such message frees the message and the data given by parameter data too, thus they can NOT be freed by the caller!

Return value

Returns NULL on error, pointer to initialized message structure otherwise.

Name

create_message_ex — create and initialize message

Synopsis

#include <cds/msg_queue.h>

mq_message_t *create_message_ex( data_len);

int data_len;

Description

Allocates message with data of given size (data_len) using cds_malloc. It initializes message content so it will be freed automaticaly. Pointer to allocated data should be obtained by get_message_data.

Messages created by create_message_ex should be freed using message_free.

Unremoved messages created this way are freed automaticaly in msg_queue_destroy using free_message.

Return value

Returns NULL on error, pointer to initialized message structure otherwise.

Name

init_message_ex — initialize message

Synopsis

#include <cds/msg_queue.h>

`void init_message_ex(`	`m`,
	`data`,
	`data_len`,
	`func)`;

mq_message_t *m;
void *data;
int data_len;
destroy_function_f func;

Description

Initializes message structure with given data and given data length like create_message but without its allocation.

Parameter func specifies function called on data pointer before freeing the message in free_message. It can be NULL. This function may be used for example for memory deallocation (for example may have value of cds_free_ptr) or some more complicated function for freeing complex data structure with pointers inside or so.

Name

set_data_destroy_function — set function used to deallocate message data

Synopsis

#include <cds/msg_queue.h> 

typedef void (*destroy_function_f)(void *);

`void set_data_destroy_function(`	`msg`,
	`func)`;

mq_message_t *msg;
destroy_function_f func;

Description

Set destroy function for message data. This function is called from free_message and is primarily used for deallocation of complex data structures or their content. It can be used on all types of messages (allocated using create_message or create_message_ex or initialized using init_message_ex).

Example 1. Usage with create_message_ex

str_t *s;
mq_message_t *msg = create_message_ex(sizeof(str_t));
set_data_destroy_function((destroy_function_f)str_free_content);
s = (str_t*)get_message_data(msg);
str_dup_zt(s, "something happened");

Example 2. Usage with create_message

str_t *s = cds_malloc(sizeof(str_t));
mq_message_t *msg = create_message(s, sizeof(str_t));
set_data_destroy_function((destroy_function_f)str_free);
str_dup_zt(s, "something happened");

Name

free_message — free message

Synopsis

#include <cds/msg_queue.h>

void free_message( msg);

mq_message_t *msg;

Description

Frees message. If data is allocated explicitly it frees it using cds_free, if they are allocated implicitly, it is freed together with message. Thus simple data strutures are deallocated automaticaly in both cases. There might be a problem with more complicated structures with internal pointers to other structures - for these you can set destroy function using set_data_destroy_function.

XCAP operations (libxcap)

Václav Kubart

Abstract

Description of helper XCAP library.

Table of Contents

Preface

1. Dependencies

Preface

Table of Contents

1. Dependencies

This library contains functions for manipulating data using XCAP protocol.

1. Dependencies

libcds (distributed with SER)
libxml2 (external library for parsing XML documents)
libcurl3 (external library for HTTP operations, used only in nonSER version!)

Presence utilities and data types (libpresence)

Václav Kubart

Abstract

Description of helper Presence library.

Table of Contents

Preface

1. Dependencies

Preface

Table of Contents

1. Dependencies

This library contains data structures for presence documents representation and helper functions.

1. Dependencies

libcds (distributed with SER)

Common libraries for SIP Express Router

Václav Kubart

Usage of common libraries

Václav Kubart

Chapter 1. Introduction

1. About

2. Dependencies

2.1. libcds dependencies

2.2. libxcap dependencies

2.3. libpresence dependencies

Chapter 2. Installation and usage

1. Usage with SIP Express Router

1.1. Installation steps

1.2. Running SER

Common Data Structures (libcds)

Václav Kubart

Preface

1. Conventions

2. Dependencies

Part I. Reference

Memory operations

Name

Synopsis

Description

Return value

See Also

Name

Synopsis

Description

Return value

See Also

Name

Synopsis

Description

See Also

Name

Synopsis

Description

See Also

String

Name

Synopsis

Description

See Also

Name

Synopsis

Description

Return value

Name

Synopsis

Description

See Also

Name

Synopsis

Description

See Also

Name

Synopsis

Description

See Also

Name

Synopsis

Description

See Also

Dynamic string

Name

Synopsis

Description

Members

Example

Todo

See Also

Name

Synopsis

Description

Return value

Name

Synopsis

Description

Return value