Kamailio SIP Server v3.2.0 Development Guide

In June 2005, Kamailio was born as a split from SIP Express Router (aka SER) project of FhG FOKUS Institute, Berlin, Germany. The newly created project was aiming to create an open development environment to build robust and scalable open source SIP server. Initial name was OpenSER, but due to trademark infringements claims, the project name changed from OpenSER to Kamailio on July 28, 2008.

The website of the project is http://www.kamailio.org. The source code up to version 1.5.x was hosted on sourceforge.net SVN repository. Starting with version 3.0.0, the source code is hosted on sip-router.org GIT repository.

In November 2008, the development teams of Kamailio and SIP Express Router (SER) joined again their efforts and started to work together to integrate the two SIP server applications. The integration concluded with release of v3.0.0, which represents a single source code tree for both applications. In other words, Kamailio and SER are the same application from source code point of view, the difference is done by the name chosen to build the application and the modules loaded in the default configuration file.

The evolution in time of Kamailio is presented in next figure.

Figure 1.1. Kamailio History

Today Kamailio SIP Server is a reference implementation, featuring hundreds of VoIP services world wide, being developed by people around the world. It is included in official distributions of several Linux and BSD flavors.

The number of registered developers and packagers exceeded 90 since the start of the project in 2001. During the last year, over 30 registered developers contributed code to project. The level of contributions and the amount of contributors has an important impact on the evolution of the project. The book tries to ease the understanding of Kamailio from a developer point of view, giving the kick start knowledge, it does not intend to be a cookbook. Efforts to improve the documentation in the sources is undertaken and make it doxygen compliant, making a good developer documentation out of there.

Daniel-Constantin Mierla is one of the co-founders of Kamailio SIP Server project. He is involved in VoIP and SIP since beginning of 2002, at FhG FOKUS Institute, Berlin, Germany, being core developer in the SIP Express Router project. Currently he is employed by ASIPTO, a Kamailio-focused company. Daniel is an active Kamailio developer, member of management board, leading the project.

Elena-Ramona Modroiu is one of the co-founders of Kamailio SIP Server project. She got involved in VoIP and SIP while working at her graduation thesis within SIP Express Router (SER) project at FhG FOKUS Institute. She completed studies at Polytechnic University of Valencia and Siemens Germany, working now at ASIPTO, being an active developer and member of management board of Kamailio.

The two authored many online tutorials about Kamailio, among them: Kamailio Core Cookbook, Kamailio Transformations Cookbook, Kamailio Pseudo-Variables Cookbook, Kamailio and Asterisk Integration, Kamailio and FreeSWITCH Integration, SIP Routing in Lua with Kamailio, Secure VoIP with Kamailio, IPv4 - IPv6 VoIP bridging with Kamailio, Kamailio and FreeRADIUS.

This document is focusing only to Kamailio specific API, has no intention to teach C programing for Linux and Networking. You, as a reader, should have already the basic knowledge of C programming.

Do not contact the authors to ask about standard C functions or variables.

There are many references to parts of code in the source tree. You must be familiar with the directory structure of Kamailio. It is not our intention to explain how something was implemented, but how to use existing code to extend Kamailio easily.

The source code remains the best reference for developers. In the last time, the comments around the important functions in Kamailio have been improved and converted to doxygen format. You should double-check the source code if the prototype of the functions presented in this document are still valid.

Daily updated doxygen documentation is available at http://devel.kamailio.org/doxygen/.

The core includes:

The internal libraries include:

There are over 150 modules in the repository at this moment. By loading modules, you can get functionalities such as:

The execution of Kamailio configuration file is triggered when receiving a SIP message from the network. The processing flow is different for a SIP request or a SIP reply.

Figure 2.3. SIP Request Processing

Figure 2.4. SIP Reply Processing

The document contains a chapter dedicated to Configuration File that explains its structure and the types of routing blocks.

Basically, to create a lock, you have to define a variable of type gen_lock_t, allocate it in shared memory and initialize it. Then you can perform set/unset operations, destroying the variable when you finish using it.

To use the locking system in your C code you have to include the headers file: locking.h.

Data types and available functions to do operations with locks are described in the next sections.

...
#include "locking.h"

gen_lock_t lock;
...
				

...
gen_lock_t* lock_alloc();
...
				

...
#include "locking.h"
...
gen_lock_t *lock;
lock = lock_alloc();
if(lock==NULL)
{
	LM_ERR("cannot allocate the lock\n");
	exit;
}
...
				

...
struct s {
    int a;
    gen_lock_t lock;
} *x;

x = shm_malloc(sizeof struct s); /* we allocate it in the shared memory */
if (lock_init(&x->lock)==0){
    /* error initializing the lock */
    ...
}
...
				

...
void lock_dealloc(gen_lock_t* lock);
...
				

...
#include "locking.h"
...
gen_lock_t *lock;
lock = lock_alloc();
if(lock==NULL)
{
	LM_ERR("cannot allocate the lock\n");
	exit;
}
/* make use of lock */
...
lock_dealloc(lock);
...
				

...
gen_lock_t* lock_init(gen_lock_t* lock);
...
				

...
#include "locking.h"
...
gen_lock_t *lock;
lock = lock_alloc();
if(lock==NULL)
{
	LM_ERR("cannot allocate the lock\n");
	exit;
}
if(lock_init(lock)==NULL)
{
	LM_ERR("cannot init the lock\n");
	lock_dealloc(lock);
	exit;
}
/* make use of lock */
...
lock_dealloc(lock);
...
				

...
void lock_destroy(gen_lock_t* lock);
...
				

...
#include "locking.h"
...
gen_lock_t *lock;
lock = lock_alloc();
if(lock==NULL)
{
	LM_ERR("cannot allocate the lock\n");
	exit;
}
if(lock_init(lock)==NULL)
{
	LM_ERR("cannot init the lock\n");
	lock_dealloc(lock);
	exit;
}
/* make use of lock */
...
lock_destroy(lock);
lock_dealloc(lock);
...
				

...
void lock_get(gen_lock_t* lock);
...
				

...
#include "locking.h"
...
gen_lock_t *lock;
lock = lock_alloc();
if(lock==NULL)
{
	LM_ERR("cannot allocate the lock\n");
	exit;
}
if(lock_init(lock)==NULL)
{
	LM_ERR("cannot init the lock\n");
	lock_dealloc(lock);
	exit;
}
/* make use of lock */
lock_get(lock);
/* under lock protection */
...
lock_destroy(lock);
lock_dealloc(lock);
...
				

...
int lock_try(gen_lock_t* lock);
...
				

...
#include "locking.h"
...
gen_lock_t *lock;
lock = lock_alloc();
if(lock==NULL)
{
	LM_ERR("cannot allocate the lock\n");
	exit;
}
if(lock_init(lock)==NULL)
{
	LM_ERR("cannot init the lock\n");
	lock_dealloc(lock);
	exit;
}
/* make use of lock */
if(lock_try(lock)==0) {
   /* under lock protection */
   ...
} else {
   /* NO lock protection */
   ...
}
...
lock_destroy(lock);
lock_dealloc(lock);
...
				

...
void lock_release(gen_lock_t* lock);
...
				

...
#include "locking.h"
...
gen_lock_t *lock;
lock = lock_alloc();
if(lock==NULL)
{
	LM_ERR("cannot allocate the lock\n");
	exit;
}
if(lock_init(lock)==NULL)
{
	LM_ERR("cannot init the lock\n");
	lock_dealloc(lock);
	exit;
}
/* make use of lock */
lock_get(lock);
/* under lock protection */
...
lock_release(lock);
...
lock_destroy(lock);
lock_dealloc(lock);
...
				

The lock set is an array of gen_lock_t. To create a lock set, you have to define a variable of type gen_lock_set_t, allocate it in shared memory specifying the number of locks in the set, then initialize it. You can perform set/unset operations, providing the lock set variable and destroying the variable when you finish using it.

To use the lock sets in your C code you have to include the headers file: locking.h.

Data types and available functions to do operations with lock sets are described in the next sections.

...
#include "locking.h"

gen_lock_set_t lock_set;
...
				

...
gen_lock_set_t* lock_set_alloc(int n);
...
				

...
#include "locking.h"
...
gen_lock_set_t *set;
set = lock_set_alloc(16);
if(set==NULL)
{
	LM_ERR("cannot allocate the lock set\n");
	exit;
}
...
				

...
void lock_set_dealloc(gen_lock_set_t* set);
...
				

...
#include "locking.h"
...
gen_lock_set_t *set;
set = lock_set_alloc(16);
if(set==NULL)
{
	LM_ERR("cannot allocate the lock set\n");
	exit;
}
...
lock_set_dealloc(set);
...
				

...
gen_lock_set_t* lock_set_init(gen_lock_set_t* set);
...
				

...
#include "locking.h"
...
gen_lock_set_t *set;
set = lock_set_alloc(16);
if(set==NULL)
{
	LM_ERR("cannot allocate the lock set\n");
	exit;
}
if(lock_set_init(set)==NULL)
{
	LM_ERR("cannot initialize the lock set'n");
	lock_set_dealloc(set);
	exit;
}
/* make usage of lock set */
...
lock_set_dealloc(set);

...
				

...
void lock_set_destroy(gen_lock_set_t* set);
...
				

...
#include "locking.h"
...
gen_lock_set_t *set;
set = lock_set_alloc(16);
if(set==NULL)
{
	LM_ERR("cannot allocate the lock set\n");
	exit;
}
if(lock_set_init(set)==NULL)
{
	LM_ERR("cannot initialize the lock set'n");
	lock_set_dealloc(set);
	exit;
}
/* make usage of lock set */
...
lock_set_destroy(set);
lock_set_dealloc(set);
...
				

...
void lock_set_get(gen_lock_set_t* set, int i);
...
				

...
#include "locking.h"
...
gen_lock_set_t *set;
set = lock_set_alloc(16);
if(set==NULL)
{
	LM_ERR("cannot allocate the lock set\n");
	exit;
}
if(lock_set_init(set)==NULL)
{
	LM_ERR("cannot initialize the lock set'n");
	lock_set_dealloc(set);
	exit;
}
/* make usage of lock set */
lock_set_get(set, 8);
/* under lock protection */
...
lock_set_destroy(set);
lock_set_dealloc(set);
...
				

...
int lock_set_try(gen_lock_set_t* set, int i);
...
				

...
#include "locking.h"
...
gen_lock_set_t *set;
set = lock_set_alloc(16);
if(set==NULL)
{
	LM_ERR("cannot allocate the lock set\n");
	exit;
}
if(lock_set_init(set)==NULL)
{
	LM_ERR("cannot initialize the lock set'n");
	lock_set_dealloc(set);
	exit;
}
/* make usage of lock set */
if(lock_set_try(set, 8)==0) {
    /* under lock protection */
    ...
} else {
    /* NO lock protection */
    ...
}
...
lock_set_destroy(set);
lock_set_dealloc(set);
...
				

...
void lock_set_release(gen_lock_set_t* set, int i);
...
				

...
#include "locking.h"
...
gen_lock_set_t *set;
set = lock_set_alloc(16);
if(set==NULL)
{
	LM_ERR("cannot allocate the lock set\n");
	exit;
}
if(lock_set_init(set)==NULL)
{
	LM_ERR("cannot initialize the lock set'n");
	lock_set_dealloc(set);
	exit;
}
/* make usage of lock set */
lock_set_get(set, 8);
/* under lock protection */
...
lock_set_release(set, 8);
...
lock_set_destroy(set);
lock_set_dealloc(set);
...
				

A clear sign of issues with the locking is that one or more Kamailio processes eat lot of CPU. If the traffic load does not justify such behavior and no more SIP messages are processed, the only solution is to troubleshoot and fix the locking error. The problem is that a lock is set but never unset. A typical case is when returning due to an error and forgetting to release a previously lock set.

To troubleshoot a solution is to use gdb, attach to the process that eats lot of CPU and get the backtrace. You need to get the PID of that Kamailio process - top or ps tools can be used.

...
# gdb /path/to/kamailio PID
# gdb> bt
...
		

From the backtrace you should get to the lock that is set and not released. From there you should start the investigation - what are the cases to set that lock and in which circumstances it does not get released.

This type of memory is specific per process, no synchronization is needed to access structures allocated in it. It should be used for variables that do not need to be visible in other Kamailio processes or for temporary operations.

To store static values in private memory and have it in all processes without the need to synchronize for accessing it, you must create it before Kamailio forks.

To use the private memory manager you have to include the file: mem/mem.h.

...
void* pkg_malloc(unsigned int size);
...
				

...
#include "mem/mem.h"
...
char *p;
p = (char*)pkg_malloc(8*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot allocate pkg memory\n");
	exit;
}
...
				

...
void *pkg_free(void *p);
...
				

...
#include "mem/mem.h"
...
char *p;
p = (char*)pkg_malloc(8*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot allocate pkg memory\n");
	exit;
}
strcpy(p, "kamailio");
LM_DBG("string value at %p is [%s]\n", p, p);
pkg_free(p);
...
				

...
void *pkg_realloc(void *p, unsigned int size);
...
				

...
#include "mem/mem.h"
...
char *p;
p = (char*)pkg_malloc(8*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot allocate pkg memory\n");
	exit;
}
strcpy(p, "kamailio");
LM_DBG("string value at %p is [%s]\n", p, p);
p = (char*)pkg_realloc(p, 16*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot re-allocate pkg memory\n");
	exit;
}
strcat(p, " server");
LM_DBG("string value at %p is [%s]\n", p, p);

pkg_free(p);
...
				

The data stored in shared memory is visible in all Kamailio modules. It is the space where user location records are stored, the TM structures for stateful processing, routing rules for the dispatcher or the lcr module, and many more.

The shared memory is initialized after the config file is parsed, because it need to know the user and group Kamailio is running under, for the case when the memory manger uses SysV operations.

To use shared memory functions in your C code you need to include the file: mem/shm_mem.h. When accessing shared memory data, you need to make sure that you don't have a race between different Kamailio processes, for example protect the access via a lock.

...
void *shm_malloc(unsigned int size);
...
				

...
#include "mem/shm_mem.h"
...
char *p;
p = (char*)shm_malloc(8*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot allocate shm memory\n");
	exit;
}
...
				

...
void shm_free(void *p);
...
				

...
#include "mem/shm_mem.h"
...
char *p;
p = (char*)shm_malloc(8*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot allocate shm memory\n");
	exit;
}
strcpy(p, "kamailio");
LM_DBG("string value at %p is [%s]\n", p, p);
shm_free(p);
...
				

...
void *shm_realloc(void *p, unsigned int size);
...
				

...
#include "mem/shm_mem.h"
...
char *p;
p = (char*)shm_malloc(8*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot allocate shm memory\n");
	exit;
}
strcpy(p, "kamailio");
LM_DBG("string value at %p is [%s]\n", p, p);
p = (char*)shm_realloc(p, 16*sizeof(char));
if(p==NULL)
{
	LM_ERR("cannot re-allocate shm memory\n");
	exit;
}
strcat(p, " server");
LM_DBG("string value at %p is [%s]\n", p, p);

shm_free(p);
...
				

There are two cases of memory problems:

Kamailio has an internal debugger for memory - it is able to show the chunks allocated in private or shared memory and the file and line from where it was allocated. In debugging mode it prints all calls for allocations and freeing memory.

To enable the memory debugger you have to recompile Kamailio with MEMDBG=1 option to make tool.

...
make cfg FLAVOUR=kamailio MEMDBG=1 ...
make all
...
				

Once compiled and installed with memory debugging you have to set memlog parameter to a value lower than debug in configuration file. You can start Kamailio and try to reproduce the errors again. Once memory leak errors are printed you can either send a RPC command to the process that printed the messages or stop Kamailio. You get in the syslog file the status of the memory. If you see memory allocation done from the same place in the sources, many times, at runtime, it is a memory leak. If not, increase the memory size to fit your load needs and run again -- if you don't get the memory leak errors it was the case of insufficient memory allocated for Kamailio.

For sending the RPC command, you have to load ctl and cfg_rpc modules, then use sercmd tool:

...
sercmd cfg.set_now_int core mem_dump_pkg [pid]
...
sercmd cfg.set_now_int core mem_dump_shm [pid]
...
				

Monitoring used memory can be done also via RPC commands:

...
sercmd> core.shmmem
{
	total: 33554432
	free: 30817888
	used: 2512248
	real_used: 2736544
	max_used: 2736544
	fragments: 1
}
...
sercmd> pkg.stats
{
	entry: 0
	pid: 60090
	rank: 0
	used: 217280
	free: 3674296
	real_used: 520008
}
{
	entry: 1
	pid: 60091
	rank: 1
	used: 225160
	free: 3666320
	real_used: 527984
}
...
				

It is possible to walk through the list of PKG fragments with gdb. For example, printing used fragment in the range 2000 to 10000:

...
set $i=0
set $a = mem_block->first_frag
while($i<10000)
  if($i>2000)
    if($a->u.is_free==0)
      p *$a
    end
  end
  set $a = ((struct qm_frag*)((char*)($a)+sizeof(struct qm_frag)+((struct qm_frag*)$a)->size+sizeof(struct qm_frag_end)))
  set $i = $i + 1
end
...
		

For memory overwriting a core should be generated. If yes, you can investigate it with gdb.

...
# gdb /path/to/kamailio corefile
...
		

From the backtrace you should get the file and line where the overwriting happened. In case a core is not generated, check the messages in the syslog. Look for BUG and error, for head or tail of a memory chunk being overwriting.

SIP is a text-based protocol, therefore lot of operations resume to text manipulation. Kamailio uses references in the SIP message body most of the time, doing it via an anchor pointer and the length. For that it uses the str structure.

The str structure is defined in file str.h.

...
struct _str{
	char* s; /* pointer to the beginning of string (char array) */
	int len; /* string length */
};

typedef struct _str str;
...
			

...
#include "str.h"
...
str s;
s.s = "kamailio";
s.len = strlen(s.s);
LM_DBG("the string is [%.*s]\n", s.len, s.s);
...
			

This is the structure holding a parsed SIP URI. You can fill it by calling parse_uri(...) function.

The structure is defined in file parser/msg_parser.h.

...	
struct sip_uri {
	str user;     /* Username */
	str passwd;   /* Password */
	str host;     /* Host name */
	str port;     /* Port number */
	str params;   /* URI Parameters */
	str headers;  /* URI Headers */
	unsigned short port_no; /* Port number r*/
	unsigned short proto; /* Transport protocol */
	uri_type type; /* URI scheme */
	/* parameters */
	str transport;   /* transport parameter */
	str ttl;         /* ttl parameter */
	str user_param;  /* user parameter */
	str maddr;       /* maddr parameter */
	str method;      /* method parameter */
	str lr;          /* lr parameter */
	str r2;          /* specific rr parameter */
	/* values */
	str transport_val;  /* value of transport parameter */
	str ttl_val;        /* value of ttl parameter */
	str user_param_val; /* value of user parameter */
	str maddr_val;      /* value of maddr parameter */
	str method_val;     /* value of method parameter */
	str lr_val;         /* value of lr parameter */
	str r2_val;         /* value of r2 parameter */
};
...
			

Members of the structure corresponds to a part of a SIP URI. To get details about the format of SIP URI read RFC3261. Example of SIP URI:

sip:alice@sipserver.org:5060;transport=tcp

This is the main structure related to a SIP message. When a SIP message is received from the network, it is parsed in such structure. The pointer to this structure is given as parameter to all functions exported by modules to be used in the configuration file.

The structure is defined in file parser/msg_parser.h.

...
struct sip_msg {
	unsigned int id;               /* message id, unique/process*/
	struct msg_start first_line;   /* Message first line */
	struct via_body* via1;         /* The first via */
	struct via_body* via2;         /* The second via */
	struct hdr_field* headers;     /* All the parsed headers*/
	struct hdr_field* last_header; /* Pointer to the last parsed header*/
	hdr_flags_t parsed_flag;       /* Already parsed header field types */

	/* Via, To, CSeq, Call-Id, From, end of header*/
	/* pointers to the first occurrences of these headers;
	 * everything is also saved in 'headers' (see above)
	 */

	/* shorcuts to known headers */
	struct hdr_field* h_via1;
	struct hdr_field* h_via2;
	struct hdr_field* callid;
	struct hdr_field* to;
	struct hdr_field* cseq;
	struct hdr_field* from;
	struct hdr_field* contact;
	struct hdr_field* maxforwards;
	struct hdr_field* route;
	struct hdr_field* record_route;
	struct hdr_field* path;
	struct hdr_field* content_type;
	struct hdr_field* content_length;
	struct hdr_field* authorization;
	struct hdr_field* expires;
	struct hdr_field* proxy_auth;
	struct hdr_field* supported;
	struct hdr_field* proxy_require;
	struct hdr_field* unsupported;
	struct hdr_field* allow;
	struct hdr_field* event;
	struct hdr_field* accept;
	struct hdr_field* accept_language;
	struct hdr_field* organization;
	struct hdr_field* priority;
	struct hdr_field* subject;
	struct hdr_field* user_agent;
	struct hdr_field* content_disposition;
	struct hdr_field* accept_disposition;
	struct hdr_field* diversion;
	struct hdr_field* rpid;
	struct hdr_field* refer_to;
	struct hdr_field* session_expires;
	struct hdr_field* min_se;
	struct hdr_field* ppi;
	struct hdr_field* pai;
	struct hdr_field* privacy;

	struct sdp_info* sdp; /* parsed SDP body */

	char* eoh;        /* pointer to the end of header (if found) or null */
	char* unparsed;   /* here we stopped parsing*/
	
	struct receive_info rcv; /* source and dest ip, ports, proto a.s.o*/

	char* buf;        /* scratch pad, holds a unmodified message,
                           *  via, etc. point into it */
	unsigned int len; /* message len (orig) */

	/* modifications */

	str new_uri; /* changed first line uri, when you change this
                  * don't forget to set parsed_uri_ok to 0 */

	str dst_uri; /* Destination URI, must be forwarded to this URI if len!=0 */
	
	/* current uri */
	int parsed_uri_ok; /* 1 if parsed_uri is valid, 0 if not, set it to 0
	                      if you modify the uri (e.g change new_uri)*/
	struct sip_uri parsed_uri; /* speed-up > keep here the parsed uri*/

	/* the same for original uri */
	int parsed_orig_ruri_ok;
	struct sip_uri parsed_orig_ruri;

	struct lump* add_rm;       /* used for all the forwarded requests/replies */
	struct lump* body_lumps;     /* Lumps that update Content-Length */
	struct lump_rpl *reply_lump; /* only for localy generated replies !!!*/

	/* whatever whoever want to append to branch comes here */
	char add_to_branch_s[MAX_BRANCH_PARAM_LEN];
	int add_to_branch_len;
	
	/* index to TM hash table; stored in core to avoid 
	 * unnecessary calculations */
	unsigned int  hash_index;

	/* flags used from script */
	flag_t flags;

	/* flags used by core - allows to set various flags on the message; may 
	 * be used for simple inter-module communication or remembering 
	 * processing state reached */
	unsigned int msg_flags;

	str set_global_address;
	str set_global_port;

	/* force sending on this socket */
	struct socket_info* force_send_socket;

	/* create a route HF out of this path vector */
	str path_vec;
};
...
			

To fill such structure you can use function parse_msg(...) giving a buffer containing raw text of a SIP message. Most of the attributes in this structure point directly inside the SIP message buffer.

Example of a SIP message:

...
REGISTER sip:sip.test.com SIP/2.0
Via: SIP/2.0/UDP 192.168.1.3:5061;branch=z9hG4bK-d663b80b
Max-Forwards: 70
From: user <sip:u123@sip.test.com>;tag=ea8cef4b108a99bco1
To: user <sip:u123@sip.test.com>
Call-ID: b96fead3-f03493d4@xyz
CSeq: 3720 REGISTER
Contact: user <sip:u123@192.168.1.3:5061>;expires=3600
User-Agent: Linksys/RT31P2-2.0.10(LIc)
Content-Length: 0
Allow: ACK, BYE, CANCEL, INFO, INVITE, NOTIFY, OPTIONS, REFER
Supported: x-sipura
...
		

The structure corresponds to a parsed representation of the first line in a SIP message. It is defined in file parser/parse_fline.h.

...
struct msg_start {
	int type;                 /* Type of the Message - Request or Response (Reply) */
	int len;                  /* length including delimiter */
	union {
		struct {
			str method;       /* Method string */
			str uri;          /* Request URI as raw string */
			str version;      /* SIP version */
			int method_value; /* Internal integer representation of SIP method */
		} request;
		struct {
			str version;      /* SIP version */
			str status;       /* Reply status */
			str reason;       /* Reply reason phrase */
			unsigned int statuscode; /* Integer representation of reply status */
		} reply;
	}u;
};
...
			

To parse a buffer containing the first line of a SIP message you have to use the function parse_fline(...).

The structure holding a parsed SIP header. It is defined in file parser/hf.h.

...
struct hdr_field {
	hdr_types_t type;          /* Header field type */
	str name;                  /* Header field name */
	str body;                  /* Header field body (may not include CRLF) */
	int len;                   /* length from hdr start until EoHF (incl.CRLF) */
	void* parsed;              /* Parsed data structures */
	struct hdr_field* next;    /* Next header field in the list */
	struct hdr_field* sibling; /* Next header of same type */
};
...
			

To parse specific headers in a SIP message you have to use the function parse_headers(...). The function takes as parameter a bitmask flag that can specify what headers you need to be parsed. For example, to parse the From and To headers:

parse_headers(msg, HDR_FROM_F|HDR_TO_F, 0);

To optimize the operations with headers, an integer value is assigned to most used headers. This value is stored in attribute type. Here is the list with the values for header type:

...
enum _hdr_types_t {
	HDR_ERROR_T        = -1   /* Error while parsing */,
	HDR_OTHER_T        =  0   /* Some other header field */,
	HDR_VIA_T          =  1   /* Via header field */,
	HDR_VIA1_T         =  1   /* First Via header field */,
	HDR_VIA2_T         =  2   /* only used as flag */,
	HDR_TO_T                  /* To header field */,
	HDR_FROM_T                /* From header field */,
	HDR_CSEQ_T                /* CSeq header field */,
	HDR_CALLID_T              /* Call-Id header field */,
	HDR_CONTACT_T             /* Contact header field */,
	HDR_MAXFORWARDS_T         /* MaxForwards header field */,
	HDR_ROUTE_T               /* Route header field */,
	HDR_RECORDROUTE_T         /* Record-Route header field */,
	HDR_PATH_T                /* Path header fiels */,
	HDR_CONTENTTYPE_T         /* Content-Type header field */,
	HDR_CONTENTLENGTH_T       /* Content-Length header field */,
	HDR_AUTHORIZATION_T       /* Authorization header field */,
	HDR_EXPIRES_T             /* Expires header field */,
	HDR_PROXYAUTH_T           /* Proxy-Authorization hdr field */,
	HDR_SUPPORTED_T           /* Supported  header field */,
	HDR_PROXYREQUIRE_T        /* Proxy-Require header field */,
	HDR_UNSUPPORTED_T         /* Unsupported header field */,
	HDR_ALLOW_T               /* Allow header field */,
	HDR_EVENT_T               /* Event header field */,
	HDR_ACCEPT_T              /* Accept header field */,
	HDR_ACCEPTLANGUAGE_T      /* Accept-Language header field */,
	HDR_ORGANIZATION_T        /* Organization header field */,
	HDR_PRIORITY_T            /* Priority header field */,
	HDR_SUBJECT_T             /* Subject header field */,
	HDR_USERAGENT_T           /* User-Agent header field */,
	HDR_ACCEPTDISPOSITION_T   /* Accept-Disposition hdr field */,
	HDR_CONTENTDISPOSITION_T  /* Content-Disposition hdr field */,
	HDR_DIVERSION_T           /* Diversion header field */,
	HDR_RPID_T                /* Remote-Party-ID header field */,
	HDR_REFER_TO_T            /* Refer-To header fiels */,
	HDR_SESSION_EXPIRES_T     /* Session-Expires header field */,
	HDR_MIN_SE_T              /* Min-SE header field */,
	HDR_PPI_T                 /* P-Preferred-Identity header field */,
	HDR_PAI_T                 /* P-Asserted-Identity header field */,
	HDR_PRIVACY_T             /* Privacy header field */,
	HDR_RETRY_AFTER_T         /* Retry-After header field */,
	HDR_EOH_T                 /* Some other header field */
};
...
		

If the type of hdr_field structure is HDR_TO_T it is the parsed To header.

The attribute parsed may hold the parsed representation of the header body. For example, for Content-Lenght header it contains the content length value as integer.

The structure holds a parsed To header. Same structure is used for From header and the other headers that have same structure conform to IETF RFCs. The structure is defined in file parser/parse_to.h.

...
struct to_body{
	int error;                    /* Error code */
	str body;                     /* The whole header field body */
	str uri;                      /* URI withing the body of the header */
	str display;                  /* Display Name */
	str tag_value;                /* Value of tag parameter*/
	struct sip_uri parsed_uri;    /* Parsed URI */
	struct to_param *param_lst;   /* Linked list of parameters */
	struct to_param *last_param;  /* Last parameter in the list */
};
...
			

To parse a To header you have to use function parse_to(...).

The structure holds a parsed Via header. It is defined in file parse_via.h.

...
struct via_body { 
	int error;          /* set if an error occurred during parsing */
	str hdr;        /* header name "Via" or "v" */
	str name;       /* protocol name */
	str version;    /* protocol version */
	str transport;  /* transport protocol */
	str host;       /* host part of Via header */
	unsigned short proto; /* transport protocol as integer*/
	unsigned short port;  /* port number as integer */
	str port_str;         /* port number as string*/
	str params;           /* parameters */
	str comment;          /* comment */
	unsigned int bsize;           /* body size, not including hdr */
	struct via_param* param_lst;  /* list of parameters*/
	struct via_param* last_param; /*last via parameter, internal use*/

	/* shortcuts to "important" params*/
	struct via_param* branch;     /* branch parameter */
	str tid;                      /* transaction id, part of branch */
	struct via_param* received;   /* received parameter */
	struct via_param* rport;      /* rport parameter */
	struct via_param* i;          /* i parameter */
	struct via_param* alias;      /* alias see draft-ietf-sip-connect-reuse-00 */
	struct via_param* maddr;      /* maddr parameter */
	struct via_body* next;        /* pointer to next via body string if compact Via or null */
};
...
			

The str attributes in the structure are referenced to SIP message buffer. To parse a Via header you have to use the function parse_via(...).

A developer does not interfere too much with this function as it is called automatically by Kamailio when a SIP message is received from the network.

You can use it if you load the content of SIP message from a file or database, or you received on different channels, up to your extension implementation. You should be aware that it is not enough to call this function and then run the actions from the configuration file. There are some attributes in the structure sip_msg that are specific to the environment: received socket, source IP and port, ...

...
int parse_msg(char* buf, unsigned int len, struct sip_msg* msg);
...
			

Return 0 if parsing was OK, >0 if error occurred.

...
str msg_buf;
struct sip_msg msg;
...
msg_buf.s = "INVITE sip:user@sipserver.com SIP/2.0\r\nVia: ...";
msg_buf.len = strlen(msg_buf.s);

if (parse_msg(buf,len, &msg)!=0) {
	LM_ERR("parse_msg failed\n");
	return -1;
}

if(msg.first_line.type==SIP_REQUEST)
	LM_DBG("SIP method is [%.*s]\n", msg.first_line.u.request.method.len,
		msg.first_line.u.request.method.s);
...
			

Parse the SIP message until the headers specified by parameter flags flags are found. The parameter next can be used when a header can occur many times in a SIP message, to continue parsing until a new header of that type is found.

The values that can be used for flags are defined in parser/hf.h.

When searching to get a specific header, all the headers encountered during parsing are hooked in the structure sip_msg.

...
int parse_headers(struct sip_msg* msg, hdr_flags_t flags, int next);
...
			

Return 0 if parsing was sucessful, >0 in case of error.

...
if(parse_headers(msg, HDR_CALLID_F, 0)!=0)
{
	LM_ERR("error parsing CallID header\n");
	return -1;
}
...
			

Parse a buffer that contains the body of a To header. The function is defined in parser/parse_to.h.

...
char* parse_to(char* buffer, char *end, struct to_body *to_b);
...
			

Return 0 in case of success, >0 in case of error.

The next example shows the parse_from(...) function that makes use of parse_to(...) to parse the body of header From. The function is located in file parser/parse_from.c.

The structure filled at parsing is hooked in the structure sip_msg, inside the attribute from, which is the shortcut to the header From.

...

int parse_from_header( struct sip_msg *msg)
{
	struct to_body* from_b;

	if ( !msg->from && ( parse_headers(msg,HDR_FROM_F,0)==-1 || !msg->from)) {
		LM_ERR("bad msg or missing FROM header\n");
		goto error;
	}

	/* maybe the header is already parsed! */
	if (msg->from->parsed)
		return 0;

	/* first, get some memory */
	from_b = pkg_malloc(sizeof(struct to_body));
	if (from_b == 0) {
		LM_ERR("out of pkg_memory\n");
		goto error;
	}

	/* now parse it!! */
	memset(from_b, 0, sizeof(struct to_body));
	parse_to(msg->from->body.s,msg->from->body.s+msg->from->body.len+1,from_b);
	if (from_b->error == PARSE_ERROR) {
		LM_ERR("bad from header\n");
		pkg_free(from_b);
		set_err_info(OSER_EC_PARSER, OSER_EL_MEDIUM, "error parsing From");
		set_err_reply(400, "bad From header");
		goto error;
	}
	msg->from->parsed = from_b;

	return 0;
error:
	return -1;
}

...
			

Next example shows how to get the content of SIP message body in a 'str' variable.

...
int get_msg_body(struct sip_msg *msg, str *body)
{
	/* 'msg' is a pointer to a valid struct sip_msg */

	/* get message body
	- after that whole SIP MESSAGE is parsed
	- calls internally parse_headers(msg, HDR_EOH_F, 0)
	*/
	body->s = get_body( msg );
	if (body->s==0) 
	{
		LM_ERR("cannot extract body from msg\n");
		return -1;
	}

	body->len = msg->len - (body->s - msg->buf);

	/* content-length (if present) must be already parsed */
	if (!msg->content_length) 
	{
		LM_ERR("no Content-Length header found!\n");
		return -1;
	}
	if(body->len != get_content_length( msg ))
		LM_WARN("Content length header value different than body size\n");
	return 0;
}
...
			

You can see in the next example how to access the body of header Call-ID.

...
void print_callid_header(struct sip_msg *msg)
{
	if(msg==NULL)
		return;
	if(parse_headers(msg, HDR_CALLID_F, 0)!=0)
	{
		LM_ERR("error parsing CallID header\n");
		return;
	}
		
	if(msg->callid==NULL || msg->callid->body.s==NULL)
	{
		LM_ER("NULL call-id header\n");
		return;
	}
	LM_INFO("Call-ID: %.*s\n", msg->callid->body.len, msg->callid->body.s);
}
...
			

The section gives the guidelines to add a new function for parsing a header.

Kamailio follows the requirements specified in RFC3263 for server and service location. That includes support for NAPTR and SRV records as well.

To investigate the implementation related to DNS, start with files resolve.{c,h}.

There is an internal DNS cache which is necessary for doing DNS-based load balancing and failover. It can be disable via core parameters in the configuration file.

Some of the core parameters correspond to global variables in Kamailio sources. Others induce actions to be taken during statup.

Let's follow step by step the definition and usage of the core parameter log_name. It is a string parameter that specifies the value to be printed as application name in syslog messages.

First is the declaration of the variable in the C code. The log_name is defined in main.c and initialized to 0 (when set to o, it is printed the Kamailio name (including path) in the syslog).

...
char *log_name = 0;
...
		

Next is to define the token in the flex file: cfg.lex.

...
LOGNAME		log_name
...
		

The association of a token ID and extending the grammar of the configuration file is done in the bison file: cfg.y.

...
%token LOGNAME
...
assign_stm: ...
		| LOGNAME EQUAL STRING { log_name=$3; }
		| LOGNAME EQUAL error { yyerror("string value expected"); }
...
		

The grammar was extended with a new assign statement, that allows to write in the configuration file an expression like:

...
log_name = "kamailio123"
...
		

When having a line like above one in the configuration file, the variable log_name in C code will be initialized to the string in the right side of the equal operator.

To introduce new functions in Kamailio core that are exported to the configuration file the grammar have to be extended (bison and flex files), the interpreter must be enhanced to be able to run the new actions.

Behind each core function resides an action structure. This data type is defined in route_struct.h:

...
typedef struct {
	action_param_type type;
	union {
		long number;
		char* string;
		struct _str str;
		void* data;
		avp_spec_t* attr;
		select_t* select;
	} u;
} action_u_t;

/* maximum internal array/params
 * for module function calls val[0] and val[1] store a pointer to the
 * function and the number of params, the rest are the function params 
 */
#define MAX_ACTIONS (2+6)

struct action{
	int cline;
	char *cfile;
	enum action_type type;  /* forward, drop, log, send ...*/
	int count;
	struct action* next;
	action_u_t val[MAX_ACTIONS];
};
...
		

Each action is identified by a type. The types of actions are defined in same header file. For example, the strip(...) function has the type STRIP_T, the functions exported by modules have the type MODULE_T.

To each action may be given a set of parameters, so called action elements. In case of functions exported by modules, the first element is the pointer to the function, next are the parameters given to that function in configuration file.

For debugging and error detection, the action keeps the line number in configuration file where it is used.

Next we discuss how setflag(...) config function was implemented.

...
SETFLAG			"setflag"
...
			

...
%token SETFLAG
...
cmd:	...

	| SETFLAG LPAREN NUMBER RPAREN	{
							if (check_flag($3)==-1)
								yyerror("bad flag value");
							$$=mk_action(SETFLAG_T, 1, NUMBER_ST,
													(void*)$3);
							set_cfg_pos($$);
									}
	| SETFLAG LPAREN flag_name RPAREN	{
							i_tmp=get_flag_no($3, strlen($3));
							if (i_tmp<0) yyerror("flag not declared");
							$$=mk_action(SETFLAG_T, 1, NUMBER_ST,
										(void*)(long)i_tmp);
							set_cfg_pos($$);
									}
	| SETFLAG error			{ $$=0; yyerror("missing '(' or ')'?"); }

...

			

...
		case SETFLAG_T:
			if (a->val[0].type!=NUMBER_ST) {
				LOG(L_CRIT, "BUG: do_action: bad setflag() type %d\n",
					a->val[0].type );
				ret=E_BUG;
				goto error;
			}
			if (!flag_in_range( a->val[0].u.number )) {
				ret=E_CFG;
				goto error;
			}
			setflag( msg, a->val[0].u.number );
			ret=1;
			break;
...

			

...
int setflag( struct sip_msg* msg, flag_t flag ) {
	msg->flags |= 1 << flag;
	return 1;
}
...
			

...
		case SETFLAG_T:
		case RESETFLAG_T:
		case ISFLAGSET_T:
			if (t->elem[0].type!=NUMBER_ST) {
				LM_CRIT("bad xxxflag() type %d\n", t->elem[0].type );
				ret=E_BUG;
				goto error;
			}
			if (!flag_in_range( t->elem[0].u.number )) {
				ret=E_CFG;
				goto error;
			}
			break;
...
			

...
		case SETFLAG_T:
				LM_DBG("setflag(");
				break;
...
			

It is the structure that gets filled when binding to a DB driver module. It links to the interface functions implemented in the module.

...
typedef struct db_func {
	unsigned int      cap;            /* Capability vector of the database transport */
	db_use_table_f    use_table;      /* Specify table name */
	db_init_f         init;           /* Initialize database connection */
	db_close_f        close;          /* Close database connection */
	db_query_f        query;          /* query a table */
	db_fetch_result_f fetch_result;   /* fetch result */
	db_raw_query_f    raw_query;      /* Raw query - SQL */
	db_free_result_f  free_result;    /* Free a query result */
	db_insert_f       insert;         /* Insert into table */
	db_delete_f       delete;         /* Delete from table */ 
	db_update_f       update;         /* Update table */
	db_replace_f      replace;        /* Replace row in a table */
	db_last_inserted_id_f  last_inserted_id;  /* Retrieve the last inserted ID
	                                            in a table */
	db_insert_update_f insert_update; /* Insert into table, update on duplicate key */ 
	db_insert_delayed_f insert_delayed;       /* Insert delayed into table */
	db_affected_rows_f affected_rows; /* Numer of affected rows for last query */
} db_func_t;
...
			

The attribute cap is a bitmask of implemented functions, making easy to detect the capabilities of the DB driver module. A module using the DB API should check at startup that the DB driver configured to be used has the required capabilities. For example, msilo module need select, delete and insert capabilities. The flags for capabilities are enumerated in the next figure (located in lib/srdb1/db_cap.h).

...
typedef enum db_cap {
	DB_CAP_QUERY =     1 << 0,  /* driver can perform queries                                     */
	DB_CAP_RAW_QUERY = 1 << 1,  /* driver can perform raw queries                                 */
	DB_CAP_INSERT =    1 << 2,  /* driver can insert data                                         */
	DB_CAP_DELETE =    1 << 3,  /* driver can delete data                                         */
	DB_CAP_UPDATE =    1 << 4,  /* driver can update data                                         */
	DB_CAP_REPLACE =   1 << 5,  /* driver can replace (also known as INSERT OR UPDATE) data       */
	DB_CAP_FETCH   =   1 << 6,  /* driver supports fetch result queries                           */
	DB_CAP_LAST_INSERTED_ID = 1 << 7,  /* driver can return the ID of the last insert operation   */
	DB_CAP_INSERT_UPDATE = 1 << 8,  /* driver can insert data into database, update on duplicate  */
	DB_CAP_INSERT_DELAYED = 1 << 9, /* driver can do insert delayed                               */
	DB_CAP_AFFECTED_ROWS = 1 << 10  /* driver can return number of rows affected by last query    */
} db_cap_t;
...
		

The DB API offers a set of macros to make easier to access the attributes in various data structures.

Macros for db_res_t:

Macros for db_val_t:

Macros for db_val_t:

A simple example of doing a select. The table is named test and has two columns.

...
create table test (
    a int,
	b varchar(64)
);
...
		

The C code:

...

#include "../../dprint.h"
#include "../../lib/srdb1/db.h"

db_func_t db_funcs;      /* Database API functions */
db1_con_t* db_handle=0;   /* Database connection handle */

int db_example(char *db_url)
{
	str table;
	str col_a;
	str col_b;
	int nr_keys=0;
	db_key_t db_keys[1];
	db_val_t db_vals[1];
	db_key_t db_cols[1];
	db1_res_t* db_res = NULL;

    /* Bind the database module */
	if (db_bind_mod(&db_url, &db_funcs))
	{
		LM_ERR("failed to bind database module\n");
		return -1;
	}
	/* Check for SELECT capability */
	if (!DB_CAPABILITY(db_funcs, DB_CAP_QUERY))
	{
		LM_ERR("Database modules does not "
			"provide all functions needed here\n");
		return -1;
	}
	/* Connect to DB */
	db_handle = db_funcs.init(&db_url);
	if (!db_handle)
	{
		LM_ERR("failed to connect database\n");
		return -1;
	}

	/* Prepare the data for the query */
	table.s = "test";
	table.len = 4;

	col_a.s = "a";
	col_a.len = 1;
	col_b.s = "b";
	col_b.len = 1;

	db_cols[0] = &col_b;
	db_keys[0] = &col_a;
	
	db_vals[nr_keys].type = DB_INT;
	db_vals[nr_keys].nul = 0;
	db_vals[nr_keys].val.int_val = 1;
	nr_keys++;

	/* execute the query */
	/* -- select b from test where a=1 */
	db_funcs.use_table(db_handle, &table);
	if(db_funcs.query(db_handle, db_keys, NULL, db_vals, db_cols,
		nr_keys /*no keys*/, 1 /*no cols*/, NULL, &db_res)!=0)
	{
		LM_ERR("failed to query database\n");
		db_funcs.close(db_handle);
		return -1;
	}

	if (RES_ROW_N(db_res)<=0 || RES_ROWS(db_res)[0].values[0].nul != 0)
	{
		LM_DBG("no value found\n");
		if (db_res!=NULL && db_funcs.free_result(db_handle, db_res) < 0)
			LM_DBG("failed to free the result\n");
		db_funcs.close(db_handle);
		return -1;
	}

	/* Print the first value */
	if(RES_ROWS(db_res)[0].values[0].type == DB_STRING)
		LM_DBG("first value found is [%s]\n",
			(char*)RES_ROWS(db_res)[0].values[0].val.string_val);
	else if(RES_ROWS(db_res)[0].values[0].type == DB_STR)
		LM_DBG("first value found is [%.*s]\n",
			RES_ROWS(db_res)[0].values[0].val.str_val.len,
			(char*)RES_ROWS(db_res)[0].values[0].val.str_val.s);
	else
		LM_DBG("first value found has an unexpected type [%d]\n",
			RES_ROWS(db_res)[0].values[0].type);

	/* Free the result */
	db_funcs.free_result(db_handle, db_res);
	db_funcs.close(db_handle);

	return 0;
}

...
		

RPC is designed as scanner-printer communication channel - RPC commands will scan the input for parameters as needed and will print back.

RPC API is very well documented at: http://www.kamailio.org/docs/docbooks/3.2.x/rpc_api/rpc_api.html. We will show next just an example of implementing a RPC command: pkg.stats - dump usage statistics of PKG (private) memory, implemented in modules_k/kex.

...
/**
 *
 */
static const char* rpc_pkg_stats_doc[2] = {
	"Private memory (pkg) statistics per process",
	0
};

/**
 *
 */
int pkg_proc_get_pid_index(unsigned int pid)
{
	int i;
	for(i=0; i<_pkg_proc_stats_no; i++)
	{
		if(_pkg_proc_stats_list[i].pid == pid)
			return i;
	}
	return -1;
}

/**
 *
 */
static void rpc_pkg_stats(rpc_t* rpc, void* ctx)
{
	int i;
	int limit;
	int cval;
	str cname;
	void* th;
	int mode;

	if(_pkg_proc_stats_list==NULL)
	{
		rpc->fault(ctx, 500, "Not initialized");
		return;
	}
	i = 0;
	mode = 0;
	cval = 0;
	limit = _pkg_proc_stats_no;
	if (rpc->scan(ctx, "*S", &cname) == 1)
	{
		if(cname.len==3 && strncmp(cname.s, "pid", 3)==0)
			mode = 1;
		else if(cname.len==4 && strncmp(cname.s, "rank", 4)==0)
			mode = 2;
		else if(cname.len==5 && strncmp(cname.s, "index", 5)==0)
			mode = 3;
		else {
			rpc->fault(ctx, 500, "Invalid filter type");
			return;
		}

		if (rpc->scan(ctx, "d", &cval) < 1)
		{
			rpc->fault(ctx, 500, "One more parameter expected");
			return;
		}
		if(mode==1)
		{
			i = pkg_proc_get_pid_index((unsigned int)cval);
			if(i<0)
			{
				rpc->fault(ctx, 500, "No such pid");
				return;
			}
			limit = i + 1;
		} else if(mode==3) {
			i=cval;
			limit = i + 1;
		}
	}

	for(; i<limit; i++)
	{
		/* add entry node */
		if(mode!=2 || _pkg_proc_stats_list[i].rank==cval)
		{
			if (rpc->add(ctx, "{", &th) < 0)
			{
				rpc->fault(ctx, 500, "Internal error creating rpc");
				return;
			}
			if(rpc->struct_add(th, "dddddd",
							"entry",     i,
							"pid",       _pkg_proc_stats_list[i].pid,
							"rank",      _pkg_proc_stats_list[i].rank,
							"used",      _pkg_proc_stats_list[i].used,
							"free",      _pkg_proc_stats_list[i].available,
							"real_used", _pkg_proc_stats_list[i].real_used
						)<0)
			{
				rpc->fault(ctx, 500, "Internal error creating rpc");
				return;
			}
		}
	}
}

/**
 *
 */
rpc_export_t kex_pkg_rpc[] = {
	{"pkg.stats", rpc_pkg_stats,  rpc_pkg_stats_doc,       0},
	{0, 0, 0, 0}
};

/**
 *
 */
int pkg_proc_stats_init_rpc(void)
{
	if (rpc_register_array(kex_pkg_rpc)!=0)
	{
		LM_ERR("failed to register RPC commands\n");
		return -1;
	}
	return 0;
}
...

			

To add new RPC commands to control interface, you have to register them. One option, which is used here, is to build an array with the new commands and the help messages for each one and the use rpc_register_array(...) function. You have the register the commands in mod_init() function - in our example it is done via pkg_proc_stats_init(), which is a wrapper function called from mod_init().

pkg.stats commands has optional parameters, which can be used to specify the pid, internal rank or position in internal process table (index) of the application process for which to dump the private memory statistics. If there is no parameter given, the the statistics for all processes will be printed.

The command itself is implemented in C function rpc_pkg_stats(...). In the first part, it reads the parameters. You can see there the search for optional parameter is done by using '*' in the front of the type of parameter (str):

			rpc->scan(ctx, "*S", &cname)

If this parameter is found, then there has to be another one, which this time is no longer optional.

			rpc->scan(ctx, "d", &cval)

Once input is read, follows the printing of the result in RPC structures. When kex module is loaded, one can use pkg.stats command via sercmd tool like:

	sercmd pkg.stats
	sercmd pkg.stats index 2
	sercmd pkg.stats rank 4
	sercmd pkg.stats pid 8492

The Management Interface is an abstract layer introduced to allow interaction between Kamailio and external applications like shell terminal or web applications. It is an old alternative to RPC control interface, which is going to be obsoleted in the future.

MI is built on a tree architecture - the input is parsed completely and stored as a tree in memory. The commands get access to the tree and build another tree with the response, which is then printed back to the transport layer.

In the past, there were two ways to interact with such applications: via FIFO file and via unix sockets.

MI came and introduced an abstractization between the transport and application levels. All MI commands are available for all available transports. At this moment the following transports are available:

To implement a new command for MI you don't need to interact with the transports. MI will pass to your function a compiled version of the command, in the form of a tree. The functions walks through the tree, finds the input parameters, executes the actions accordingly, and returns a new MI tree with the response to the command.

...
struct mi_root my_my_function(struct mi_root *tree, void *param);
...
		

...
typedef struct mi_root* (mi_cmd_f)(struct mi_root*, void *param);
typedef int (mi_child_init_f)(void);

int register_mi_cmd(mi_cmd_f f, char *name, void *param,
		mi_child_init_f in, unsigned int flags);
...
		

...
static struct mi_root* ds_mi_set(struct mi_root* cmd_tree, void* param)
{
	str sp;
	int ret;
	unsigned int group, state;
	struct mi_node* node;

	node = cmd_tree->node.kids;
	if(node == NULL)
		return init_mi_tree(400, MI_MISSING_PARM_S, MI_MISSING_PARM_LEN);
	sp = node->value;
	if(sp.len<=0 || !sp.s)
	{
		LM_ERR("bad state value\n");
		return init_mi_tree(500, "bad state value", 15);
	}

	state = 0;
	if(sp.s[0]=='0' || sp.s[0]=='I' || sp.s[0]=='i') {
		/* set inactive */
		state |= DS_INACTIVE_DST;
		if((sp.len>1) && (sp.s[1]=='P' || sp.s[1]=='p'))
			state |= DS_PROBING_DST;
	} else if(sp.s[0]=='1' || sp.s[0]=='A' || sp.s[0]=='a') {
		/* set active */
		if((sp.len>1) && (sp.s[1]=='P' || sp.s[1]=='p'))
			state |= DS_PROBING_DST;
	} else if(sp.s[0]=='2' || sp.s[0]=='D' || sp.s[0]=='d') {
		/* set disabled */
		state |= DS_DISABLED_DST;
	} else if(sp.s[0]=='3' || sp.s[0]=='T' || sp.s[0]=='t') {
		/* set trying */
		state |= DS_TRYING_DST;
		if((sp.len>1) && (sp.s[1]=='P' || sp.s[1]=='p'))
			state |= DS_PROBING_DST;
	} else {
		LM_ERR("unknow state value\n");
		return init_mi_tree(500, "unknown state value", 19);
	}
	node = node->next;
	if(node == NULL)
		return init_mi_tree(400, MI_MISSING_PARM_S, MI_MISSING_PARM_LEN);
	sp = node->value;
	if(sp.s == NULL)
	{
		return init_mi_tree(500, "group not found", 15);
	}

	if(str2int(&sp, &group))
	{
		LM_ERR("bad group value\n");
		return init_mi_tree( 500, "bad group value", 16);
	}

	node= node->next;
	if(node == NULL)
		return init_mi_tree( 400, MI_MISSING_PARM_S, MI_MISSING_PARM_LEN);

	sp = node->value;
	if(sp.s == NULL)
	{
		return init_mi_tree(500,"address not found", 18 );
	}

	ret = ds_reinit_state(group, &sp, state);

	if(ret!=0)
	{
		return init_mi_tree(404, "destination not found", 21);
	}

	return init_mi_tree( 200, MI_OK_S, MI_OK_LEN);
}
...

		

...
:_command_name_:_reply_fifo_file_
_parameters_
_empty_line_
...
		

...
:ds_set_state:kamailio_fifo_reply
i
2
sip:10.10.10.10:5080
\n
...
		

The naming format for a pseudo-variable is described in the next example:

...
marker classname
marker '(' classname ')'
marker '(' classname '[' index ']' ')'
marker '(' classname ( '{' transformation '}' )+ ')'
marker '(' classname '[' index ']' ( '{' transformation '}' )+ ')'
marker classname '(' innername ')'
marker '(' classname '(' innername ')' ')'
marker '(' classname '(' innername ')' '[' index ']' ')'
marker '(' classname '(' innername ')' ( '{' transformation '}' )+ ')'
marker '(' classname '(' innername ')' '[' index ']' ( '{' transformation '}' )+ ')'
...
		

Meaning of the tokens:

Some examples with pseudo-variable names:

...
$ru - reference to request URI
$(ru) - same as above - this format can be used when the class name cannot be delimited. It must
        be used if the PV has index or transformations.
$avp(s:test) - the AVP with the string name 'test'
$(avp(test)[2]) - the third AVP with the string name 'test'
...
		

The prototypes and data structures for pseudo-variables are defined in pvar.h.

...
typedef struct _pv_value
{
	str rs;    /* string value */
	int ri;    /* integer value */
	int flags; /* flags about the type of value */
} pv_value_t, *pv_value_p;

...
			

...
#define PV_VAL_NONE			0    // no actual value -- it is so just at initialization
#define PV_VAL_NULL			1    // the value must be considered NULL
#define PV_VAL_EMPTY		2    // the value is an empty string (deprecated)
#define PV_VAL_STR			4    // the value has the string attribute 'rs' set
#define PV_VAL_INT			8    // the value has the integer attribute 'ri' set
#define PV_TYPE_INT			16   // the value may have both string and integer attribute set, but type is integer
#define PV_VAL_PKG			32   // the value was duplicated in pkg memory, free it accordingly at destroy time
#define PV_VAL_SHM			64   // the value was duplicated in shm memory, free it accordingly at destroy time
...
			

...
typedef struct _pv_name
{
	int type;             /* type of name */
	union {
		struct {
			int type;     /* type of int_str name - compatibility with AVPs */
			int_str name; /* the value of the name */
		} isname;
		void *dname;      /* PV value - dynamic name */
	} u;
} pv_name_t, *pv_name_p;

...
			

...
#define PV_NAME_INTSTR	0 // the name is constant, an integer or string
#define PV_NAME_PVAR	1 // the name is dynamic, a pseudo-variable
#define PV_NAME_OTHER	2 // the name is specific per implementation

...
			

...
0                                       // the name is integer

#define AVP_NAME_STR     (1<<0)   // 1 - the name is string
...
			

...
typedef struct _pv_index
{
	int type; /* type of PV index */
	union {
		int ival;   /* integer value */
		void *dval; /* PV value - dynamic index */
	} u;
} pv_index_t, *pv_index_p;

...
			

...
#define PV_IDX_INT	0  // the index is integer value
#define PV_IDX_PVAR	1  // the index is dynamic, a pseudo-variable
#define PV_IDX_ALL	2  // the index specifies to return all values for that pseudo-variables
                       // - this is up to implementation of pseudo-variable class
...
			

...
typedef struct _pv_param
{
	pv_name_t    pvn; /* PV name */
	pv_index_t   pvi; /* PV index */
} pv_param_t, *pv_param_p;

...
		

...
typedef int (*pv_getf_t) (struct sip_msg*,  pv_param_t*, pv_value_t*);
typedef int (*pv_setf_t) (struct sip_msg*,  pv_param_t*, int, pv_value_t*);

typedef struct _pv_spec {
	pv_type_t    type;   /* type of PV */
	pv_getf_t    getf;   /* get PV value function */
	pv_setf_t    setf;   /* set PV value function */
	pv_param_t   pvp;    /* parameter to be given to get/set functions */
	void         *trans; /* transformations */
} pv_spec_t, *pv_spec_p;

...
			

...
typedef int (*pv_parse_name_f)(pv_spec_p sp, str *in);
typedef int (*pv_parse_index_f)(pv_spec_p sp, str *in);
typedef int (*pv_init_param_f)(pv_spec_p sp, int param);

typedef struct _pv_export {
	str name;                      /* class name of PV */
	pv_type_t type;                /* type of PV */
	pv_getf_t  getf;               /* function to get the value */
	pv_setf_t  setf;               /* function to set the value */
	pv_parse_name_f parse_name;    /* function to parse the inner name */
	pv_parse_index_f parse_index;  /* function to parse the index of PV */
	pv_init_param_f init_param;    /* function to init the PV spec */
	int iparam;                    /* parameter for the init function */
} pv_export_t;

...
			

We will show how to add a simple pseudo-variable in the core, later will show how to add a pseudo-variable with a inner name via module interface. $ru (request URI) is taken as example. This pseudo-variable is read/write, so we have to implement the get and set functions. These are in file module_k/pv/pv_core.c.

...
static int pv_get_ruri(struct sip_msg *msg, pv_param_t *param,
		pv_value_t *res)
{
	if(msg==NULL || res==NULL)
		return -1;

	if(msg->first_line.type == SIP_REPLY)	/* REPLY doesn't have a ruri */
		return pv_get_null(msg, param, res);

	if(msg->parsed_uri_ok==0 /* R-URI not parsed*/ && parse_sip_msg_uri(msg)<0)
	{
		LM_ERR("failed to parse the R-URI\n");
		return pv_get_null(msg, param, res);
	}
	
	if (msg->new_uri.s!=NULL)
		return pv_get_strval(msg, param, res, &msg->new_uri);
	return pv_get_strval(msg, param, res, &msg->first_line.u.request.uri);
}
...
int pv_set_ruri(struct sip_msg* msg, pv_param_t *param,
		int op, pv_value_t *val)
{
	struct action  act;
	struct run_act_ctx h;
	char backup;

	if(msg==NULL || param==NULL || val==NULL || (val->flags&PV_VAL_NULL))
	{
		LM_ERR("bad parameters\n");
		return -1;
	}

	if(!(val->flags&PV_VAL_STR))
	{
		LM_ERR("str value required to set R-URI\n");
		goto error;
	}
	
	memset(&act, 0, sizeof(act));
	act.val[0].type = STRING_ST;
	act.val[0].u.string = val->rs.s;
	backup = val->rs.s[val->rs.len];
	val->rs.s[val->rs.len] = '\0';
	act.type = SET_URI_T;
	init_run_actions_ctx(&h);
	if (do_action(&h, &act, msg)<0)
	{
		LM_ERR("do action failed\n");
		val->rs.s[val->rs.len] = backup;
		goto error;
	}
	val->rs.s[val->rs.len] = backup;

	return 0;
error:
	return -1;
}
...

		

The parameters to the functions are:

The functions return 0 in case of success and <0 in case of error.

In the get function, it checks whether there is a new request URI values and return that. If not, returns the URI from the original SIP message. It takes care that the URI is parsed, so it is valid.

In the set function, it checks to be sure that the value to assign is a string, and then calls the internal SET_URI_T action.

The last step is to add the proper entry in the pseudo-variables table (see modules_k/pv/pv.c) -- remember that this is required only for pseudo-variables included in core, not for the ones exported by modules.

...
static pv_export_t mod_pvs[] = {

...
	{{"ruri", (sizeof("ruri")-1)}, /* */
		PVT_RURI, pv_get_ruri, pv_set_ruri,
		0, 0, 0, 0},
...
	{{0,0}, 0, 0, 0, 0, 0, 0, 0}
};
...
		

... and do not forget to document in the Pseudo-Variable Cookbok.

The transformations are given in between the pharantesis around the parenthesis of a pseudo-variable. The transformation name and parameters are enclosed in between curly brackets { }. The grammar for a transformation specifier:

...
'{' classname '.' innername ( ',' parameter )* '}'
...
		

The tokens are:

Example of existing transformations:

...
{s.substr,1,2} - return the string with second and the third characters (substring of length 2 from the
                 second character)
{uri.user} -  return the user part of the SIP URI stored in the pseudo-variable on which this transformation
              is applied
...
		

Internally, to the classname of a transformation it is associated type, an integer number, and to the innername a subtype, also an integer number. Constants and definitions are in file transformations.h

...
typedef struct _tr_param {
	int type;        /* type of the parameter value */
	union {
		int n;       /* the integer value of the parameter */
		str s;       /* the string value of the parameter */
		void *data;  /* pseudo-variable spec of the parameter */
	} v;
	struct _tr_param *next; /* link to next parameter */
} tr_param_t, *tr_param_p;

typedef int (*tr_func_t) (struct sip_msg *, tr_param_t*, int, pv_value_t*);

typedef struct _trans {
	str name;               /* full name of the transformation */
	int type;               /* the id of the transformation class */
	int subtype;            /* the id of the transformation inner name */
	tr_func_t trf;          /* the function to be executed when applying the transformation */
	tr_param_t *params;     /* the parameters for this transformation */
	struct _trans *next;    /* link to next transformation to be applied to same pseudo-variable */
} trans_t, *trans_p;
...
		

The parameters of the function to be executed for a transformation:

There is one function for each transformation class, the exact operation to be applied is given via subtype. The structure trans_t is what stands behind each transformation occurrence.

The transformation framework keeps for each transformation class a function to parse the innername and the parameters, plus a function to execute when the transformation need to be applied. To add new transformations, you have to implement the two functions.

Exemplifying with transformation s.len - it returns the length of the string value of a pseudo-variable. The type TR_STRING and subtype TR_S_LEN are added in file modules_k/pv/pv_trans.h - these are internal IDs used for runtime optimizations.

The function tr_parse_string() in file modules_k/pv/pv_trans.c is implementing the parser of the class s. In this function, if the inner name is len it sets the subtype accordingly.

...
	if(name.len==3 && strncasecmp(name.s, "len", 3)==0)
	{
		t->subtype = TR_S_LEN;
		return p;
	}
...
		

The transformation parser is now extended. Next is the interpreter, the function tr_eval_str(...) - the evaluation function will be associated to string transformation by the parser function tr_parse_string().

...
	switch(subtype)
	{
		case TR_S_LEN:
			if(!(val->flags&PV_VAL_STR))
				val->rs.s = int2str(val->ri, &val->rs.len);

			val->flags = PV_TYPE_INT|PV_VAL_INT|PV_VAL_STR;
			val->ri = val->rs.len;
			val->rs.s = int2str(val->ri, &val->rs.len);
			break;
...
		

The content of the pv_value_t variable is replaced with the length of the string representation of its initial value. An example of usage is shown next - get the length of request URI:

...
$var(x) = $(ru{s.len});
...
		

To make the transformations available to the core API, you have to register them. You can do it via mod_register(...) function. Note that this function is executed when the module is loaded, making possible to use the transformation in module parameters and configuration file operations. See modules_k/pv/pv.c:

...
static tr_export_t mod_trans[] = {
	{ {"s", sizeof("s")-1}, /* string class */
		tr_parse_string },
	{ {"nameaddr", sizeof("nameaddr")-1}, /* nameaddr class */
		tr_parse_nameaddr },
	{ {"uri", sizeof("uri")-1}, /* uri class */
		tr_parse_uri },
	{ {"param", sizeof("param")-1}, /* param class */
		tr_parse_paramlist },
	{ {"tobody", sizeof("tobody")-1}, /* param class */
		tr_parse_tobody },

	{ { 0, 0 }, 0 }
};
...
int mod_register(char *path, int *dlflags, void *p1, void *p2)
{
	return register_trans_mod(path, mod_trans);
}
...
		

There are three macros that help to deal with statistic values easily.

The functions that can be given as callbacks for timer have the following prototypes:

...
typedef unsigned long long utime_t;

typedef void (timer_function)(unsigned int ticks, void* param);
...
		

Parameters are:

Register a function to be executed by second-based timer:

...
int register_timer(timer_function f, void* param, unsigned int interval);
...
		

Parameters:

Register a function to start a new timer process:

...
int register_timer_process(timer_function f, void* param, unsigned int interval);
...
		

Parameters:

There are two functions that return the number of ticks elapsed since Kamailio started, one returning time in seconds and the other one returning the number of internal ticks.

...
unsigned int get_ticks(void);

utime_t get_ticks_raw(void);
...
		

Next we will show how the module msilo register a timer function to clean the stored messages. See modules/msilo/msilo.c.

...
#include "../../timer.h"
...
void m_clean_silo(unsigned int ticks, void *);
...
		

Registration to the second-based timer is done in function mod_init().

...
register_timer(m_clean_silo, 0, ms_check_time);
...
		

Function implementation is:

...

/**
 * - cleaning up the messages that got reply
 * - delete expired messages from database
 */
void m_clean_silo(unsigned int ticks, void *param)
{
	msg_list_el mle = NULL, p;
	db_key_t db_keys[MAX_DEL_KEYS];
	db_val_t db_vals[MAX_DEL_KEYS];
	db_op_t  db_ops[1] = { OP_LEQ };
	int n;
	
	LM_DBG("cleaning stored messages - %d\n", ticks);
	
	msg_list_check(ml);
	mle = p = msg_list_reset(ml);
	n = 0;
	while(p)
	{
		if(p->flag & MS_MSG_DONE)
		{
#ifdef STATISTICS
			if(p->flag & MS_MSG_TSND)
				update_stat(ms_dumped_msgs, 1);
			else
				update_stat(ms_dumped_rmds, 1);
#endif

			db_keys[n] = &sc_mid;
			db_vals[n].type = DB1_INT;
			db_vals[n].nul = 0;
			db_vals[n].val.int_val = p->msgid;
			LM_DBG("cleaning sent message [%d]\n", p->msgid);
			n++;
			if(n==MAX_DEL_KEYS)
			{
				if (msilo_dbf.delete(db_con, db_keys, NULL, db_vals, n) < 0) 
					LM_ERR("failed to clean %d messages.\n",n);
				n = 0;
			}
		}
		if((p->flag & MS_MSG_ERRO) && (p->flag & MS_MSG_TSND))
		{ /* set snd time to 0 */
			ms_reset_stime(p->msgid);
#ifdef STATISTICS
			update_stat(ms_failed_rmds, 1);
#endif

		}
#ifdef STATISTICS
		if((p->flag & MS_MSG_ERRO) && !(p->flag & MS_MSG_TSND))
			update_stat(ms_failed_msgs, 1);
#endif
		p = p->next;
	}
	if(n>0)
	{
		if (msilo_dbf.delete(db_con, db_keys, NULL, db_vals, n) < 0) 
			LM_ERR("failed to clean %d messages\n", n);
		n = 0;
	}

	msg_list_el_free_all(mle);
	
	/* cleaning expired messages */
	if(ticks%(ms_check_time*ms_clean_period)<ms_check_time)
	{
		LM_DBG("cleaning expired messages\n");
		db_keys[0] = &sc_exp_time;
		db_vals[0].type = DB1_INT;
		db_vals[0].nul = 0;
		db_vals[0].val.int_val = (int)time(NULL);
		if (msilo_dbf.delete(db_con, db_keys, db_ops, db_vals, 1) < 0) 
			LM_DBG("ERROR cleaning expired messages\n");
	}
}

...
		

The function deletes from database the messages that were succesfully delivered and the messages that were stored for too long time in database and the recipient was not online or not able to receive them.

Sometime might be better to have your own timer process, not to disturb the operations done by other timer function - recommended when you are doing operation that may take a while on timer basis.

You can create as many timer processes as you need - it takes two steps:

...
/**
 * init module function
 */
static int mod_init(void)
{
	...
	register_dummy_timers(1);
	...
}
...
/**
 * init module children
 */
static int child_init(int rank)
{
	...
	if (rank==PROC_MAIN)
	{
		if(fork_dummy_timer(PROC_TIMER, "MY MOD TIMER", 1 /*socks flag*/,
				my_timer_callback, my_timer_param, 1 /*sec*/) < 0) {
			LM_ERR("failed to register timer routine as process\n");
			return -1; /* error */
		}
	}
	...
}
...
		

The main structure that has to be exported by a module. It is defined in file sr_module.h.

...
struct module_exports{
	char* name;                     /* null terminated module name */
	unsigned int dlflags;           /* flags for dlopen */
	
	cmd_export_t* cmds;             /* null terminated array of the exported
	                                   commands */
	param_export_t* params;         /* null terminated array of the exported
	                                   module parameters */

	stat_export_t* stats;           /* null terminated array of the exported
	                                   module statistics */

	mi_export_t* mi_cmds;           /* null terminated array of the exported
	                                   MI functions */

	pv_export_t* items;             /* null terminated array of the exported
	                                   module items (pseudo-variables) */

	proc_export_t* procs;           /* null terminated array of the additional
	                                   processes reqired by the module */

	init_function init_f;           /* Initialization function */
	response_function response_f;   /* function used for responses,
	                                   returns yes or no; can be null */
	destroy_function destroy_f;     /* function called when the module should
	                                   be "destroyed", e.g: on kamailio exit */
	child_init_function init_child_f;/* function called by all processes
	                                    after the fork */
};
...
			

The comments in the definition are explanatory, each internal structure and data type is detailed in the next sections.

Starting with version 3.0, there are two module interfaces: one specific to Kamailio flavour and the other one specific for SER flavour. A third one will merge the two in the near future. At this moment, each module has to specify in the Makefile what kind of interface implements. In this chapter, the focus is on writing modules implementing Kamailio specific module interface.

The structure corresponds to a function exported by modules

...
struct cmd_export_ {
	char* name;             /* null terminated command name */
	cmd_function function;  /* pointer to the corresponding function */
	int param_no;           /* number of parameters used by the function */
	fixup_function fixup;   /* pointer to the function called to "fix" the
							   parameters */
	free_fixup_function
				free_fixup; /* pointer to the function called to free the
							   "fixed" parameters */
	int flags;              /* Function flags */
};
typedef struct cmd_export_ cmd_export_t;
...
		

Flags can be a bit mask of:

The structure specifies a parameter exported by a module.

...
struct param_export_ {
	char* name;             /* null terminated param. name */
	modparam_t type;        /* param. type */
	void* param_pointer;    /* pointer to the param. memory location or to function to set the parameter */
};
typedef struct param_export_ param_export_t;
...
		

The type can be:

When using USE_FUNC_PARAM flag, the param_pointer must be set to a function with the following type:

...
typedef int (*param_func_t)( modparam_t type, void* val);
...
		

Parameters are:

The function has to return 0 in case of success.

This field is no longer active, it is kept for no-error at compilation time during a transition period and will be removed in the future. To create new application processes, you have to use a two steps mechanism that ensures inheriting proper TCP/TLS handling.

First you have to declare in mod_init() how many processes you want to start, the fork new processes in init_child() for RANK_PROC_MAIN:

...

static int mod_init(void)
{
	...
	/* add space for one extra process */
	register_procs(1);
	...
}	
...
static int child_init(int rank)
{
	int pid;

	...
	if (rank==PROC_MAIN) {
		pid=fork_process(PROC_NOCHLDINIT, "MY PROC DESCRIPTION", 1);
		if (pid<0)
			return -1; /* error */
		if(pid==0){
			/* child */

			/* initialize the config framework */
			if (cfg_child_init())
				return -1;

			my_process_main_function(...);
		}
	}
	...

	return 0;
}

...
		

register_procs(no) takes as parameter the number of processes to be created. fork_process(...) takes as parameters: flag specifying wheter to execute child_init() functions for the new process; string with description of the process; flag specifying whether to create internal unix sockets or not for the new process (needed for TCP/TLS communication, use 1 to be safe always).

Typical module implementations for such functionality are the MI transports module. They require a special process to listen to the MI transport layer.

The structure allow to export statistics variables from your module.

...
typedef struct stat_export_ {
	char* name;                /* null terminated statistic name */
	int flags;                 /* flags */
	stat_var** stat_pointer;   /* pointer to the variable's mem location *
	                            * NOTE - it's in shm mem */
} stat_export_t;
...
		

This field is currently in passive mode inside module_exports structure. You have to explicitely register the statistics inside mod_init() via register_module_stats(). For example in modules_k/msilo:

...

stat_export_t msilo_stats[] = {
	{"stored_messages" ,  0,  &ms_stored_msgs  },
	{"dumped_messages" ,  0,  &ms_dumped_msgs  },
	{"failed_messages" ,  0,  &ms_failed_msgs  },
	{"dumped_reminders" , 0,  &ms_dumped_rmds  },
	{"failed_reminders" , 0,  &ms_failed_rmds  },
	{0,0,0}
};
...
static int mod_init(void)
{
	...
	/* register statistics */
	if (register_module_stats( exports.name, msilo_stats)!=0 ) {
		LM_ERR("failed to register core statistics\n");
		return -1;
	}
	...
}
...
		</programlisting>
		<para>
			For more see the chapter <emphasis role="strong">Statistics</emphasis>.
		</para>
	</section>
	<section id="c16t_mi_export_t">
		<title>mi_export_t type</title>
		<para>
			The structure to export MI commands. For more see the chapter <emphasis role="strong">Management Interface</emphasis>.
		</para>
		<programlisting  format="linespecific">
...
typedef struct mi_export_ {
	char *name;              /* name of MI command */
	mi_cmd_f *cmd;           /* function to be executed for the MI command */
	unsigned int flags;      /* flags associated to the MI command */
	void *param;             /* parameter to be given to the MI command */
	mi_child_init_f *init_f; /* function to be executed at MI process initialization in order to
	                          * have function 'cmd' working properly */
}mi_export_t;

...
		

The structure to export pseudo-variables from module. See the chapter Pseudo Variables for detailed description.

...
typedef struct _pv_export {
	str name;                      /* class name of PV */
	pv_type_t type;                /* type of PV */
	pv_getf_t  getf;               /* function to get the value */
	pv_setf_t  setf;               /* function to set the value */
	pv_parse_name_f parse_name;    /* function to parse the inner name */
	pv_parse_index_f parse_index;  /* function to parse the index of PV */
	pv_init_param_f init_param;    /* function to init the PV spec */
	int iparam;                    /* parameter for the init function */
} pv_export_t;
...
		

An example of module that exports pseudo-variables is modules/mqueue:

...
static pv_export_t mod_pvs[] = {
	{ {"mqk", sizeof("mqk")-1}, PVT_OTHER, pv_get_mqk, 0,
		pv_parse_mqk_name, 0, 0, 0 },
	{ {"mqv", sizeof("mqv")-1}, PVT_OTHER, pv_get_mqv, 0,
		pv_parse_mqv_name, 0, 0, 0 },
	{ {0, 0}, 0, 0, 0, 0, 0, 0, 0 }
};
...
truct module_exports exports = {
	"mqueue",
	DEFAULT_DLFLAGS, /* dlopen flags */
	cmds,
	params,
	0,
	0,              /* exported MI functions */
	mod_pvs,        /* exported pseudo-variables */
	0,              /* extra processes */
	mod_init,       /* module initialization function */
	0,              /* response function */
	mod_destroy,    /* destroy function */
	0               /* per child init function */
};
...
		

These are the types of functions used in the structure module_exports.

...
typedef  int (*cmd_function)(struct sip_msg*, char*, char*, char*, char*, char*, char*);
typedef  int (*fixup_function)(void** param, int param_no);
typedef  int (*free_fixup_function)(void** param, int param_no);
typedef  int (*response_function)(struct sip_msg*);
typedef void (*destroy_function)();
typedef int (*init_function)(void);
typedef int (*child_init_function)(int rank);
...
		

Description:

These are the functions implemented by the module that can be invoked from the configuration file. It has a strict prototype. First parameter is the pointer to structure with the current processed SIP message. Next are char*. Most existing command functions have up to two char* parameters, recent extensions allow up to six such parameters.

It means that in the configuration file you can give only char* values as parameter. Kamailio provides the mechanisms to convert the values to something more meaningful for the module, during Kamailio start up, via fixup functions.

When calling from the configuration file, the structure sip_msg is not given as parameter, it is added by the config interpreter when calling the C function. The name of the function available in the configuration file may be different that the name of the C function. There can be different C functions behind the same config file function, when the number of the parameters is different.

...

int fixup_uint(void** param)
{
	unsigned int ui;
	str s;

	s.s = (char*)*param;
	s.len = strlen(s.s);
	if(str2int(&s, &ui)==0)
	{
		pkg_free(*param);
		*param=(void *)(unsigned long)ui;
		return 0;
	}
	LM_ERR("bad number <%s>\n", (char *)(*param));
	return E_CFG;
}

/**
 * fixup for functions that get one parameter
 * - first parameter is converted to unsigned int
 */
int fixup_uint_null(void** param, int param_no)
{
	if(param_no != 1)
	{
		LM_ERR("invalid parameter number %d\n", param_no);
		return E_UNSPEC;
	}
	return fixup_uint(param);
}

...
			

Here we show the steps to develop new modules, exemplifying with code from different modules.

Prior starting writing code, check with developers whether that functionality is already implemented. Also try to identify whether the extension fits better in an existing module or needs to be created a new one.

...
mkdir modules/my_new_module
...
			

...
include ../../Makefile.defs
auto_gen=
NAME=regex.so

BUILDER = $(shell which pcre-config)

ifeq ($(BUILDER),)
	PCREDEFS=-I$(LOCALBASE)/include -I/usr/local/include -I/opt/include \
	-I/usr/sfw/include
	PCRELIBS=-L$(LOCALBASE)/lib -L/usr/local/lib -L/usr/sfw/lib \
	-L/opt/lib -lpcre
else
	PCREDEFS = $(shell pcre-config --cflags)
	PCRELIBS = $(shell pcre-config --libs)
endif

DEFS+=$(PCREDEFS)
LIBS=$(PCRELIBS)

DEFS+=-DOPENSER_MOD_INTERFACE

SERLIBPATH=../../lib
SER_LIBS+=$(SERLIBPATH)/kmi/kmi
include ../../Makefile.modules
...
		

...
include ../../Makefile.defs
auto_gen=
NAME=my_new_module.so
LIBS=

DEFS+=-DOPENSER_MOD_INTERFACE

include ../../Makefile.modules
...
			

...
MODULE_VERSION
...
			

...
static int initial = 10;

static char* hash_file = NULL;

static param_export_t params[]={ 
...
	{"initial_probability", INT_PARAM, &initial},
	{"hash_file",           STR_PARAM, &hash_file        },
...
	{"shvset",              STR_PARAM|USE_FUNC_PARAM, (void*)param_set_shvar },
...
	{0,0,0}
};

...
			

...

int param_set_xvar( modparam_t type, void* val, int mode)
{
	str s;
	char *p;
	int_str isv;
	int flags;
	int ival;
	script_var_t *pkv;
	sh_var_t *shv;

	if(!shm_initialized()!=0)
	{
		LM_ERR("shm not initialized - cannot set value for PVs\n");
		goto error;
	}

	s.s = (char*)val;
	if(s.s == NULL || s.s[0] == '\0')
		goto error;

	p = s.s;
	while(*p && *p!='=') p++;

	if(*p!='=')
		goto error;
	
	s.len = p - s.s;
	if(s.len == 0)
		goto error;
	p++;
	flags = 0;
	if(*p!='s' && *p!='S' && *p!='i' && *p!='I')
		goto error;

	if(*p=='s' || *p=='S')
		flags = VAR_VAL_STR;
	p++;
	if(*p!=':')
		goto error;
	p++;
	isv.s.s = p;
	isv.s.len = strlen(p);
	if(flags != VAR_VAL_STR) {
		if(str2sint(&isv.s, &ival)<0)
			goto error;
		isv.n = ival;
	}
	if(mode==0) {
		pkv = add_var(&s);
		if(pkv==NULL)
			goto error;
		if(set_var_value(pkv, &isv, flags)==NULL)
			goto error;
	} else {
		shv = add_shvar(&s);
		if(shv==NULL)
			goto error;
		if(set_shvar_value(shv, &isv, flags)==NULL)
			goto error;
	}
	
	return 0;
error:
	LM_ERR("unable to set shv parame [%s]\n", s.s);
	return -1;
}

int param_set_shvar( modparam_t type, void* val)
{
	return param_set_xvar(type, val, 1);
}

...
			

...
modparam("pv", "shvset", "debug=i:1")
...
			

...

static int mod_init(void)
{
	if(register_mi_mod(exports.name, mi_cmds)!=0)
	{
		LM_ERR("failed to register MI commands\n");
		return -1;
	}

	if (!hash_file) {
		LM_INFO("no hash_file given, disable hash functionality\n");
	} else {
		if (MD5File(config_hash, hash_file) != 0) {
			LM_ERR("could not hash the config file");
			return -1;
		}
		LM_DBG("config file hash is %.*s", MD5_LEN, config_hash);
	}

	if (initial_prob > 100) {
		LM_ERR("invalid probability <%d>\n", initial_prob);
		return -1;
	}
	LM_DBG("initial probability %d percent\n", initial_prob);

	probability=(int *) shm_malloc(sizeof(int));

	if (!probability) {
		LM_ERR("no shmem available\n");
		return -1;
	}
	*probability = initial_prob;

	gflags=(unsigned int *) shm_malloc(sizeof(unsigned int));
	if (!gflags) {
		LM_ERR(" no shmem available\n");
		return -1;
	}
	*gflags=initial_gflags;
	if(_cfg_lock_size>0 && _cfg_lock_size<=10)
	{
		_cfg_lock_size = 1<<_cfg_lock_size;
		_cfg_lock_set = lock_set_alloc(_cfg_lock_size);
		if(_cfg_lock_set==NULL || lock_set_init(_cfg_lock_set)==NULL)
		{
			LM_ERR("cannot initiate lock set\n");
			return -1;
		}
	}
	return 0;
}

...
			

...

static int child_init(int rank)
{
	if (rank==PROC_INIT || rank==PROC_MAIN || rank==PROC_TCP_MAIN)
		return 0; /* do nothing for the main process */

	db_handle = db_funcs.init(&db_url);
	if (!db_handle)
	{
		LM_ERR("failed to connect database\n");
		return -1;
	}
	return 0;

}

...
			

...
static void mod_destroy(void)
{
	if (probability)
		shm_free(probability);
	if (gflags)
		shm_free(gflags);
	if(_cfg_lock_set!=NULL)
	{
		lock_set_destroy(_cfg_lock_set);
		lock_set_dealloc(_cfg_lock_set);
	}
}
...
			

...
static cmd_export_t cmds[]={
...
	{"sleep",    (cmd_function)m_sleep,    1,      fixup_uint_null, 0, 
			ANY_ROUTE},
...
	{0, 0, 0, 0, 0, 0}
};
...

static int m_sleep(struct sip_msg *msg, char *time, char *str2)
{
	LM_DBG("sleep %lu seconds\n", (unsigned long)time);
	sleep((unsigned int)(unsigned long)time);
	return 1;
}

...
			

...
sleep("3");
...
			

...

static pv_export_t mod_items[] = {
...
	{ {"time", (sizeof("time")-1)}, 1002, pv_get_time,
		0, pv_parse_time_name, 0, 0, 0},
...
	{ {0, 0}, 0, 0, 0, 0, 0, 0, 0 }
};
...
int pv_parse_time_name(pv_spec_p sp, str *in)
{
	if(sp==NULL || in==NULL || in->len<=0)
		return -1;

	switch(in->len)
	{
		case 3: 
			if(strncmp(in->s, "sec", 3)==0)
				sp->pvp.pvn.u.isname.name.n = 0;
			else if(strncmp(in->s, "min", 3)==0)
				sp->pvp.pvn.u.isname.name.n = 1;
			else if(strncmp(in->s, "mon", 3)==0)
				sp->pvp.pvn.u.isname.name.n = 4;
			else goto error;
		break;
		case 4: 
			if(strncmp(in->s, "hour", 4)==0)
				sp->pvp.pvn.u.isname.name.n = 2;
			else if(strncmp(in->s, "mday", 4)==0)
				sp->pvp.pvn.u.isname.name.n = 3;
			else if(strncmp(in->s, "year", 4)==0)
				sp->pvp.pvn.u.isname.name.n = 5;
			else if(strncmp(in->s, "wday", 4)==0)
				sp->pvp.pvn.u.isname.name.n = 6;
			else if(strncmp(in->s, "yday", 4)==0)
				sp->pvp.pvn.u.isname.name.n = 7;
			else goto error;
		break;
		case 5: 
			if(strncmp(in->s, "isdst", 5)==0)
				sp->pvp.pvn.u.isname.name.n = 8;
			else goto error;
		break;
		default:
			goto error;
	}
	sp->pvp.pvn.type = PV_NAME_INTSTR;
	sp->pvp.pvn.u.isname.type = 0;

	return 0;

error:
	LM_ERR("unknown PV time name %.*s\n", in->len, in->s);
	return -1;
}
...
static struct tm _cfgutils_ts;
static unsigned int _cfgutils_msg_id = 0;

int pv_get_time(struct sip_msg *msg, pv_param_t *param,
		pv_value_t *res)
{
	time_t t;

	if(msg==NULL || param==NULL)
		return -1;

	if(_cfgutils_msg_id != msg->id)
	{
		pv_update_time(msg, &t);
		_cfgutils_msg_id = msg->id;
		if(localtime_r(&t, &_cfgutils_ts) == NULL)
		{
			LM_ERR("unable to break time to attributes\n");
			return -1;
		}
	}
	
	switch(param->pvn.u.isname.name.n)
	{
		case 1:
			return pv_get_uintval(msg, param, res, (unsigned int)_cfgutils_ts.tm_min);
		case 2:
			return pv_get_uintval(msg, param, res, (unsigned int)_cfgutils_ts.tm_hour);
		case 3:
			return pv_get_uintval(msg, param, res, (unsigned int)_cfgutils_ts.tm_mday);
		case 4:
			return pv_get_uintval(msg, param, res, 
					(unsigned int)(_cfgutils_ts.tm_mon+1));
		case 5:
			return pv_get_uintval(msg, param, res,
					(unsigned int)(_cfgutils_ts.tm_year+1900));
		case 6:
			return pv_get_uintval(msg, param, res, 
					(unsigned int)(_cfgutils_ts.tm_wday+1));
		case 7:
			return pv_get_uintval(msg, param, res, 
					(unsigned int)(_cfgutils_ts.tm_yday+1));
		case 8:
			return pv_get_sintval(msg, param, res, _cfgutils_ts.tm_isdst);
		default:
			return pv_get_uintval(msg, param, res, (unsigned int)_cfgutils_ts.tm_sec);
	}
}

...
			

...

static mi_export_t mi_cmds[] = {
...
	{ "shv_set" ,      mi_shvar_set,  0,                 0,  0 },
...
	{ 0, 0, 0, 0, 0}
};

struct mi_root* mi_shvar_set(struct mi_root* cmd_tree, void* param)
{
	str sp;
	str name;
	int ival;
	int_str isv;
	int flags;
	struct mi_node* node;
	sh_var_t *shv = NULL;

	node = cmd_tree->node.kids;
	if(node == NULL)
		return init_mi_tree( 400, MI_SSTR(MI_MISSING_PARM_S));
	name = node->value;
	if(name.len<=0 || name.s==NULL)
	{
		LM_ERR("bad shv name\n");
		return init_mi_tree( 500, MI_SSTR("bad shv name"));
	}
	shv = get_shvar_by_name(&name);
	if(shv==NULL)
		return init_mi_tree(404, MI_SSTR("Not found"));

	node = node->next;
	if(node == NULL)
		return init_mi_tree(400, MI_SSTR(MI_MISSING_PARM_S));
	sp = node->value;
	if(sp.s == NULL)
		return init_mi_tree(500, MI_SSTR("type not found"));
	flags = 0;
	if(sp.s[0]=='s' || sp.s[0]=='S')
		flags = VAR_VAL_STR;

	node= node->next;
	if(node == NULL)
		return init_mi_tree(400, MI_SSTR(MI_MISSING_PARM_S));

	sp = node->value;
	if(sp.s == NULL)
	{
		return init_mi_tree(500, MI_SSTR("value not found"));
	}
	if(flags == 0)
	{
		if(str2sint(&sp, &ival))
		{
			LM_ERR("bad integer value\n");
			return init_mi_tree( 500, MI_SSTR("bad integer value"));
		}
		isv.n = ival;
	} else {
		isv.s = sp;
	}

	lock_shvar(shv);
	if(set_shvar_value(shv, &isv, flags)==NULL)
	{
		unlock_shvar(shv);
		LM_ERR("cannot set shv value\n");
		return init_mi_tree( 500, MI_SSTR("cannot set shv value"));
	}

	unlock_shvar(shv);
	LM_DBG("$shv(%.*s) updated\n", name.len, name.s);
	return init_mi_tree( 200, MI_OK_S, MI_OK_LEN);
}

...
			

...

static proc_export_t procs[] = {
	{"XMPP receiver",  0,  0, xmpp_process, 1 },
	{0,0,0,0,0}
};
...
static void xmpp_process(int rank)
{
	/* if this blasted server had a decent I/O loop, we'd
	 * just add our socket to it and connect().
	 */
	close(pipe_fds[1]);

	LM_DBG("started child connection process\n");
	if (!strcmp(backend, "component"))
		xmpp_component_child_process(pipe_fds[0]);
	else if (!strcmp(backend, "server"))
		xmpp_server_child_process(pipe_fds[0]);
}
...
/**
 * initialize module
 */
static int mod_init(void) {
	...
	/* add space for one extra process */
	register_procs(1);
	...
}
...
/**
 * initialize child processes
 */
static int child_init(int rank)
{
	int pid;

	if (rank==PROC_MAIN) {
		pid=fork_process(PROC_NOCHLDINIT, "XMPP Manager", 1);
		if (pid<0)
			return -1; /* error */
		if(pid==0){
			/* child */
			/* initialize the config framework */
			if (cfg_child_init())
				return -1;

			xmpp_process(1);
		}
	}

	return 0;
}

...
			

...
struct module_exports exports = {
	"cfgutils",
	DEFAULT_DLFLAGS, /* dlopen flags */
	cmds,        /* exported functions */
	params,      /* exported parameters */
	0,           /* exported statistics */
	mi_cmds,     /* exported MI functions */
	mod_items,   /* exported pseudo-variables */
	0,           /* extra processes */
	mod_init,    /* module initialization function */
	0,           /* response function*/
	mod_destroy, /* destroy function */
	0            /* per-child init function */
};
...
			

Between version 1.5 and 3.0, there were major refactorings inside the code, as part Kamailio and SER source code integration, several of them affecting the existing modules. If you had some internally developed modules, in this chapter you can find the hints that should make the upgrade easier.

Three changes affected the old Kamailio modules:

Since you developed the module for Kamailio v1.x, it is clear you have implemented the Kamailio-specific module interface. What you need to do: edit module Makefile and add -DOPENSER_MOD_INTERFACE to DEFS variable:

...
DEFS+=-DOPENSER_MOD_INTERFACE
...
			

Some examples of code that was during the past in core and now is part of internal libraries:

To get your module compiling, you have to update the paths to include directives. Internal libraries are located in directories inside lib/. For example, what was in v1.x as:

...
#include "../../db/db.h"
...
			

is in v3.x:

...
#include "../../lib/srdb1/db.h"
...
			

You may need also to update the names of data structures and types, or API functions.

In the Makefile, you have to list the interal library dependencies. For example, a module that connects to database and exports MI commands has in Makefile:

...
SERLIBPATH=../../lib
SER_LIBS+=$(SERLIBPATH)/srdb1/srdb1
SER_LIBS+=$(SERLIBPATH)/srdb1/kmi
SER_LIBS+=$(SERLIBPATH)/kcore/kcore

...
			

Internal kcore library collects code from old v1.x that didn't meet the requirements of the new architecture for the core v3.x. It also includes the code for statistics API - it most of the cases, you may need to link old Kamailio modules to it.

Regarding the passive fields in the module exports, practically they are:

To get them registered to the core framework, you have to use now dedicated functions in mod_init() and child_init(). See the specific chapters in this guide that approach these topics for real examples of how to do it for each one.

The library has to be added as a sub-directory of lib/ folder. For example the trie library is located in lib/trie/.

When adding a new internal library, simply create a folder for it and place the Makefile, source code and header files inside it.

The Makefile for internal library specify name, version and external dependencies for it.

...
include ../../Makefile.defs
auto_gen=
NAME:=trie
MAJOR_VER=1
MINOR_VER=0
BUGFIX_VER=0
LIBS=

include ../../Makefile.libs
...
		

The above example is from trie library, which will result on Linux in an object file libtrie.1.0.0.so.

Other Makefile variables such as DEFS or SER_LIBS can be used for libraries in the same manner as for modules. For example, an internal library can depend on another internal library - simply add the dependency to SER_LIBS variable.

The source code and headers have to be placed in files inside library's directory. There is no real restriction of what you can have inside, besides valid C code. however, it is recommended to use a naming pattern for C functions and global variables that will reduce the risk of naming conflicts.

A good practice is to declare only static global variables and export functions that give access (read/write) to them. Exported functions (non-static functions) should be prefixed by a token that tries to suggest the library and build an unique name. If you look inside trie library, the lib/tree/dtree.c file, all the functions are prefixed with dtree_.

To use a library, include the files with the prototypes of the functions that you need in your module and then use them where you need. In the Makefile of the module, you have to add the dependency on the respective library by setting accordingly the variable SER_LIBS. See Module Development section for more details on this topic.