1.8.1. Lexical Analysis

Lexical analysis is process of converting the input (the configuration file in this case) into a stream of tokens. A token is a set of characters that 'belong' together. A program that can turn the input into stream of tokens is called scanner. For example, when scanner encounters a number in the config file, it will produce token NUMBER.

There is no need to implement the scanner from scratch, it can be done automatically. There is a utility called flex. Flex accepts a configuration file and generates scanner according to the configuration file. The configuration file for flex consists of several lines - each line describing one token. The tokens are described using regular expressions. For more details, see flex manual page or info documentation.

Flex input file for the SER config file is in file cfg.lex. The file is processed by flex when the server is being compiled and the result is written in file lex.yy.c. The output file contains the scanner implemented in the C language.

1.8.2. Syntactical Analysis

The second stage of configuration file processing is called syntactical analysis. Purpose of syntactical analysis is to check if the configuration file has been well formed, doesn't contain syntactical errors and perform various actions at various stages of the analysis. Program performing syntactical analysis is called parser.

Structure of the configuration file is described using grammar. Grammar is a set of rules describing valid 'order' or 'combination' of tokens. If the file isn't conformable with it's grammar, it is syntactically invalid and cannot be further processed. In that case an error will be issued and the server will be aborted.

There is a utility called yacc. Input of the utility is a file containing the grammar of the configuration file, in addition to the grammar, you can describe what action the parser should do at various stages of parsing. For example, you can instruct the parser to create a structure describing an IP address every time it finds an IP address in the configuration file and convert the address to its binary representation.

For more information see yacc documentation.

yacc creates the parser when the server is being compiled from the sources. Input file for yacc is cfg.y. The file contains grammar of the config file along with actions that create the binary representation of the file. Yacc will write its result into file cfg.tab.c. The file contains function yyparse which will parse the whole configuration file and construct the binary representation. For more information about the bison input file syntax see bison documentation.

1.8.3. Config File Structure

The configuration file consist of three sections, each of the sections will be described separately.

• Route Statement - The statement describes how incoming requests will be processed. When a request is received, commands in one or more "route" sections will be executed step by step. The config file must always contain one main "route" statement and may contain several additional "route" statements. Request processing always starts at the beginning of the main "route" statement. Additional "route" statements can be called from the main one or another additional "route" statements (It it similar to function calling).

• Assign Statement - There are many configuration variables across the server and this statement makes it possible to change their value. Generally it is a list of assignments, each assignment on a separate line.

• Module Statement - Additional functionality of the server is available through separate modules. Each module is a shared object that can be loaded at runtime. Modules can export functions, that can be called from the configuration file and variables, that can be configured from the config file. The module statement makes it possible to load modules and configure them. There are two commands in the statement - loadmodule and modparam. The first can load a module. The second one can configure module's internal variables.

In the following sections we will describe in detail how the three sections are being processed upon server startup.

route_stm = "route" "{" actions "}"  
{ 
    $$ = push($3, &rlist[DEFAULT_RT]); 
}
			
actions = actions action { $$ = append_action($1, $2}; }
	| action { $$ = $1; }

action = cmd SEMICOLON { $$ = $1; }
       | SEMICOLON { $$ = 0; }

cmd = "forward" "(" host ")" { $$ = mk_action(FORWARD_T, STRING_ST, NUMBER_ST, $3, 0)
    | ...

assign_stm = "children" '=' NUMBER { children_no=$3; }
	   | "children" '=' error  { yyerror("number expected"); } 
...

module_stm = "loadmodule" STRING 
{ 
    DBG("loading module %s\n", $2);
    if (load_module($2)!=0) {
        yyerror("failed to load module");
    }
}
	   | "loadmodule" error	 { yyerror("string expected");  }
	   | "modparam" "(" STRING "," STRING "," STRING ")" 
			{
			    if (set_mod_param($3, $5, STR_PARAM, $7) != 0) {
			        yyerror("Can't set module parameter");
			    }
			}
	   | "modparam" "(" STRING "," STRING "," NUMBER ")" 
			{
			    if (set_mod_param($3, $5, INT_PARAM, (void*)$7) != 0) {
			        yyerror("Can't set module parameter");
			    }
			}
	   | MODPARAM error { yyerror("Invalid arguments"); }

1.15.1. dont_fork variable is set (not zero)

If dont_fork variable is set, the server will be operating in special mode. There will be only one process processing incoming requests. This is very slow and was intended mainly for debugging purposes. The main process will be processing all incoming requests itself.

The server still needs additional children:

• One child is for the timer subsystem, the child will be processing timers independently of the main process.

• FIFO server will spawn another child if enabled. The child will be processing all commands coming through the fifo interface.

• If SNMP support was enabled, another child will be created.

The following initialization will be performed in dont fork mode. (look into function main_loop in file main.c.

• Another child will be forked for the timer subsystem.

• Initialize the FIFO server if enabled, this will fork another child. For more info about the FIFO server, see section The FIFO server.

• Call init_child(0). The function performs per-child specific initialization of all loaded modules. A module can be initialized though mod_init function. The function is called BEFORE the server forks and thus is common for all children.

  If there is anything, that needs to be initialized in every child separately (for example if each child needs to open its own file descriptor), it cannot be done in mod_init. To make such initialization possible, a module can export another initialization function called init_child. The function will be called in all children AFTER fork of the server.

  And since we are in "dont fork" mode and there will no children processing requests (remember the main process will be processing all requests), the init_child wouldn't be called.

  That would be bad, because child_init might do some initialization that must be done otherwise modules might not work properly.

  To make sure that module initialization is complete we will call init_child here for the main process even if we are not going to fork.

That's it. Everything has been initialized properly and as the last step we will call udp_rcv_loop which is the main loop function. The function will be described later.

1.15.2. dont_fork is not set (zero)

dont_fork is not set. That means that the server will fork children and the children will be processing incoming requests. How many children will be created depends on the configuration (children variable). The main process will be sleeping and handling signals only.

The main process will then initialize the FIFO server. The FIFO server needs another child to handle communication over FIFO and thus another child will be created. The FIFO server will be described in more detail later.

Then the main process will perform another fork for the timer attendant. The child will take care of timer lists and execute specified function when a timer hits.

The main process is now completely initialized, it will sleep in pause function until a signal comes and call handle_sigs when such condition occurs.

The following initialization will be performed by each child separately:

Each child executes init_child function. The function will sequentially call child_init functions of all loaded modules.

Because the function is called in each child separately, it can initialize per-child specific data. For example if a module needs to communicate with database, it must open a database connection. If the connection would be opened in mod_init function, all the children would share the same connection and locking would be necessary to avoid conflicts. On the other hand if the connection was opened in child_init function, each child will have its own connection and concurrency conflicts will be handled by the database server.

And last, but not least, each child executes udp_rcv_loop function which contains the main loop logic.

6.2.1. The First Line Parser

Purpose of the parser is to parse the first line of a SIP message. The first line is represented by msg_start structure define in file parse_fline.h under parser subdirectory.

The main function of the first line parser is parse_first_line, the function will fill in msg_start structure.

Follow inline comments in the function if you want to add support for a new message type.

6.2.2. The Header Field Name Parser

The purpose of the header field type parser is to recognize type of a header field. The following types of header field will be recognized:

Via, To, From, CSeq, Call-ID, Contact, Max-Forwards, Route, Record-Route, Content-Type, Content-Length, Authorization, Expires, Proxy-Authorization, WWW-Authorization, supported, Require, Proxy-Require, Unsupported, Allow, Event.

All other header field types will be marked as HDR_OTHER.

Main function of header name parser is parse_hname2. The function can be found in file parse_hname.c. The function accepts pointers to begin and end of a header field and fills in hdf_field structure. name field will point to the header field name, body field will point to the header field body and type field will contain type of the header field if known and HDR_OTHER if unknown.

The parser is 32-bit, it means, that it processes 4 characters of header field name at time. 4 characters of a header field name are converted to an integer and the integer is then compared. This is much faster than comparing byte by byte. Because the server is compiled on at least 32-bit architectures, such comparison will be compiled into one instruction instead of 4 instructions.

We did some performance measurement and 32-bit parsing is about 3 times faster for a typical SIP message than corresponding automaton comparing byte by byte. Performance may vary depending on the message size, parsed header fields and header fields type. Test showed that it was always as fast as corresponding 1-byte comparing automaton.

Since comparison must be case insensitive in case of header field names, it is necessary to convert it to lower case first and then compare. Since converting byte by byte would slow down the parser a lot, we have implemented a hash table, that can again convert 4 bytes at once. Since set of keys that need to be converted to lowercase is known (the set consists of all possible 4-byte parts of all recognized header field names) we can precalculate size of the hash table to be synonym-less. That will simplify (and speed up) the lookup a lot. The hash table must be initialized upon the server startup (function init_hfname_parser).

The header name parser consists of several files, all of them are under parser subdirectory. Main file is parse_hname2.c - this files contains the parser itself and functions used to initialize and lookup the hash table. File keys.h contains automatically generated set of macros. Each macro is a group of 4 bytes converted to integer. The macros are used for comparison and the hash table initialization. For example, for Max-Forwards header field name, the following macros are defined in the file:

#define _max__ 0x2d78616d   /* "max-" */
#define _maX__ 0x2d58616d   /* "maX-" */
#define _mAx__ 0x2d78416d   /* "mAx-" */
#define _mAX__ 0x2d58416d   /* "mAX-" */
#define _Max__ 0x2d78614d   /* "Max-" */
#define _MaX__ 0x2d58614d   /* "MaX-" */
#define _MAx__ 0x2d78414d   /* "MAx-" */
#define _MAX__ 0x2d58414d   /* "MAX-" */

#define _forw_ 0x77726f66   /* "forw" */
#define _forW_ 0x57726f66   /* "forW" */
#define _foRw_ 0x77526f66   /* "foRw" */
#define _foRW_ 0x57526f66   /* "foRW" */
#define _fOrw_ 0x77724f66   /* "fOrw" */
#define _fOrW_ 0x57724f66   /* "fOrW" */
#define _fORw_ 0x77524f66   /* "fORw" */
#define _fORW_ 0x57524f66   /* "fORW" */
#define _Forw_ 0x77726f46   /* "Forw" */
#define _ForW_ 0x57726f46   /* "ForW" */
#define _FoRw_ 0x77526f46   /* "FoRw" */
#define _FoRW_ 0x57526f46   /* "FoRW" */
#define _FOrw_ 0x77724f46   /* "FOrw" */
#define _FOrW_ 0x57724f46   /* "FOrW" */
#define _FORw_ 0x77524f46   /* "FORw" */
#define _FORW_ 0x57524f46   /* "FORW" */

#define _ards_ 0x73647261   /* "ards" */
#define _ardS_ 0x53647261   /* "ardS" */
#define _arDs_ 0x73447261   /* "arDs" */
#define _arDS_ 0x53447261   /* "arDS" */
#define _aRds_ 0x73645261   /* "aRds" */
#define _aRdS_ 0x53645261   /* "aRdS" */
#define _aRDs_ 0x73445261   /* "aRDs" */
#define _aRDS_ 0x53445261   /* "aRDS" */
#define _Ards_ 0x73647241   /* "Ards" */
#define _ArdS_ 0x53647241   /* "ArdS" */
#define _ArDs_ 0x73447241   /* "ArDs" */
#define _ArDS_ 0x53447241   /* "ArDS" */
#define _ARds_ 0x73645241   /* "ARds" */
#define _ARdS_ 0x53645241   /* "ARdS" */
#define _ARDs_ 0x73445241   /* "ARDs" */
#define _ARDS_ 0x53445241   /* "ARDS" */

As you can see, Max-Forwards name was divided into three 4-byte chunks: Max-, Forw, ards. The file contains macros for every possible lower and upper case character combination of the chunks. Because the name (and therefore chunks) can contain colon (":"), minus or space and these characters are not allowed in macro name, they must be substituted. Colon is substituted by "1", minus is substituted by underscore ("_") and space is substituted by "2".

When initializing the hash table, all these macros will be used as keys to the hash table. One of each upper and lower case combinations will be used as value. Which one ?

There is a convention that each word of a header field name starts with a upper case character. For example, most of user agents will send "Max-Forwards", messages containing some other combination of upper and lower case characters (for example: "max-forwards", "MAX-FORWARDS", "mAX-fORWARDS") are very rare (but it is possible).

Considering the previous paragraph, we optimized the parser for the most common case. When all header fields have upper and lower case characters according to the convention, there is no need to do hash table lookups, which is another speed up.

For example suppose we are trying to figure out if the header field name is Max-Forwards and the header field name is formed according to the convention (i.e. "Max-Forwards"):

• Get the first 4 bytes of the header field name ("Max-"), convert it to an integer and compare to "_Max__" macro. Comparison succeeded, continue with the next step.

• Get next 4 bytes of the header field name ("Forw"), convert it to an integer and compare to "_Forw_" macro. Comparison succeeded, continue with the next step.

• Get next 4 bytes of the header field name ("ards"), convert it to an integer and compare to "_ards_" macro. Comparison succeeded, continue with the next step.

• If the following characters are spaces and tabs followed by a colon (or colon directly without spaces and tabs), we found Max-Forwards header field name and can set type field to HDR_MAXFORWARDS. Otherwise (other characters than colon, spaces and tabs) it is some other header field and set type field to HDR_OTHER.

As you can see, there is no need to do hash table lookups if the header field was formed according to the convention and the comparison was very fast (only 3 comparisons needed !).

Now lets consider another example, the header field was not formed according to the convention, for example "MAX-forwards":

• Get the first 4 bytes of the header field name ("MAX-"), convert it to an integer and compare to "_Max__" macro.

  Comparison failed, try to lookup "MAX-" converted to integer in the hash table. It was found, result is "Max-" converted to integer.

  Try to compare the result from the hash table to "_Max__" macro. Comparison succeeded, continue with the next step.

• Compare next 4 bytes of the header field name ("forw"), convert it to an integer and compare to "_Max__" macro.

  Comparison failed, try to lookup "forw" converted to integer in the hash table. It was found, result is "Forw" converted to integer.

  Try to compare the result from the hash table to "Forw" macro. Comparison succeeded, continue with the next step.

• Compare next 4 bytes of the header field name ("ards"), convert it to integer and compare to "ards" macro. Comparison succeeded, continue with the next step.

• If the following characters are spaces and tabs followed by a colon (or colon directly without spaces and tabs), we found Max-Forwards header field name and can set type field to HDR_MAXFORWARDS. Otherwise (other characters than colon, spaces and tabs) it is some other header field and set type field to HDR_OTHER.

In this example, we had to do 2 hash table lookups and 2 more comparisons. Even this variant is still very fast, because the hash table lookup is synonym-less, lookups are very fast.

6.2.3. The Header Field Body Parsers

struct to_param{
    int type;              /* Type of parameter */
    str name;              /* Name of parameter */
    str value;             /* Parameter value */
    struct to_param* next; /* Next parameter in the list */
};


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

struct cseq_body{
    int error;  /* Error code */
    str number; /* CSeq number */
    str method; /* Associated method */
};

---

6.2.3.4. Event HF Body Parser

Purpose of this parser is to parse body of an Event Header field. The parser can be found in file parse_event.c under parser subdirectory.

This is NOT fully featured Event body parser ! The parser was written for Presence Agent module only and thus can recognize Presence package only. No subpackages will be recognized. All other packages will be marked as "OTHER". The parser should be replace by a more generic parser if subpackages or parameters should be parsed too.

Main function is parse_event in file parse_event.c. The function will create an instance of event_t structure and call the parser. If everything went OK, pointer to the newly created structure will be stored in parsed field of hdr_field structure representing the parsed header field.

As usually, the newly created structure will be freed when the whole message is being destroyed. See function clean_hdr_field in file hf.c.

The parser will be not called automatically when the main parser finds an Event header field. It is up to you to call the parser when you really need the body of the header field to be parsed (call parse_event function).

---

6.2.3.4.1. Structure event_t

The structure represents parsed Event body. The structure is declared in parse_event.h file.

Structure Declaration:

#define EVENT_OTHER    0
#define EVENT_PRESENCE 1

typedef struct event {
    str text;   /* Original string representation */
    int parsed; /* Parsed variant */
} event_t;

Field Description:

• text - Package name as text.

• parsed - Package name as integer. It will be EVENT_PRESENCE for presence package and EVENT_OTHER for rest.

typedef struct exp_body {
    str text;   /* Original text representation */
    int val;    /* Parsed value */
} exp_body_t;

---

6.2.3.7. Contact HF Body Parser

The parser is located under parser/contact subdirectory. The parser is not called automatically when the main parser finds a Contact header field. It is your responsibility to call the parser if you want a Contact header field body to be parsed.

Main function is parse_contact in file parse_contact.c. The function accepts one parameter which is structure hdr_field representing the header field to be parsed. A single Contact header field may contain multiple contacts, the parser will parse all of them and will create linked list of all such contacts.

The function creates and initializes an instance of contact_body structure. Then function contact_parser will be called. If everything went OK, pointer to the newly created structure will be stored in parsed field of the hdr_field structure representing the parsed header field.

Function contact_parser will then check if the contact is star, if not it will call parse_contacts function that will parse all contacts of the header field.

Function parse_contacts can be found in file contact.c. It extracts URI and parses all contact parameters.

The Contact parameter parser can be found in file cparam.c.

The following structures will be created during parsing:

Mind that none of string in the following structures is zero terminated ! Be very careful when processing the strings with functions that require zero termination (printf for example) !

typedef struct contact_body {
    unsigned char star;    /* Star contact */
    contact_t* contacts;   /* List of contacts */
} contact_body_t;

This is the main structure. Pointer to instance of this structure will be stored in parsed field of structure representing the header field to be parsed. The structure contains two field:

• star field - This field will contain 1 if the Contact was star (see RFC3261 for more details).

• contacts field - This field contains pointer to linked list of all contacts found in the Contact header field.

typedef struct contact {
    str uri;              /* contact uri */
    cparam_t* q;          /* q parameter hook */
    cparam_t* expires;    /* expires parameter hook */
    cparam_t* method;     /* method parameter hook */
    cparam_t* params;     /* List of all parameters */
    struct contact* next; /* Next contact in the list */
} contact_t;

This structure represents one Contact (Mind that there might be several contacts in one Contact header field delimited by a comma). Its fields have the following meaning:

• uri - This field contains pointer to begin of URI and its length.

• q - This is a hook to structure representing q parameter. If there is no such parameter, the hook contains 0.

• expires - This is a hook to structure representing expires parameter. If there is no such parameter, the hook contains 0.

• method - This is a hook to structure representing method parameter. If there is no such parameter, the hook contains 0.

• params - Linked list of all parameters.

• next - Pointer to the next contact that was in the same header field.

typedef enum cptype {
    CP_OTHER = 0,  /* Unknown parameter */
    CP_Q,          /* Q parameter */
    CP_EXPIRES,    /* Expires parameter */
    CP_METHOD      /* Method parameter */
} cptype_t;

This is an enum of recognized types of contact parameters. Q parameter will have type set to CP_Q, Expires parameter will have type set to CP_EXPIRES and Method parameter will have type set to CP_METHOD. All other parameters will have type set to CP_OTHER.

/*
 * Structure representing a contact
 */
typedef struct cparam {
    cptype_t type;       /* Type of the parameter */
    str name;            /* Parameter name */
    str body;            /* Parameter body */
    struct cparam* next; /* Next parameter in the list */
} cparam_t;

This structure represents a contact parameter. Field description follows:

• type - Type of the parameter, see cptype enum for more details.

• name - Name of the parameter (i.e. the part before "=").

• body - Body of the parameter (i.e. the part after "=").

• next - Next parameter in the linked list.

---

6.2.3.8. Digest Body Parser

Purpose of this parser is to parse digest response. The parser can be found under parser/digest subdirectory. There might be several header fields containing digest response, for example Proxy-Authorization or WWW-Authorization. The parser can be used for all of them.

The parser is not called automatically when by the main parser. It is your responsibility to call the parser when you want a digest response to be parsed.

Main function is parse_credentials defined in digest.c. The function accepts one parameter which is header field to be parsed. As result the function will create an instance of auth_body_t structure which will represent the parsed digest credentials. Pointer to the structure will be put in parsed field of the hdr_field structure representing the parsed header field. It will be freed when the whole message is being destroyed.

The digest parser contains 32-bit digest parameter parser. The parser was in detail described in section Header Field Name Parser. See that section for more details about the digest parameter parser algorithm, they work in the same way.

Description of digest related structures follows:

			
typedef struct auth_body {
    /* This is pointer to header field containing
     * parsed authorized digest credentials. This
     * pointer is set in sip_msg->{authorization,proxy_auth}
     * hooks.
     *
     * This is necessary for functions called after
     * {www,proxy}_authorize, these functions need to know
     * which credentials are authorized and they will simply
     * look into 
     * sip_msg->{authorization,proxy_auth}->parsed->authorized
     */
    struct hdr_field* authorized;
    dig_cred_t digest;           /* Parsed digest credentials */
    unsigned char stale;         /* Flag is set if nonce is stale */
    int nonce_retries;           /* How many times the nonce was used */
} auth_body_t;

This is the "main" structure. Pointer to the structure will be stored in parsed field of hdr_field structure. Detailed description of its fields follows:

• authorized - This is a hook to header field containing authorized credentials.

  A SIP message may contain several credentials. They are distinguished using realm parameter. When the server is trying to authorize the message, it must first find credentials with corresponding realm and than authorize the credentials. To authorize credentials server calculates response string and if the string matches to response string contained in the credentials, credentials are authorized (in fact it means that the user specified in the credentials knows password, nothing more, nothing less).

  It would be good idea to remember which credentials contained in the message are authorized, there might be other functions interested in knowing which credentials are authorized.

  That is what is this field for. A function that successfully authorized credentials (currently there is only one such function in the server, it is function authorize in auth module) will put pointer to header field containing the authorized credentials in this field. Because there might be several header field containing credentials, the pointer will be put in authorized field in the first header field in the message containing credentials. That means that it will be either header field whose pointer is in www_auth or proxy_auth field of sip_msg structure representing the message.

  When a function wants to find authorized credentials, it will simply look in msg->www_auth->parsed->authorized or msg->proxy_auth->parsed->authorized, where msg is variable containing pointer to sip_msg structure.

  To simplify the task of saving and retrieving pointer to authorized credentials, there are two convenience functions defined in digest.c file. They will be described later.

• digest - Structure containing parsed digest credentials. The structure will be described in detail later.

• stale - This field will be set to 1 if the server received a stale nonce. Next time when the server will be sending another challenge, it will use "stale=true" parameter. "stale=true" indicates to the client that username and password used to calculate response were correct, but nonce was stale. The client should recalculate response with the same username and password (without disturbing user) and new nonce. For more details see RFC2617.

• nonce_retries - This fields indicates number of authorization attempts with same nonce.

/*
 * Errors returned by check_dig_cred
 */
typedef enum dig_err {
    E_DIG_OK = 0,        /* Everything is OK */
    E_DIG_USERNAME  = 1, /* Username missing */
    E_DIG_REALM = 2,     /* Realm missing */
    E_DIG_NONCE = 4,     /* Nonce value missing */
    E_DIG_URI = 8,       /* URI missing */
    E_DIG_RESPONSE = 16, /* Response missing */
    E_DIG_CNONCE = 32,   /* CNONCE missing */
    E_DIG_NC = 64,       /* Nonce-count missing */
} dig_err_t;			

This is enum of all possible errors returned by check_dig_cred function.

• E_DIG_OK - No error found.

• E_DIG_USERNAME - Username parameter missing in digest response.

• E_DIG_REALM - Realm parameter missing in digest response.

• E_DIG_NONCE - Nonce parameter missing in digest response.

• E_DIG_URI - Uri parameter missing in digest response.

• E_DIG_RESPONSE - Response parameter missing in digest response.

• E_DIG_CNONCE - Cnonce parameter missing in digest response.

• E_DIG_NC - Nc parameter missing in digest response.

/* Type of algorithm used */
typedef enum alg {
    ALG_UNSPEC = 0,   /* Algorithm parameter not specified */
    ALG_MD5 = 1,      /* MD5 - default value*/
    ALG_MD5SESS = 2,  /* MD5-Session */
    ALG_OTHER = 4     /* Unknown */
} alg_t;

This is enum of recognized algorithm types. (See description of algorithm structure for more details).

• ALG_UNSPEC - Algorithm was not specified in digest response.

• ALG_MD5 - "algorithm=MD5" was found in digest response.

• ALG_MD5SESS - "algorithm=MD5-Session" was found in digest response.

• ALG_OTHER - Unknown algorithm parameter value was found in digest response.

/* Quality Of Protection used */
typedef enum qop_type { 
    QOP_UNSPEC = 0,   /* QOP parameter not present in response */
    QOP_AUTH = 1,     /* Authentication only */
    QOP_AUTHINT = 2,  /* Authentication with integrity checks */
    QOP_OTHER = 4     /* Unknown */
} qop_type_t;

This enum lists all recognized qop parameter values.

• QOP_UNSPEC - qop parameter was not found in digest response.

• QOP_AUTH - "qop=auth" was found in digest response.

• QOP_AUTHINT - "qop=auth-int" was found in digest response.

• QOP_OTHER - Unknown qop parameter value was found in digest response.

/* Algorithm structure */
struct algorithm {
    str alg_str;       /* The original string representation */
    alg_t alg_parsed;  /* Parsed value */
};

The structure represents "algorithm" parameter of digest response. Description of fields follows:

• alg_str - Algorithm parameter value as string.

• alg_parsed - Parsed algorithm parameter value.

/* QOP structure */
struct qp {
    str qop_str;           /* The original string representation */
    qop_type_t qop_parsed; /* Parsed value */
};

This structure represents "qop" parameter of digest response. Description of fields follows:

• qop_str - Qop parameter value as string.

• qop_parsed - Parsed "qop" parameter value.

/*
 * Parsed digest credentials
 */
typedef struct dig_cred {
    str username;         /* Username */
    str realm;            /* Realm */
    str nonce;            /* Nonce value */
    str uri;              /* URI */
    str response;         /* Response string */
    str algorithm;        /* Algorithm in string representation */
    struct algorithm alg; /* Type of algorithm used */
    str cnonce;           /* Cnonce value */
    str opaque;           /* Opaque data string */
    struct qp qop;        /* Quality Of Protection */
    str nc;               /* Nonce count parameter */
} dig_cred_t;

This structure represents set of digest credentials parameters. Description of field follows:

• username - Value of "username" parameter.

• realm - Value of "realm" parameter.

• nonce - Value of "nonce" parameter.

• uri - Value of "uri" parameter.

• response - Value of "response" parameter.

• algorithm - Value of "algorithm" parameter as string.

• alg - Parsed value of "algorithm" parameter.

• cnonce - Value of "cnonce" parameter.

• opaque - Value of "opaque" parameter.

• qop - Value of "qop" parameter.

• nc - Value of "nc" parameter.

---

6.2.3.8.1. Other Functions Of the Digest Body Parser

There are some other mainly convenience functions defined in the parser. The function will be in detail described in this section. All the functions are defined in digest.c file.

dig_err_t check_dig_cred(dig_cred_t* _c);

This function performs some basic sanity check over parsed digest credentials. The following conditions must be met for the checks to be successful:

• There must be non-empty "username" parameter in the credentials.

• There must be non-empty "realm" parameter in the credentials.

• There must be non-empty "nonce" parameter in the credentials.

• There must be non-empty "uri" parameter in the credentials.

• There must be non-empty "response" parameter in the credentials.

• If qop parameter is set to QOP_AUTH or QOP_AUTHINT, then there must be also non-empty "cnonce" and "nc" parameters in the digest.

It is recommended to call check_dig_cred before you try to authorize the credentials. If the function fails, there is no need to try to authorize the credentials because the authorization will fail for sure.

int mark_authorized_cred(struct sip_msg* _m, struct hdr_field* _h);

This is convenience function. The function saves pointer to the authorized credentials. For more info see description of authorized field in auth_body structure.

int get_authorized_cred(struct sip_msg* _m, struct hdr_field** _h);

This is convenience function. The function will retrieve pointer to authorized credentials previously saved using mark_authorized_cred function. If there is no such credentials, 0 will be stored in variable pointed to by the second parameter. The function returns always zero. For more information see description of authorized field in auth_body structure.

7.4.1. Function modparam

modparam function accepts three parameters:

• module name - Name of module as exported in name field of exports global variable.

• variable name - Name of variable to be set - it must be one of names specified in param_names field of exports variable of the module.

• value - New value of the variable. There are two types of variables: string and integer. If the last parameter (value) of modparam function is enclosed in quotes, it is string parameter and server will try to find the corresponding variable among string parameters only.

  Otherwise it is integer parameter and server will try to find corresponding variable among integer parameters only.

7.4.2. Function set_mod_param

When the server finds modparam function in the config file, it will call set_mod_param function. The function can be found in modparam.c file. The function will do the following:

• It tries to find corresponding variable using find_param_export function.

• If it is string parameter, a new copy of the string will be obtained using strdup function and pointer to the copy will be stored in the variable.

  If it is integer parameter, its value will be simply copied in the variable.

7.4.3. Function find_param_export

This function accepts 3 parameters:

• module - Name of module.

• parameter - Name of parameter to be found.

• type - Type of the parameter.

The function will search list of all modules until it finds module with given name. Then it will search through all module's exported parameters until it finds parameter with corresponding name and type. If such parameter was found, pointer to variable holding the parameter's value will be returned. If the function failed to find either module or parameter with given name and type then zero will be returned.

8.1.1. Type db_con_t

This type represents a database connection, all database functions (described below) use a variable of this type as one argument. In other words, variable of db_con_t type serves as a handle for a particular database connection.

typedef struct db_con {
    char* table;     /* Default table to use */
    void* con;       /* Database connection */
    void* res;       /* Result of previous operation */
    void* row;       /* Internal, not for public use */
    int connected;   /* 1 if connection is established */
} db_con_t;

There are no macros defined for db_con_t type.

8.1.2. Type db_key_t

This type represents a database key. Every time you need to specify a key value, this type should be used. In fact, this type is identical to const char*.

		    typedef const char* db_key_t;
		

There are no macros defined (they are not needed).

8.1.3. Type db_type_t

Each cell in a database table can be of a different type. To distinguish among these types, the db_type_t enumeration is used. Every value of the enumeration represents one datatype that is recognized by the database API. This enumeration is used in conjunction with db_type_t. For more information, see the next section.

typedef enum {
    DB_INT,       /* Integer number */
    DB_DOUBLE,    /* Decimal number */
    DB_STRING,    /* String */
    DB_STR,       /* str structure */
    DB_DATETIME   /* Date and time */
    DB_BLOB       /* Binary large object */
} db_type_t;

There are no macros defined.

8.1.4. Type db_val_t

This structure represents a value in the database. Several datatypes are recognized and converted by the database API:

• DB_INT - Value in the database represents an integer number.

• DB_DOUBLE - Value in the database represents a decimal number.

• DB_STRING - Value in the database represents a string.

• DB_STR - Value in the database represents a string.

• DB_DATETIME - Value in the database represents date and time.

• DB_BLOB - Value in the database represents binary large object.

typedef struct db_val {
    db_type_t type;              /* Type of the value */
    int nul;                     /* NULL flag */
    union {                      
        int int_val;             /* Integer value */
        double double_val;       /* Double value */
        time_t time_val;         /* Unix time_t value */
        const char* string_val;  /* Zero terminated string */
        str str_val;             /* str structure */
        str blob_val;            /* Structure describing blob */
    } val;
} db_val_t;

All macros expect pinter to db_val_t variable as a parameter.

• VAL_TYPE(value) Macro.

  Use this macro if you need to set/get the type of the value

  Example 8-1. VAL_TYPE Macro

  ...
  VAL_TYPE(val) = DB_INT;
  if (VAL_TYPE(val) == DB_FLOAT)
  ...

• VAL_NULL(value) Macro.

  Use this macro if you need to set/get the null flag. Non-zero flag means that the corresponding cell in the database contained no data (NULL value in MySQL terminology).

  Example 8-2. VAL_NULL Macro

  ...
  if (VAL_NULL(val) == 1) {
      printf("The cell is NULL");
  }
  ...

• VAL_INT(value) Macro.

  Use this macro if you need to access integer value in db_val_t structure.

  Example 8-3. VAL_INT Macro

  ...
  if (VAL_TYPE(val) == DB_INT) {
      printf("%d", VAL_INT(val));
  }
  ...

• VAL_DOUBLE(value) Macro.

  Use this macro if you need to access double value in the db_val_t structure.

  Example 8-4. VAL_DOUBLE Macro

  ...
  if (VAL_TYPE(val) == DB_DOUBLE) {
      printf("%f", VAL_DOUBLE(val));
  }
  ...

• VAL_TIME(value) Macro.

  Use this macro if you need to access time_t value in db_val_t structure.

  Example 8-5. VAL_TIME Macro

  ...
  time_t tim;
  if (VAL_TYPE(val) == DB_DATETIME) {
      tim = VAL_TIME(val);
  }
  ...

• VAL_STRING(value) Macro.

  Use this macro if you need to access string value in db_val_t structure.

  Example 8-6. VAL_STRING Macro

  ...
  if (VAL_TYPE(val) == DB_STRING) {
      printf("%s", VAL_STRING(val));
  }
  ...

• VAL_STR(value) Macro.

  Use this macro if you need to access str structure in db_val_t structure.

  Example 8-7. VAL_STR Macro

  ...
  if (VAL_TYPE(val) == DB_STR) {
      printf("%.*s", VAL_STR(val).len, VAL_STR(val).s);
  }
  ...

• VAL_BLOB(value) Macro.

  Use this macro if you need to access blob value in db_val_t structure.

  Example 8-8. VAL_STR Macro

  ...
  if (VAL_TYPE(val) == DB_BLOB) {
      printf("%.*s", VAL_BLOB(val).len, VAL_BLOB(val).s);
  }
  ...

8.1.5. Type db_row_t

This type represents one row in a database table. In other words, the row is an array of db_val_t variables, where each db_val_t variable represents exactly one cell in the table.

typedef struct db_row {
    db_val_t* values;    /* Array of values in the row */
    int n;               /* Number of values in the row */
} db_val_t;

• ROW_VALUES(row) Macro.

  Use this macro to get pointer to array of db_val_t structures.

  Example 8-9. ROW_VALUES Macro

  ...
  db_val_t* v = ROW_VALUES(row);
  if (VAL_TYPE(v) == DB_INT)
  ...

• ROW_N(row) Macro.

  Use this macro to get number of cells in a row.

  Example 8-10. ROW_N Macro

  ...
  db_val_t* val = ROW_VALUES(row);
  for(i = 0; i < ROW_N(row); i++) {
      switch(VAL_TYPE(val + i)) {
          case DB_INT: ...; break;
          case DB_DOUBLE: ...; break;
          ...
      }
  }
  ...

8.1.6. Type db_res_t

This type represents a result returned by db_query function (see below). The result can consist of zero or more rows (see db_row_t description).

A variable of type db_res_t returned by db_query function uses dynamically allocated memory, don't forget to call db_free_query if you don't need the variable anymore. You will encounter memory leaks if you fail to do this !

In addition to zero or more rows, each db_res_t object contains also an array of db_key_t objects. The objects represent keys (names of columns).

typedef struct db_res {
    struct {
        db_key_t* keys;    /* Array of column names */
        db_type_t* types;  /* Array of column types */
        int n;             /* Number of columns */
    } col;
    struct db_row* rows;   /* Array of rows */
    int n;                 /* Number of rows */
} db_res_t;

• RES_NAMES(res) Macro.

  Use this macro if you want to obtain pointer to an array of cell names.

  Example 8-11. RES_NAMES Macro

  ...
  db_key_t* column_names = ROW_NAMES(row);
  ...

• RES_COL_N(res) Macro.

  Use this macro if you want to get the number of columns in the result.

  Example 8-12. RES_COL_N Macro

  ...
  int ncol = RES_COL_N(res);
  for(i = 0; i < ncol; i++) {
      /* do something with the column */
  }
  ...

• RES_ROWS(res) Macro.

  Use this macro if you need to obtain pointer to array of rows.

  Example 8-13. RES_ROWS Macro

  ...
  db_row_t* rows = RES_ROWS(res);
  ...

• RES_ROW_N(res) Macro.

  Use this macro if you need to obtain the number of rows in the result.

  Example 8-14. RES_ROW_N Macro

  ...
  int n = RES_ROW_N(res);
  ...

8.2.1. bind_dbmod

This function is special, it's only purpose is to call find_export function in the SER core and find addresses of all other functions (starting with db_ prefix). This function MUST be called FIRST !

The function takes no parameters.

The function returns 0 if it was able to find addresses of all other functions, otherwise value < 0 is returned.

8.2.2. db_init

Use this function to initialize the database API and open a new database connection. This function must be called after bind_dbmod but before any other function is called.

The function takes one parameter, the parameter must contain database connection URL. The URL is of the form sql://username:password@host:port/database where:

• username - Username to use when logging into database (optional).

• password - Password if it was set (optional).

• host - Hostname or IP address of the host where database server lives (mandatory).

• port - Port number of the server if the port differs from default value (optional).

• database - If the database server supports multiple databases, you must specify name of the database (optional).

The function returns pointer to db_con_t* representing the connection if it was successful, otherwise 0 is returned.

8.2.3. db_close

The function closes previously open connection and frees all previously allocated memory. The function db_close must be the very last function called.

The function takes one parameter, this parameter is a pointer to db_con_t structure representing database connection that should be closed.

Function doesn't return anything.

8.2.4. db_query

This function implements SELECT SQL directive.

The function takes 8 parameters:

• _h - Database connection handle.

• _k - Array of column names that will be compared and their values must match.

• _v - Array of values, columns specified in _k parameter must match these values.

• _c - Array of column names that you are interested in.

• _n - Number of key-value pairs to match in _k and _v parameters.

• _nc - Number of columns in _c parameter.

• _o - Order by.

• _r - Address of variable where pointer to the result will be stored.

_r will point to a dynamically allocated structure, it is necessary to call db_free_query function once you are finished with the result.

Strings in the result are not duplicated, they will be discarded if you call db_free_query, make a copy yourself if you need to keep it after db_free_query.

You must call db_free_query BEFORE you can call db_query again !

The function returns 0 if everything is OK, otherwise value < 0 is returned.

8.2.5. db_free_query

This function frees all memory allocated previously in db_query, it is necessary to call this function for a db_res_t structure if you don't need the structure anymore. You must call this function BEFORE you call db_query again !

The function takes 2 parameters:

• _h - Database connection handle.

• _r - Pointer to db_res_t structure to destroy.

The function returns 0 if everything is OK, otherwise the function returns value < 0.

8.2.6. db_insert

This function implements INSERT SQL directive, you can insert one or more rows in a table using this function.

The function takes 4 parameters:

• _h - Database connection handle.

• _k - Array of keys (column names).

• _v - Array of values for keys specified in _k parameter.

• _n - Number of keys-value pairs int _k and _v parameters.

The function returns 0 if everything is OK, otherwise the function returns value < 0.

8.2.7. db_delete

This function implements DELETE SQL directive, it is possible to delete one or more rows from a table.

The function takes 4 parameters:

• _h - Database connection handle.

• _k - Array of keys (column names) that will be matched.

• _v - Array of values that the row must match to be deleted.

• _n - Number of keys-value parameters in _k and _v parameters.

The function returns 0 if everything is OK, otherwise the function returns value < 0.

8.2.8. db_update

The function implements UPDATE SQL directive. It is possible to modify one or more rows in a table using this function.

The function takes 7 parameters:

• _h - Database connection handle.

• _k - Array of keys (column names) that will be matched.

• _v - Array of values that the row must match to be modified.

• _uk - Array of keys (column names) that will be modified.

• _uv - New values for keys specified in _k parameter.

• _n - Number of key-value pairs in _k and _v parameters.

• _un - Number of key-value pairs in _uk and _uv parameters.

The function returns 0 if everything is OK, otherwise the function returns value < 0.

8.2.9. db_use_table

The function db_use_table takes a table name and stores it in db_con_t structure. All subsequent operations (insert, delete, update, query) are performed on that table.

The function takes 2 parameters:

• _h - Database connection handle.

• _t - Table name.

The function returns 0 if everything is OK, otherwise the function returns value < 0.

9.1.1. Exported Parameters

• db_url - Database url string in form "sql://<user>:<pass>@host/database".

  Type: string

  Default: "sql://serro:47serro11@localhost/ser"

• user_column - Name of column containing usernames in subscriber table.

  Type: string

  Default: "user"

• realm_column - Name of column containing realm in subscriber table.

  Type: string

  Default: "realm"

• password_column - Name of column containing (plaintext passwords)/(ha1 strings) if calculate_ha1 parameter is set to true/false.

  Type: string

  Default: "ha1"

• password_column_2 - The parameter can be used if and only if USER_DOMAIN_HACK macro is set in defs.h header file. The column of this name contains alternate ha1 strings calculated from username containing also domain, for example username="jan@iptel.org". This hack is necessary for some broken user agents. The parameter has no meaning if "calculate_ha1" is set to true.

  Type: string

  Default: "ha1b"

• secret - Nonce secret phrase.

  Type: string

  Default: Randomly generated string.

• group_table - Name of table containing group definitions.

  Type: string

  Default: "grp"

• group_user_column - Name of column containing usernames in group table.

  Type: string

  Default: "user"

• group_group_column - Name of column containing groups in group table.

  Type: string

  Default: "grp"

• calculate_ha1 - If set to true, auth module assumes that "password_column" contains plaintext passwords and ha1 string will be calculated at runtime. If set to false, "password_column" must contain precalculated ha1 strings.

  Type: integer

  Default: false

• nonce_expire - Every nonce is valid only for a limited amount of time. This parameter specifies nonce validity interval in seconds.

  Type: integer

  Default: 300

• retry_count - This parameter specifies how many times a user is allowed to retry authentication with incorrect credentials. After that the user will receive 403 Forbidden and must retry with different credentials. This should prevent DoS attacks from misconfigured user agents which try to authenticate with incorrect password again and again and again.

  Type: integer

  Default: 5

9.1.2. Exported Functions

• int www_authorize(struct sip_msg* msg, char* realm, char* table);

  The function checks credentials in Authorization header field.

  realm - Realm string

  table - Subscriber table name

  Example 9-1. www_authorize

  if (!www_authorize( "iptel.org", "subscriber" )) {
      www_challenge(  "iptel.org", "0"); 
      break; 
  }

• int proxy_authorize(struct sip_msg* msg, char* realm, char* table);

  The function checks credentials in Proxy-Authorization header field.

  realm - Realm string

  table - Subscriber table name

  Example 9-2. proxy_authorize

  if (!proxy_authorize( "iptel.org", "subscriber" )) {
      proxy_challenge(  "iptel.org", "0"); 
      break; 
  }

• int www_challenge(struct sip_msg* msg, char* realm, char* qop);

  Challenges a user agent using WWW-Authenticate header field. The second parameter specifies if qop parameter (according to rfc2617) should be used or not. (Turning off is useful primarily to make UAC happy, which have a broken qop implementation, particularly M$ Messenger 4.6).

  realm - Realm string

  qop - Qop string, "1" means use qop parameter "0" means do not use qop parameter.

• int proxy_challenge(struct sip_msg* msg, char* realm, char* qop);

  Challenges a user agent using Proxy-Authenticate header field. The second parameter specifies if qop parameter (according to rfc2617) should be used or not. (Turning off is useful primarily to make UAC happy, which have a broken qop implementation, particularly M$ Messenger 4.6).

  realm - Realm string

  qop - Qop string, "1" means use qop parameter "0" means do not use qop parameter.

• int is_user(struct sip_msg* msg, char* username, char* s);

  Checks if the specified username and matches the username in credentials. Call after *_authorize, otherwise an error will be issued.

  username - Username string.

  s - Not used.

• int is_in_group(struct sip_msg* msg, char* group, char* s);

  Checks if the user specified in credentials is member of given group Call after *_authorize, otherwise an error will be issued.

  group - Group name.

  s - Not used.

• int check_to(struct sip_msg* msg, char* s1, char* s2);

  Checks if the username given in credentials and username in To header field are equal Call after *_authorize, otherwise an error will be issued.

  s1 - Not used.

  s2 - Not used.

  Example 9-3. check_to

  if (method=="REGISTER" & proxy_authorize("iptel.org", "subscriber" ) {
      if (!check_to) { 
          sl_send_reply("403", "cheating: user!=to");
          break;
      }
  }

• int check_from(struct sip_msg* msg, char* s1, char* s2);

  Checks if the username given in credentials and username in From header field are equal. Call after *_authorize, otherwise an error will be issued.

  s1 - Not used.

  s2 - Not used.

• int consume_credentials(struct sip_msg* msg, char* s1, char* s2);

  Removes previously authorized credentials from the message. The function must be called after {www,proxy}_authorize.

  s1 - Not used.

  s2 - Not used.

• int is_user_in(struct sip_msg* msg, char* hf, char* group);

  Checks, if the user is in specified table.

  hf - Use username in this header field, the following values are recognized:

  • "From" - Extract username from From URI.

  • "To" - Extract username from To URI.

  • "Request-URI" - Extract username from Request-URI.

  • "credentials" - Use username digest parameter.

  group - Group name.

9.2.1. Exported Parameters

None.

9.2.2. Exported Functions

If no Max-Forwards header is present in the received request, a header will be added having the original value equal with "max_value". An OK code is returned by the function.

If a Max-Forwards header is already present, its value will be decremented. If after this operation its value will be positive non-zero, an OK code will be returned. Otherwise (for a zero value) an error code will be returned. Note that an error code will be also returned if the SIP message couldn't be parsed or if the Max-Forwards header's body invalid (non numerical string or negative numerical value)

Parameter s is not used.

9.3.1. Exported Parameters

• default_expires - If the processed message contains neither Expires HFs nor expires contact parameters, this value will be used for newly created usrloc records. The parameter contains number of second to expire (for example use 3600 for one hour).

  Type: integer

  Default: 3600

• default_q - The parameter represents default q value for new contacts. Because ser doesn't support float parameter types, the value in the parameter is divided by 100 and stored as float. For example, if you want default_q to be 0.38, use value 38 here.

  Type: integer

  Default: 0

• append_branches - The parameter controls how lookup function processes multiple contacts. If there are multiple contacts for the given username in usrloc and this parameter is set to 1, Request-URI will be overwritten with the highest-q rated contact and the rest will be appended to sip_msg structure and can be later used by tm for forking. If the parameter is set to 0, only Request-URI will be overwritten with the highest-q rated contact and the rest will be left unprocessed.

  Type: integer

  Default: 1

9.3.2. Exported Functions

• int save(struct sip_msg* msg, char* table, char* s);

  The function processes a REGISTER message. It can add, remove or modify usrloc records depending on Contact and Expires HFs in the REGISTER message. On success, 200 OK will be returned listing all contacts that are currently in usrloc. On an error, error message will be send with a short description in reason phrase.

  table - Table name where contacts should be stored.

  s - Not used.

• int lookup(struct sip_msg* msg, char* table, char* s);

  The functions extracts username from Request-URI and tries to find all contacts for the username in usrloc. If there are no such contacts, -1 will be returned. If there are such contacts, Request-URI will be overwritten with the contact that has the highest q value and optionally the rest will be appended to the message (depending on append_branches parameter value).

  table - Name of table that should be used for the lookup.

  s - Not used.

9.4.1. Exported Parameters

None.

9.4.2. Exported Functions

• int rewriteFromRoute(struct sip_msg* msg, char* s1, char* s2);

  If there are any Route HFs in the message, the function takes the first one, rewrites Request-URI with it's value and removes the first URI from Route HFs.

  s1 - Not used.

  s2 - Not used.

• int addRecordRoute(struct sip_msg* msg, char* s1, char* s2);

  The function adds a new Record-Route header field. The header field will be inserted in the message before any other Record-Route header fields.

  s1 - Not used.

  s2 - Not used.

9.5.1. Exported Parameters

None.

9.5.2. Exported Functions

• int sl_send_reply(struct sip_msg* msg, char* code, char* text_reason);

  For the current request, a reply is sent back having the given code and text reason. The reply is sent stateless, totally independent of the Transaction module and with no retransmission for the INVITE's replies.

  code - Reply code to be used.

  text_reason - Reason phrase to be used.

• int sl_filter_ACK(struct sip_msg* msg, char* s1, char* s2);

  Identifies and blocks the ACK requests generated by INVITE's replies sent using the sl_send_reply() or sl_send_error() functions.

  s1 - Not used.

  s2 - Not used.

• int sl_reply_error(struct sip_msg* msg, char* s1, char* s2);

  Identifies and blocks the ACK requests generated by INVITE's replies sent using the sl_send_reply() or sl_send_error() functions.

  s1 - Not used.

  s2 - Not used.

9.6.1. External Usage of TM

There are applications which would like to generate SIP transactions without too big involvement in SIP stack, transaction management, etc. An example of such an application is sending instant messages from a website. To address needs of such apps, SER accepts requests for new transactions via fifo pipes too. If you want to enable this feature, start FIFO server by configuration option fifo="/tmp/filename" Then, an application can easily launch a new transaction by writing a transaction request to this named pipe. The request must follow very simple format, which is

:t_uac:[<file_name>]\n
<method>\n
<dst uri>\n
<CR_separated_headers>\n
<body>\n
\n
\n

A convenience library fifo_uac.c implements this simple functionality. Note the the request write must be atomic, otherwise the request might get intermixes with writes from other writers. You can easily use it via Unix command-line tools, see the following example:

[jiri@bat jiri]$ cat > /tmp/fifo
:t_uac:xxx
MESSAGE
sip:mrx@iptel.org
header:value
foo:bar
bznk:hjhjk
p_header: p_value

body body body
yet body
end of body

9.6.2. Exported Parameters

• fr_timer - Timer which hits if no final reply for a request or ACK for a negative INVITE reply arrives.

  Type: integer (seconds)

  Default: 30

• fr_inv_timer - Timer which hits if no final reply for an INVITE arrives after a provisional message was received.

  Type: integer (seconds)

  Default: 120

• wt_timer - Time for which a transaction stays in memory to absorb delayed messages after it completed; also, when this timer hits, retransmission of local cancels is stopped (a puristic but complex behaviour would be not to enter wait state until local branches are finished by a final reply or FR timer -- we simplified)

  Type: integer (seconds)

  Default: 5

• delete_timer - Time after which a to-be-deleted transaction currently ref-ed by a process will be tried to be deleted again.

  Type: integer (seconds)

  Default: 2

• retr_timer1p1, 2, 3 - Retransmission period.

  Type: integer (seconds)

  Default: RETR_T1=1, 2*RETR_T1, 4*RETR_T1

• retr_timer2 - Maximum retransmission period.

  Type: integer (seconds)

  Default: RETR_T2=4

• noisy_ctimer - If set, on FR timer INVITE transactions will be explicitly cancelled if possible, silently dropped otherwise; preferably, it is turned off to allow very long ringing; this behaviour is overridden if a request is forked, or some functionality explicitly turned it off for a transaction (like acc does to avoid unaccounted transactions due to expired timer).

  Type: integer (boolean)

  Default: 0 (false)

9.6.3. Exported Functions

• int t_relay_to(struct sip_msg* msg, char* ip_address, char* port_number);

  Relay a message statefully to a fixed destination; this along with t_relay is the function most users want to use -- all other are mostly for programming; programmers interested in writing TM logic should review how t_relay is implemented in tm.c and how TM callbacks work.

  ip_address - IP address of the destination.

  port_number - Port of the destination.

  Example 9-5. t_relay_to

  if (!t_relay_to("1.2.3.4", "5060")) { 
      sl_reply_error(); 
      break; 
  };

• int t_relay(struct sip_msg* msg, char* s1, char* s2);

  Relay a message statefully to destination indicated in current URI; (if the original URI was rewritten by UsrLoc, RR, strip/prefix, etc., the new URI will be taken); returns a negative value on failure -- you may still want to send a negative reply upstream statelessly not to leave upstream UAC in lurch.

  s1 - Not used.

  s2 - Not used.

  Example 9-6. t_relay

  if (!t_relay()) { 
      sl_reply_error(); 
      break; 
  };

• int t_on_negative(struct sip_msg* msg, char* reply_route, char* s);

  Sets reply routing block, to which control is passed after a transaction completed with a negative result but before sending a final reply; In the referred block, you can either start a new branch (good for services such as forward_on_no_reply) or send a final reply on your own (good for example for message silo, which received a negative reply from upstream and wants to tell upstream "202 I will take care of it"); Note that the set of command which are usable within reply_routes is strictly limited to rewriting URI, initiating new branches, logging, and sending 'unsafe' replies (t_reply_unsafe). Any other commands may result in unpredictable behaviour and possible server failure. Note that whenever reply_route is entered, uri is reset to value which it had on relaying. If it temporarily changed during a reply_route processing, subsequent reply_route will ignore the changed value and use again the original one.

  reply_route - Reply routing block.

  s - Not used.

  Example 9-7. t_on_negative

  route { 
      t_on_negative("1"); 
      t_relay(); 
  } reply_route[1] {
      revert_uri(); 
      setuser("voicemail"); 
      append_branch(); 
  }

• int t_newtran(struct sip_msg* msg, char* s1, char* s2);

  Creates a new transaction, returns a negative value on error; this is the only way a script can add a new transaction in an atomic way; typically, it is used to deploy a UAS

  s1 - Not used.

  s2 - Not used.

  Example 9-8. t_newtran

  if (t_newtran()) { 
      log("UAS logic"); 
      t_reply("999","hello"); 
  } else sl_reply_error();

• int t_reply(struct sip_msg* msg, char* code, char* reason_phrase);

  Sends a stateful reply after a transaction has been established; see t_newtran for usage; note: never use t_reply from within reply_route ... always use t_reply_unsafe.

  code - Code of the response.

  reason_phrase - Reason phrase of the response.

• int t_lookup_request(struct sip_msg* msg, char* s1, char* s2);

  Checks if a transaction exists; returns a positive value if so, negative otherwise; most likely you will not want to use it, as a typical application of a look-up is to introduce a new transaction if none was found; however this is safely (atomically) done using t_newtran.

  s1 - Not used.

  s2 - Not used.

• int t_retransmit_reply(struct sip_msg* msg, char* s1, char* s2);

  Retransmits a reply sent previously by UAS transaction.

  s1 - Not used.

  s2 - Not used.

• int t_release(struct sip_msg* msg, char* s1, char* s2);

  Remove transaction from memory (it will be first put on a wait timer to absorb delayed messages).

  s1 - Not used.

  s2 - Not used.

• int t_forward_noack(struct sip_msg* msg, char* ip, char* port);

  Mainly for internal -- forward a non-ACK request statefully.

  ip - IP address.

  port - Port number.

• int register_tmcb(struct sip_msg* msg, char* cb_type, char* cb_func);

  For programmatic use only -- register a function to be called back on an event; see t_hooks.h for more details.

  cb_type - Callback type.

  cb_func - Callback function.

• int load_tm(struct sip_msg* msg, char* import_structure, char* s);

  For programmatic use only -- import exported TM functions; see the acc module for an example of use.

  import_structure - Structure where pointers to tm functions will be stored.

  s - Not used.

• int t_reply_unsafe(struct sip_msg* msg, char* code, char* reason_phrase);

  Sends a stateful reply after a transaction has been established; it can only be used from reply processing; using it from regular processing will introduce erroneous conditions; using t_reply from reply_processing will introduce a deadlock.

  code - Code of the reply.

  reason_phrase - Reason phrase of the reply.

9.6.4. Known Issues

• Need to revisit profiling again.

• Review whether there is not potential for to-tag rewriting and ACK matching.

• We don't have authentication merging on forking.

• Branch tid is not used yet.

• local ACK/CANCELs copy'n'pastes Route and ignores deleted Routes

• 6xx should be delayed.

• Possibly, performance could be improved by not parsing non-INVITEs, as they do not be replied with 100, and do not result in ACK/CANCELs, and other things which take parsing. However, we need to rethink whether we don't need parsed headers later for something else. Remember, when we now conserver a request in sh_mem, we can't apply any pkg_mem operations to it any more. (that might be redesigned too).

• t_replicate should be done more cleanly -- Vias, Routes, etc. should be removed from a message prior to replicating it.

• SNMP support.

• Lookup fails to recognize subsequent requests which have additional leading spaces in header field values.

• Make UAC session-aware (as opposed to just transaction aware) -- needed for keeping SUB-NOT dialog state, etc. Currently, there are only place-holders for in in TM.

• Places labeled with "HACK" strongly deserve beautification.

9.7.1. Exported Parameters

• user_col - Name of column containing usernames.

  Type: string

  Default: "user"

• contact_col - Name of column containing contacts.

  Type: string

  Default: "contact"

• expires_col - Name of column containing expires.

  Type: string

  Default: "expires"

• q_col - Name of column containing q values.

  Type: string

  Default: "q"

• callid_col - Name of column containing callids.

  Type: string

  Default: "callid"

• cseq_col - Name of column containing cseq numbers.

  Type: string

  Default: "cseq"

• method_col - Name of column containing supported methods.

  Type: string

  Default: "method"

• db_url - URL of the database that should be used.

  Type: string

  Default: "sql://ser:heslo@localhost/ser"

• timer_interval - Number of seconds between two timer runs. The module uses timer to delete expired contacts, synchronize with database and other tasks, that need to be run periodically.

  Type: integer

  Default: 60 seconds

• db_mode - The usrloc module can utilize database for persistent contact storage. If you use database, your contacts will survive machine restarts or sw crashes. The disadvantage is that accessing database can be very time consuming. Therefore, usrloc module implements three database accessing modes:

  • 0 - This disables database completely. Only memory will be used. Contacts will not survive restart. Use this value if you need a really fast usrloc and contact persistence is not necessary or is provided by other means.

  • 1 - Write-Through scheme. All changes to usrloc are immediately reflected in database too. This is very slow, but very reliable. Use this scheme if speed is not your priority but need to make sure that no registered contacts will be lost during crash or reboot.

  • 2 - Write-Back scheme. This is a combination of previous two schemes. All changes are made to memory and database synchronization is done in the timer. The timer deletes all expired contacts and flushes all modified or new contacts to database. Use this scheme if you encounter high-load peaks and want them to process as fast as possible. The mode will not help at all if the load is high all the time. Also, latency of this mode is much lower than latency of mode 1, but slightly higher than latency of mode 0.

  Type: integer

  Default: 0

  In case of crash or restart contacts that are in memory only and haven't been flushed yet will get lost. If you want minimize the risk, use shorter timer interval.

9.7.2. Exported Functions

• int ul_register_domain(const char* name);

  The function registers a new domain. Domain is just another name for table used in registrar. The function is called from fixups in registrar. It gets name of the domain as a parameter and returns pointer to a new domain structure. The fixup than 'fixes' the parameter in registrar so that it will pass the pointer instead of the name every time save() or lookup() is called. Some usrloc functions get the pointer as parameter when called. For more details see implementation of save function in registrar.

  name - Name of the domain (also called table) to be registered.

• int ul_insert_urecord(udomain_t* domain, str* aor, urecord_t** rec);

  The function creates a new record structure and inserts it in the specified domain. The record is structure that contains all the contacts for belonging to the specified username.

  domain - Pointer to domain returned by ul_register_udomain.

  aor - Address of Record (aka username) of the new record (at this time the record will contain no contacts yet).

  rec - The newly created record structure.

• int ul_delete_urecord(udomain_t* domain, str* aor);

  The function deletes all the contacts bound with the given Address Of Record.

  domain - Pointer to domain returned by ul_register_udomain.

  aor - Address of record (aka username) of the record, that should be deleted.

• int ul_get_urecord(udomain_t* domain, str* aor);

  The function returns pointer to record with given Address of Record.

  domain - Pointer to domain returned by ul_register_udomain.

  aor - Address of Record of request record.

• int ul_lock_udomain(udomain_t* domain);

  The function lock the specified domain, it means, that no other processes will be able to access during the time. This prevents race conditions. Scope of the lock is the specified domain, that means, that multiple domain can be accessed simultaneously, they don't block each other.

  domain - Domain to be locked.

• int ul_unlock_udomain(udomain_t* domain);

  Unlock the specified domain previously locked by ul_lock_udomain.

  domain - Domain to be unlocked.

• int ul_release_urecord(urecord_t* record);

  Do some sanity checks - if all contacts have been removed, delete the entire record structure.

  record - Record to be released.

• int ul_insert_ucontact(urecord_t* record, str* contact, time_t expires, float q, str* callid, int cseq, ucontact_t* cont);

  The function inserts a new contact in the given record with specified parameters.

  record - Record in which the contact should be inserted.

  contact - Contact URL.

  expires - Expires of the contact in absolute value.

  q - q value of the contact.

  callid - Call-ID of the REGISTER message that contained the contact.

  cseq - CSeq of the REGISTER message that contained the contact.

  cont - Pointer to newly created structure.

• int ul_delete_ucontact(urecord_t* record, ucontact_t* contact);

  The function deletes given contact from record.

  record - Record from which the contact should be removed.

  contact - Contact to be deleted.

• int ul_get_ucontact(urecord_t* record, str* contact);

  The function tries to find contact with given Contact URI and returns pointer to structure representing the contact.

  record - Record to be searched for the contact.

  contact - URI of the request contact.

• int ul_update_ucontact(ucontact_t* contact, time_t expires, float q, str* callid, int cseq);

  The function updates contact with new values.

  contact - Contact to be updated.

  expires - New expires value.

  q - New q value.

  callid - New Call-ID.

  cseq - New CSeq.