The parser

oSIP should be provide a fully compliant SIP parser. If you ever see something missing or not correct, please report bugs to <osip@atosc.org>, I'll fix them.

The state machines

The 4 finite state machines have been tested during weeks and have also been tested with around 30 products at the 8th SIPit in Cardiff (SIP Interoperability tests). They appear to be stable.

Definition and purpose

URL are used to describe entirely a SIP entity: user, registrar, proxy have their own urls. oSIP uses the osip_uri_t type definition in the request-uri and in the following headers: "to", "from", "contact", "route", and "record-route".

type definition of osip_uri_t.

typedef struct osip_uri {
  char *scheme;
  char *username;
  char *password;
  char *host;
  char *port;
  list_t *url_params;
  list_t *url_headers;
} osip_uri_t ;

API for SIP-URL

#include <osipparser2/osip_uri.h>

osip_uri_init

osip_uri_free

osip_uri_parse

osip_uri_to_str

osip_uri_clone

osip_uri_uparam_add

osip_uri_uheader_add

osip_uri_uparam_get_byname

API for osip_uri_param_t and osip_uri_header_t

osip_uri_param_t and osip_uri_header_t are data types used inside a SIP-URL. Methods are provided to allocate, free or clone resources.

  typedef struct osip_uri_param {
    char *pname;
    char *pvalue;
  } osip_uri_param_t;

  typedef osip_uri_param_t osip_uri_header_t;

osip_uri_param_init

osip_uri_param_free

osip_uri_param_set

osip_uri_param_freelist

osip_uri_param_add

osip_uri_param_get_byname

Definition and purpose

The rfc3261 defines around 40 headers. SIP Messages are mainly composed of a list of headers. This first part documents the API to create, allocate, parse and print the SIP headers elements. The second one shows that headers also have a extended API only applicable for one type of header. The extended API presented below is for the "To" header. Nevertheless, the extended API for the "To" header is also valid for the "From", "Contact", "Route" and "Record-Route" headers.

typedef struct osip_to_t {
  char *displayname;
  osip_uri_t *url;
  list_t *gen_params;
} osip_to_t;

Common API for all implemented header.

The SIP parser can parse entirely a few headers such as: Via, To, From, CSeq, Call-Id, Contact, Route, Record-Route, Content-Type, Content-length, Mime-Version (see API for a complete list of headers API). The other headers are accessible as strings through a special API.

As an example, the following methods concern the API to manipulate a osip_to_t structure.

#include <osipparser2/osip_parser.h>

osip_to_init

osip_to_free

osip_to_parse

osip_to_to_str

osip_to_clone

Specific API for "To" header

In addition to the common API shared by all known implemented header, there is a specific API valid only for each header. The following methods concern the "To" header.

osip_to_set_displayname

osip_to_get_displayname

osip_to_set_url

osip_to_get_url

osip_to_param_add

osip_to_param_get

osip_to_get_tag

osip_to_set_tag

osip_to_param_get_byname

API for generic param

Generic parameter are components of many headers such as To, From, Contact, Route, Record-Route, and Content-Type.

  typedef struct _generic_param_t {
      char *pname;
      char *pvalue;
  } generic_param_t;

  /* to, from and contact headers are defined as below */ 
  typedef struct _osip_to_t {
      char *displayname;
      osip_uri_t *url;
      list_t *gen_params;
  }

  to: "jack" <sip:atosc.org>;tag=ae56fr-dz-23

generic_param_init

generic_param_free

generic_param_set

generic_param_get_name

generic_param_setname

generic_param_get_value

generic_param_setvalue

generic_param_add

generic_param_get_byname

generic_param_freelist

definition and purpose

The messages are based at this level on three parts. The first line is either the request-uri for requests or the status code for responses. This first line corresponds to the first attribute of oSIP: startline_t. The second valuable part of a SIP message is a list of headers. The last attribute (list of body) is a possible list of attachments found in the message.

Currently this structure sip_t is not complete. All other header than "From", "To", "Call-Id", "CSeq", "via", "contact", "route", "record-route", mime-version", "content-type" and "content-length" are stored as string in a list of generic headers. This structure will be completed while improving the parser capabilities.

 typedef struct osip_message
  {
    char *sip_version;                /**< SIP version (SIP request only) */
    osip_uri_t *req_uri;              /**< Request-Uri (SIP request only) */
    char *sip_method;                 /**< METHOD (SIP request only) */

    int status_code;                  /**< Status Code (SIP answer only) */
    char *reason_phrase;              /**< Reason Phrase (SIP answer only) */

    osip_list_t *accepts;             /**< Accept headers */
    osip_list_t *accept_encodings;    /**< Accept-Encoding headers */
    osip_list_t *accept_languages;    /**< Accept-Language headers */
    osip_list_t *alert_infos;         /**< Alert-Info headers */
    osip_list_t *allows;              /**< Allows headers */
    osip_list_t *authentication_infos;/**< authentication_info headers */
    osip_list_t *authorizations;      /**< Authorizations headers */
    osip_call_id_t *call_id;          /**< Call-ID header */
    osip_list_t *call_infos;          /**< Call-Infos header */
    osip_list_t *contacts;            /**< Contacts headers */
    osip_list_t *content_dispositions;/**< Content-Dispositions headers */
    osip_list_t *content_encodings;   /**< Content-Encodings headers */
    osip_content_length_t *content_length;   /**< Content-Length header */
    osip_content_type_t *content_type;       /**< Content-Type header */
    osip_cseq_t *cseq;                /**< CSeq header */
    osip_list_t *error_infos;         /**< Error-Info headers */
    osip_from_t *from;                /**< From header */
    osip_mime_version_t *mime_version;/**< Mime-Version header */
    osip_list_t *proxy_authenticates; /**< Proxy-Authenticate headers */
    osip_list_t *proxy_authentication_infos; /**< P-Authentication-Info headers */
    osip_list_t *proxy_authorizations;/**< Proxy-authorization headers */
    osip_list_t *record_routes;       /**< Record-Route headers */
    osip_list_t *routes;              /**< Route headers */
    osip_to_t *to;                    /**< To header */
    osip_list_t *vias;                /**< Vias headers */
    osip_list_t *www_authenticates;   /**< WWW-Authenticate headers */

    osip_list_t *headers;             /**< Other headers */

    osip_list_t *bodies;              /**< List of attachements */

    /*
       1: structure and buffer "message" are identical.
       2: buffer "message" is not up to date with the structure info (call osip_message_to_str to update it).
     */
    int message_property;             /**@internal */
    char *message;                    /**@internal */
    size_t message_length;            /**@internal */

    void *application_data;           /**can be used by upper layer*/
  } osip_message_t;

API for SIP message

#include <osipparser2/osip_parser.h>

osip_message_init

osip_message_free

osip_message_parse

osip_message_to_str

osip_message_clone

osip_message_set_header

osip_message_get_header

osip_message_header_get_byname

osip_message_set_call_id

osip_message_get_call_id

osip_message_set_cseq

osip_message_get_cseq

osip_message_set_contact

osip_message_get_contact

osip_message_set_from

osip_message_get_from

osip_message_set_to

osip_message_get_to

osip_message_set_via

osip_message_get_via

osip_message_set_record_route

osip_message_get_record_route

osip_message_set_route

osip_message_get_route

osip_message_set_content_length

osip_message_get_content_length

osip_message_set_content_type

osip_message_get_content_type

osip_message_set_mime_version

osip_message_get_mime_version

MACROs

Other helpful MACROs are defined. They are used to test characteristics of messages such as the type of a message, the method of a request and the status code of a response.

/* a few MACROS to ease readability of code */
 MSG_IS_RESPONSE(resp)
 MSG_IS_REQUEST(req)

 MSG_IS_INVITE(msg)
 MSG_IS_ACK(msg)
 MSG_IS_BYE(msg)
 MSG_IS_REGISTER(msg)
 MSG_IS_CANCEL(msg)
 MSG_IS_OPTIONS(msg)
 MSG_IS_INFO(msg)
 MSG_IS_PRACK(msg)

 MSG_IS_STATUS_1XX(msg)
 MSG_IS_STATUS_2XX(msg)
 MSG_IS_STATUS_3XX(msg)
 MSG_IS_STATUS_4XX(msg)
 MSG_IS_STATUS_5XX(msg)
 MSG_IS_STATUS_6XX(msg)

 MSG_TEST_CODE(resp, code)
 MSG_IS_RESPONSEFOR(resp,requestname)

Initialise the parser

The oSIP parser need to be initialised at run time. This is done by first calling the following method before using the oSIP parser. (This method MUST only be called once.)

int parser_init();

Allocate a structure

oSIP has a standard approach to request allocation of structures. For each SIP related one, (like osip_message_t, or osip_from_t) a method "osip_xxxx_init()" exists and MUST be used to request allocation. It must be used along with "osip_xxxx_free()".

 osip_message_t *msg;
 osip_message_init(&msg);
 osip_message_free(msg);

 osip_uri_t *url;
 osip_uri_init(&url);
 osip_uri_free(url);

create a URL and a Request-URI.

The following code is used to build a request line for an INVITE message. This line will be: "INVITE sip:jack@atosc.org SIP/2.0".

 /* make a request line. */
 osip_uri_t  *uri;
 osip_uri_init(&uri);
 osip_uri_set_scheme(url,osip_strdup("sip"));
 osip_uri_set_username(url,osip_strdup("jack"));
 osip_uri_set_host(url,osip_strdup("atosc.org"));

 osip_message_set_method(msg,osip_strdup("INVITE"));
 osip_message_set_uri(msg,uri);
 osip_message_set_version(msg,osip_strdup("2.0"));

Add headers in a message

This example shows the code required to allocate headers and add each of them in the sip_t structure. You should take a look at the RFC when building messages.

For INVITE requests,the following headers are mandatory:

 {
  osip_uri_t    *url;
  osip_to_t     *to;
  osip_uri_init(&url);
  osip_uri_set_username(url,osip_strdup("jack"));
  osip_uri_set_host(url,osip_strdup("atosc.org"));

  osip_to_init(&to);
  osip_to_set_url(to,url);
  osip_to_set_displayname(to,osip_strdup("Aymeric MOIZARD"));

  osip_message_set_to(msg, to);
 }

  /* the same API is available for the osip_from_t structure */
 {
  osip_from_t   *from;
  /* allocate a osip_uri_t */
  osip_uri_init(&url);
  osip_uri_set_username(url,osip_strdup("cha"));
  osip_uri_set_host(url,osip_strdup("anywhere.org"));

  /* allocate a osip_from_t */
  osip_from_init(&from);
  osip_from_set_url(from,url);
  osip_from_set_displayname(from,osip_strdup("My love"));
  osip_from_set_tag(from,osip_strdup("a48a"));

  osip_message_set_from(msg, from);
 }

 {
  osip_via_t    *via;
  osip_via_init(&via);

  osip_via_set_version(via,osip_strdup("2.0"));
  osip_via_set_protocol(via,osip_strdup("UDP"));
  osip_via_set_host(via,osip_strdup("137.137.137.137"));
  osip_via_set_branch(via,osip_strdup("branch"),osip_strdup("z9hG4bK776asdhds.1"));

  osip_message_set_via(msg, via);
 }

 {
  osip_cseq_t   *cseq;
  cseq_init(&cseq);
  ...

  osip_message_set_cseq(msg, cseq);
 }

 {
  osip_call_id_t *callid;
  osip_call_id_init(&callid);

  osip_callid_set_number(callid,osip_strdup("f81d4"));
  osip_callid_set_host(callid,osip_strdup("foo.atosc.org"));

  osip_message_set_callid(msg, callid);
 }

 /* this API can also be used, but it is much more time consuming! */
 osip_message_set_contact(msg,"sip:jacK@office.atosc.org");

 /* Let's add some headers */
 osip_message_set_header(msg,osip_strdup("SuBjecT"),osip_strdup("Need support for oSIP!"));

 /* add a body */
 osip_message_set_body(msg,"v=0\r\no=user1 53655765 2353687637 IN IP4 128.3.4.5\r\ns=Mbone Audio\r\ni=Discussion of Mbone Engineering Issues\r\ne=mbone@somewhere.com\r\nc=IN IP4 128.3.4.5\r\nt=0 0\r\nm=audio 3456 RTP/AVP 0\r\na=rtpmap:0 PCMU/8000\r\n");

make a string from a structure

For osip_message_t like for the structure used for the headers (osip_to_t, osip_from_t, osip_call_id_t...), a method exist to retrieve printed version of the element.

  char *astring = NULL;
  int length;
  i = osip_message_to_str(msg, &astring, &length);
  if (i!=0)
     return -1;
  osip_free(astring);

free resource in a structure

 osip_messagefree(msg);

The parser may sometimes be too much tolerant. It will accept silently some of your mistakes. As an example, the parser should accept a display name (for a "To" header) with a comma inside. The developer MUST enclose the string between quotes. To keep the application interoperable, please always keep an eye on the rfc and control every characters you put in SIP message.

Definition and purpose of transaction

Transactions are used to store the context of one "SIP transactions" as defined in the rfc3261. oSIP uses the osip_transaction_t internally so you probably don't need to understand each attribute.

       User module
        +------------+
        |            |
        +------------+
            |        msg to send
            +--------------------+        Transaction
       Timer module              |         contexts
        +------------+           |
        |            |           |        +----------+
        +------------+           +------->| TRANSAC. |
            |        timeout evt |        |    1     |
            +--------------------+        +----------+
       Transport module          |
        +------------+           |        +----------+
        |            |           +------->| TRANSAC. |
        +------------+           |        |    2     |
            |      incoming msg  |        +----------+
            +--------------------+

The attribute your_instance is not used by oSIP. You can use it to store a pointer on your own context.

You can use the transactionid as a unique id for the transaction.

transactionff is a FIFO used to receive all events (osip_event_t) which concern this transaction.

typedef struct osip__transaction {
    void *your_instance;        /**< User Defined Pointer. */
    int transactionid;          /**< Internal Transaction Identifier. */
    osip_fifo_t *transactionff; /**< events must be added in this fifo */

    osip_via_t *topvia;         /**< CALL-LEG definition (Top Via) */
    osip_from_t *from;          /**< CALL-LEG definition (From)    */
    osip_to_t *to;              /**< CALL-LEG definition (To)      */
    osip_call_id_t *callid;     /**< CALL-LEG definition (Call-ID) */
    osip_cseq_t *cseq;          /**< CALL-LEG definition (CSeq)    */

    osip_message_t *orig_request;  /**< Initial request            */
    osip_message_t *last_response; /**< Last response              */
    osip_message_t *ack;           /**< ack request sent           */

    state_t state;              /**< Current state of the transaction */

    time_t birth_time;          /**< birth date of transaction        */
    time_t completed_time;      /**< end   date of transaction        */

    int in_socket;              /**< Optional socket for incoming message */
    int out_socket;             /**< Optional place for outgoing message */

    void *config;               /**@internal transaction is managed by osip_t  */

    osip_fsm_type_t ctx_type;   /**< Type of the transaction */
    osip_ict_t *ict_context;    /**@internal */
    osip_ist_t *ist_context;    /**@internal */
    osip_nict_t *nict_context;  /**@internal */
    osip_nist_t *nist_context;  /**@internal */

} osip_transaction_t;

Definition and purpose of osip_event

osip_events objects are used to control the context of one "SIP transaction" element. There is 3 types of SIP events for the finite state machines:

The attribute type always contains the type of the event.

transactionid is now for internal use.

When the event is a SIP message, sip is the parsed message.

typedef struct osip_event {
  type_t type;
  int transactionid;
  osip_message_t *sip;
} osip_event_t;

API

#include <osip2/osip.h>

osip_init

osip_free

osip_execute

osip_find_transaction_and_add_event

osip_parse

osip_new_event

osip_new_incoming_event

osip_new_outgoing_event

osip_transaction_init

osip_transaction_free

osip_transaction_execute

The callbacks.

oSIP uses a set of callbacks to announce the evolution of SIP transactions. For example, when receiving an INVITE request, the method registered by "osip_setcb_rcvinvite(...)" will be called by the stack and used by the developer to create a provisional response and start actions to build a final one.

The following methods allow you to register, on initialization of the osip stack, the methods that will be used to handle transactions. Some of those methods are mandatory (announcements of requests, and final responses) and some are optional (announcements of provisional responses and retransmissions).

  typedef void (*osip_message_cb_t) (int type, osip_transaction_t *,
                                     osip_message_t *);
    OSIP_ICT_INVITE_SENT = 0,               /**< INVITE MESSAGE SENT */
    OSIP_ICT_INVITE_SENT_AGAIN,             /**< INVITE MESSAGE RETRANSMITTED */
    OSIP_ICT_ACK_SENT,                      /**< ACK MESSAGE SENT */
    OSIP_ICT_ACK_SENT_AGAIN,                /**< ACK MESSAGE RETRANSMITTED */
    OSIP_ICT_STATUS_1XX_RECEIVED,           /**< 1XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_2XX_RECEIVED,           /**< 2XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_2XX_RECEIVED_AGAIN,     /**< 2XX FOR INVITE RECEIVED AGAIN */
    OSIP_ICT_STATUS_3XX_RECEIVED,           /**< 3XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_4XX_RECEIVED,           /**< 4XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_5XX_RECEIVED,           /**< 5XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_6XX_RECEIVED,           /**< 6XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_3456XX_RECEIVED_AGAIN,  /**< RESPONSE RECEIVED AGAIN */

    OSIP_IST_INVITE_RECEIVED,               /**< INVITE MESSAGE RECEIVED */
    OSIP_IST_INVITE_RECEIVED_AGAIN,         /**< INVITE MESSAGE RECEIVED AGAN */
    OSIP_IST_ACK_RECEIVED,                  /**< ACK MESSAGE RECEIVED */
    OSIP_IST_ACK_RECEIVED_AGAIN,            /**< ACK MESSAGE RECEIVED AGAIN */
    OSIP_IST_STATUS_1XX_SENT,               /**< 1XX FOR INVITE SENT */
    OSIP_IST_STATUS_2XX_SENT,               /**< 2XX FOR INVITE SENT */
    OSIP_IST_STATUS_2XX_SENT_AGAIN,         /**< 2XX FOR INVITE RETRANSMITTED */
    OSIP_IST_STATUS_3XX_SENT,               /**< 3XX FOR INVITE SENT */
    OSIP_IST_STATUS_4XX_SENT,               /**< 4XX FOR INVITE SENT */
    OSIP_IST_STATUS_5XX_SENT,               /**< 5XX FOR INVITE SENT */
    OSIP_IST_STATUS_6XX_SENT,               /**< 6XX FOR INVITE SENT */
    OSIP_IST_STATUS_3456XX_SENT_AGAIN,      /**< RESPONSE RETRANSMITTED */

    OSIP_NICT_REGISTER_SENT,                /**< REGISTER MESSAGE SENT */
    OSIP_NICT_BYE_SENT,                     /**< BYE MESSAGE SENT */
    OSIP_NICT_OPTIONS_SENT,                 /**< OPTIONS MESSAGE SENT */
    OSIP_NICT_INFO_SENT,                    /**< INFO MESSAGE SENT */
    OSIP_NICT_CANCEL_SENT,                  /**< CANCEL MESSAGE SENT */
    OSIP_NICT_NOTIFY_SENT,                  /**< NOTIFY MESSAGE SENT */
    OSIP_NICT_SUBSCRIBE_SENT,               /**< SUBSCRIBE MESSAGE SENT */
    OSIP_NICT_UNKNOWN_REQUEST_SENT,         /**< UNKNOWN REQUEST MESSAGE SENT */
    OSIP_NICT_REQUEST_SENT_AGAIN,           /**< REQUEST MESSAGE RETRANMITTED */
    OSIP_NICT_STATUS_1XX_RECEIVED,          /**< 1XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_2XX_RECEIVED,          /**< 2XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_2XX_RECEIVED_AGAIN,    /**< 2XX FOR MESSAGE RECEIVED AGAIN */
    OSIP_NICT_STATUS_3XX_RECEIVED,          /**< 3XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_4XX_RECEIVED,          /**< 4XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_5XX_RECEIVED,          /**< 5XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_6XX_RECEIVED,          /**< 6XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_3456XX_RECEIVED_AGAIN, /**< RESPONSE RECEIVED AGAIN */

    OSIP_NIST_REGISTER_RECEIVED,            /**< REGISTER RECEIVED */
    OSIP_NIST_BYE_RECEIVED,                 /**< BYE RECEIVED */
    OSIP_NIST_OPTIONS_RECEIVED,             /**< OPTIONS RECEIVED */
    OSIP_NIST_INFO_RECEIVED,                /**< INFO RECEIVED */
    OSIP_NIST_CANCEL_RECEIVED,              /**< CANCEL RECEIVED */
    OSIP_NIST_NOTIFY_RECEIVED,              /**< NOTIFY RECEIVED */
    OSIP_NIST_SUBSCRIBE_RECEIVED,           /**< SUBSCRIBE RECEIVED */

    OSIP_NIST_UNKNOWN_REQUEST_RECEIVED,     /**< UNKNWON REQUEST RECEIVED */
    OSIP_NIST_REQUEST_RECEIVED_AGAIN,       /**< UNKNWON REQUEST RECEIVED AGAIN */
    OSIP_NIST_STATUS_1XX_SENT,              /**< 1XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_2XX_SENT,              /**< 2XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_2XX_SENT_AGAIN,        /**< 2XX FOR MESSAGE RETRANSMITTED */
    OSIP_NIST_STATUS_3XX_SENT,              /**< 3XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_4XX_SENT,              /**< 4XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_5XX_SENT,              /**< 5XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_6XX_SENT,              /**< 6XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_3456XX_SENT_AGAIN,     /**< RESPONSE RETRANSMITTED */

  int osip_set_message_callback (osip_t *osip, int type, osip_message_cb_t cb);


  typedef void (*osip_kill_transaction_cb_t) (int type, osip_transaction_t *);
    OSIP_ICT_KILL_TRANSACTION,      /**< end of Client INVITE transaction */
    OSIP_IST_KILL_TRANSACTION,      /**< end of Server INVITE transaction */
    OSIP_NICT_KILL_TRANSACTION,     /**< end of Client Non-INVITE transaction */
    OSIP_NIST_KILL_TRANSACTION,     /**< end of Server Non-INVITE transaction */
  int osip_set_kill_transaction_callback (osip_t *osip, int type,
                                          osip_kill_transaction_cb_t cb);

  typedef void (*osip_transport_error_cb_t) (int type, osip_transaction_t *,
                                             int error);
    OSIP_ICT_TRANSPORT_ERROR,             /**< transport error for ICT */
    OSIP_IST_TRANSPORT_ERROR,             /**< transport error for IST */
    OSIP_NICT_TRANSPORT_ERROR,            /**< transport error for NICT */
    OSIP_NIST_TRANSPORT_ERROR,            /**< transport error for NIST */
  int osip_set_transport_error_callback (osip_t *osip, int type,
                                         osip_transport_error_cb_t cb);

Useful MACROs.

You can also use the following list of MACROs. It is recommended to use them if you want your application to keep full compatibility over oSIP releases.

/* FOR INCOMING TRANSACTION */
#define EVT_IS_RCV_INVITE(event)
#define EVT_IS_RCV_ACK(event)
#define EVT_IS_RCV_REQUEST(event)
#define EVT_IS_RCV_STATUS_1XX(event)
#define EVT_IS_RCV_STATUS_23456XX(event)

/* FOR OUTGOING TRANSACTION */
#define EVT_IS_SND_INVITE(event)
#define EVT_IS_SND_ACK(event)
#define EVT_IS_SND_REQUEST(event)
#define EVT_IS_SND_STATUS_1XX(event)
#define EVT_IS_SND_STATUS_23456XX(event)

>

Initialise the osip stack

The oSIP stack needs to be initialised at run time. This is done by first calling the following method before using the oSIP stack. (This method MUST only be called once). Calling this method also initialise the parser.

int osip_global_init();

Allocate and initialize an osip_t element

The osip_t structure is a container for a list of transactions. This element represents an instance of a SIP agent. osip_t can be used for UAS/UAC, registrar and redirect server.

The following code is used to build a complete osip_t element. First, you have to register a set of mandatory and optional callbacks. You can also configure the stack to use a proxy for all outgoing requests.

  osip_t  *osip;

  if (-1==osip_init(&osip))
    return -1; /* mutex is not initialized properly */

  osip_set_kill_transaction_callback(osip ,OSIP_ICT_KILL_TRANSACTION,
                                 &cb_ict_kill_transaction);
  osip_set_kill_transaction_callback(osip ,OSIP_NIST_KILL_TRANSACTION,
                                 &cb_ist_kill_transaction);
  osip_set_kill_transaction_callback(osip ,OSIP_NICT_KILL_TRANSACTION,
                                 &cb_nict_kill_transaction);
  osip_set_kill_transaction_callback(osip ,OSIP_NIST_KILL_TRANSACTION,
                                 &cb_nist_kill_transaction);
          
  osip_set_message_callback(osip ,OSIP_ICT_STATUS_2XX_RECEIVED_AGAIN,
                        &cb_rcvresp_retransmission);
  osip_set_message_callback(osip ,OSIP_ICT_STATUS_3456XX_RECEIVED_AGAIN,
                        &cb_rcvresp_retransmission);
  osip_set_message_callback(osip ,OSIP_ICT_INVITE_SENT_AGAIN,
                        &cb_sndreq_retransmission);
  osip_set_message_callback(osip ,OSIP_IST_STATUS_2XX_SENT_AGAIN,
                        &cb_sndresp_retransmission);
  osip_set_message_callback(osip ,OSIP_IST_STATUS_3456XX_SENT_AGAIN,
                        &cb_sndresp_retransmission);
  osip_set_message_callback(osip ,OSIP_IST_INVITE_RECEIVED_AGAIN,
                        &cb_rcvreq_retransmission);
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_2XX_RECEIVED_AGAIN,
                        &cb_rcvresp_retransmission);
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_3456XX_RECEIVED_AGAIN,
                        &cb_rcvresp_retransmission);
  osip_set_message_callback(osip ,OSIP_NICT_REQUEST_SENT_AGAIN,
                        &cb_sndreq_retransmission);
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_2XX_SENT_AGAIN,
                        &cb_sndresp_retransmission);
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_3456XX_SENT_AGAIN,
                        &cb_sndresp_retransmission);
  osip_set_message_callback(osip ,OSIP_NIST_REQUEST_RECEIVED_AGAIN,
                        &cb_rcvreq_retransmission);
  

  osip_set_message_callback(osip ,OSIP_ICT_INVITE_SENT,     &cb_sndinvite);
  osip_set_message_callback(osip ,OSIP_ICT_ACK_SENT,        &cb_sndack);
  osip_set_message_callback(osip ,OSIP_NICT_REGISTER_SENT,  &cb_sndregister);
  osip_set_message_callback(osip ,OSIP_NICT_BYE_SENT,       &cb_sndbye);
  osip_set_message_callback(osip ,OSIP_NICT_CANCEL_SENT,    &cb_sndcancel);
  osip_set_message_callback(osip ,OSIP_NICT_INFO_SENT,      &cb_sndinfo);
  osip_set_message_callback(osip ,OSIP_NICT_OPTIONS_SENT,   &cb_sndoptions);
  osip_set_message_callback(osip ,OSIP_NICT_SUBSCRIBE_SENT, &cb_sndsubscribe);
  osip_set_message_callback(osip ,OSIP_NICT_NOTIFY_SENT,    &cb_sndnotify);
  /*  osip_set_cb_nict_sndprack   (osip,&cb_sndprack); */
  osip_set_message_callback(osip ,OSIP_NICT_UNKNOWN_REQUEST_SENT, &cb_sndunkrequest);

  osip_set_message_callback(osip ,OSIP_ICT_STATUS_1XX_RECEIVED, &cb_rcv1xx);
  osip_set_message_callback(osip ,OSIP_ICT_STATUS_2XX_RECEIVED, &cb_rcv2xx);
  osip_set_message_callback(osip ,OSIP_ICT_STATUS_3XX_RECEIVED, &cb_rcv3xx);
  osip_set_message_callback(osip ,OSIP_ICT_STATUS_4XX_RECEIVED, &cb_rcv4xx);
  osip_set_message_callback(osip ,OSIP_ICT_STATUS_5XX_RECEIVED, &cb_rcv5xx);
  osip_set_message_callback(osip ,OSIP_ICT_STATUS_6XX_RECEIVED, &cb_rcv6xx);
  
  osip_set_message_callback(osip ,OSIP_IST_STATUS_1XX_SENT, &cb_snd1xx);
  osip_set_message_callback(osip ,OSIP_IST_STATUS_2XX_SENT, &cb_snd2xx);
  osip_set_message_callback(osip ,OSIP_IST_STATUS_3XX_SENT, &cb_snd3xx);
  osip_set_message_callback(osip ,OSIP_IST_STATUS_4XX_SENT, &cb_snd4xx);
  osip_set_message_callback(osip ,OSIP_IST_STATUS_5XX_SENT, &cb_snd5xx);
  osip_set_message_callback(osip ,OSIP_IST_STATUS_6XX_SENT, &cb_snd6xx);
  
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_1XX_RECEIVED, &cb_rcv1xx);
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_2XX_RECEIVED, &cb_rcv2xx);
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_3XX_RECEIVED, &cb_rcv3xx);
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_4XX_RECEIVED, &cb_rcv4xx);
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_5XX_RECEIVED, &cb_rcv5xx);
  osip_set_message_callback(osip ,OSIP_NICT_STATUS_6XX_RECEIVED, &cb_rcv6xx);
      
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_1XX_SENT, &cb_snd1xx);
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_2XX_SENT, &cb_snd2xx);
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_3XX_SENT, &cb_snd3xx);
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_4XX_SENT, &cb_snd4xx);
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_5XX_SENT, &cb_snd5xx);
  osip_set_message_callback(osip ,OSIP_NIST_STATUS_6XX_SENT, &cb_snd6xx);
  
  osip_set_message_callback(osip ,OSIP_IST_INVITE_RECEIVED,     &cb_rcvinvite);
  osip_set_message_callback(osip ,OSIP_IST_ACK_RECEIVED,        &cb_rcvack);
  osip_set_message_callback(osip ,OSIP_IST_ACK_RECEIVED_AGAIN,  &cb_rcvack2);
  osip_set_message_callback(osip ,OSIP_NIST_REGISTER_RECEIVED,  &cb_rcvregister);
  osip_set_message_callback(osip ,OSIP_NIST_BYE_RECEIVED,       &cb_rcvbye);
  osip_set_message_callback(osip ,OSIP_NIST_CANCEL_RECEIVED,    &cb_rcvcancel);
  osip_set_message_callback(osip ,OSIP_NIST_INFO_RECEIVED,      &cb_rcvinfo);
  osip_set_message_callback(osip ,OSIP_NIST_OPTIONS_RECEIVED,   &cb_rcvoptions);
  osip_set_message_callback(osip ,OSIP_NIST_SUBSCRIBE_RECEIVED, &cb_rcvsubscribe);
  osip_set_message_callback(osip ,OSIP_NIST_NOTIFY_RECEIVED,    &cb_rcvnotify);
  osip_set_message_callback(osip ,OSIP_NIST_UNKNOWN_REQUEST_RECEIVED, &cb_rcvunkrequest);

Send events to control transaction

Here is a sample to initiate a transaction. The initial event sent to the FIFO contains the first INVITE request. The creation of the message is not shown here.

int
create_session(osip_t *osip)
{
  osip_message_t  *invite;
  osip_transaction_t   *transaction;

  /* You must create your own SIP message. */
  osip_message_init (&invite);
  your_own_method_to_setup_messages(invite);

  /* When it is the first invite, allocate    */
  /* and start a new transaction (prepare the
  /* context and start a thread.)             */
  osip_transaction_init(&transaction,
	   osip,
	   invite->to,
	   invite->from,
	   invite->callid,
	   invite->cseq);

  /* The thread is now waiting on its FIFO  */
  /* The following method allocate an event */
  /* and send it to the transaction.        */
  osip_sendmsg(transaction,invite);
}

int
osip_sendmsg(osip_transaction_t *transaction,osip_message_t *msg)
{
    osip_event_t *evt;

    evt = osip_new_outgoing_sipmessage(msg);

/* depending on your application model, you can choose */
/* either to consume the event are add it in the fifo  */
/* and delay the operations */

    osip_fifo_add(transaction->transactionff,evt);
    osip_transaction_execute(transaction,evt);

    return 0;
}

Notes for proxy implementation

The transaction layer provided for oSIP is usable by user agents, registrar, redirect server and some type of conference server.

For stateless proxy, no state machine is required.