Osip/eXosip Source Code Analysis

1.1 How to use osip

call osip_init to init the osip library

create transport layer to handle the outgoing and incoming messages.

 

1.2 osip internal

It implements transaction layer which is defined by RFC3261

osip structure

struct osip

  {

    /* list of transactions for ict, ist, nict, nist */

    osip_list_t *osip_ict_transactions;   /**< list of ict transactions */

    osip_list_t *osip_ist_transactions;   /**< list of ist transactions */

    osip_list_t *osip_nict_transactions;  /**< list of nict transactions */

    osip_list_t *osip_nist_transactions;  /**< list of nist transactions */

osip_list_t *ixt_retransmissions;    /**< list of ixt elements */

 

osip_message_cb_t msg_callbacks[OSIP_MESSAGE_CALLBACK_COUNT];

osip_kill_transaction_cb_t kill_callbacks[OSIP_KILL_CALLBACK_COUNT];

osip_transport_error_cb_t    

         tp_error_callbacks[OSIP_TRANSPORT_ERROR_CALLBACK_COUNT]; 

    int (*cb_send_message) (osip_transaction_t *, osip_message_t *, char *,

                            int, int);

  };

Transaction type:

    ICT, /**< Invite Client (outgoing) Transaction */

    IST, /**< Invite Server (incoming) Transaction */

    NICT,/**< Non-Invite Client (outgoing) Transaction */

    NIST /**< Non-Invite Server (incoming) Transaction */

Events:

    RCV_REQINVITE,    /**< Event is an incoming INVITE request */

    RCV_REQACK,       /**< Event is an incoming ACK request */

    RCV_REQUEST,      /**< Event is an incoming NON-INVITE and NON-ACK request */

    RCV_STATUS_1XX,   /**< Event is an incoming informational response */

    RCV_STATUS_2XX,   /**< Event is an incoming 2XX response */

    RCV_STATUS_3456XX,/**< Event is an incoming final response (not 2XX) */

 

    /* FOR OUTGOING MESSAGE */

    SND_REQINVITE,    /**< Event is an outgoing INVITE request */

    SND_REQACK,       /**< Event is an outgoing ACK request */

    SND_REQUEST,      /**< Event is an outgoing NON-INVITE and NON-ACK request */

    SND_STATUS_1XX,   /**< Event is an outgoing informational response */

    SND_STATUS_2XX,   /**< Event is an outgoing 2XX response */

    SND_STATUS_3456XX,/**< Event is an outgoing final response (not 2XX) */

 

KILL_TRANSACTION, /**< Event to 'kill' the transaction before termination */

/* other timer event not listed here*/

Callback:

There are four kinds of callbacks upper layer need to set for osip library:

osip_message_cb_t msg_callbacks[OSIP_MESSAGE_CALLBACK_COUNT];       

            Osip lib will call message callbacks to notify upper layer some information

osip_kill_transaction_cb_t kill_callbacks[OSIP_KILL_CALLBACK_COUNT];

            Osip lib will call these callbacks when a transaction is finished.

osip_transport_error_cb_t tp_error_callbacks[OSIP_TRANSPORT_ERROR_CALLBACK_COUNT]; 

            Osip lib will call these callbacks when the transport layer meet error.

int (*cb_send_message) (osip_transaction_t *, osip_message_t *, char *,

                            int, int);

            Osip lib will call this callback to do the real transportation of the message.

eXosip set these callbacks in eXosip_set_callbacks.

 

osip_init

init 4 types of transaction state machine:

set transition_t list:

typedef struct _transition_t

{

  state_t state;

  type_t type;

  void (*method) (void *, void *);

}

transition_t;

It set the process method for a type of event in a type of state

for example, in __ict_load_fsm ():

transition = (transition_t *) osip_malloc (sizeof (transition_t));

  transition->state = ICT_PRE_CALLING;

  transition->type = SND_REQINVITE;

  transition->method = (void (*)(void *, void *)) &ict_snd_invite;

  osip_list_add (ict_fsm->transitions, transition, -1);

 

How to process the SIP message

TU calls some functions to queue osip_event to the fifo of the transaction.

TU calls funtions, such as osip_ict_execute, which calls osip_transaction_execute to handle the osip_event in fifo:

            osip_transaction_execute first find the type of event, and then get that type of fsm, and then call fsm_callmethod

            fsm_callmethod will find the transition according to event type and transaction state, and the call transition->method

 

2 eXosip Overview

2.1 How to use eXosip lib

call eXosip and eXosip_listen_addr

poll the event periodly

2.2 eXosip lib internal:

It’s based on osip lib. It implements transport layer which is defined by RFC3261

The eXosip doesn’t wrapp the osip library. It just provides a transport layer for supporting message transfer.

 

eXosip_t structure

struct eXosip_t

  {

    struct eXosip_net net_interfaces[3];

     osip_list_t *j_transactions;

    osip_t *j_osip;

    int j_stop_ua;

    void *j_thread;

    jpipe_t *j_socketctl; // to notify an request from upper layer is queued to fifo of transaction

    jpipe_t *j_socketctl_event; //to notify event to upper layer

 

    osip_fifo_t *j_events; //save event which will be sent to upper layer

  };

 

eXosip_init:

init the struct eXosip

call osip_init to init the struct osip which is a member of eXosip(eXosip.j_osip

set osip lib callback: eXosip_set_callbacks (osip):

            cb_snd_message is most important callback

create two pipe(eXosip.j_socketctl and eXosip.j_socketctl_event)

init fifo: osip_fifo_init(eXosip.j_events)

j_stop_ua is used to indicate whether thread should be stopped (used in _eXosip_thread)

 

 

eXosip_listen_addr:

listen on a port for SIP message

call _eXosip_thread

 

_eXosip_thread:

            eXosip_read_message use select to wait for the message from upper layer or network

            call osip_timers_ict_execute, osip_timers_nict_execute  osip_timers_ist_execute and  osip_timers_nist_execute to handle transaction timeout

            call  osip_ict_execute ,osip_nict_execute, osip_ist_execute and osip_nist_execute to handle the event in transaction FIFO

 

eXosip_process_newrequest is used to init UAS transaction

(eXosip_call_send_initial_invite is used to init UAC transaction)

 

for outgoing message:

build SIP message, put to the transaction fifo by calling OSIP API

then write something to pipe to notify _eXosip_thread to handle transaction

 

for incoming message:

_eXosip_thread is listening to the incoming socket, if there is a incoming message,

the _eXosip_thread will be waken up to create a new transaction, and handle transaction.

 

3 The process to send an outgoing message

eXosip_call_build_initial_invite

eXosip_call_send_initial_invite

eXosip_call_init

osip_transaction_init to init a ICT transaction

osip_new_outgoing_sipmessage to create a osip event

osip_transaction_add_event to add event to transaction FIFO

__eXosip_wakeup to wake up _eXosip_thread to handle the event

            _eXosip_thread call osip_ict_execute, osip_ict_execute call osip_transaction_execute to find the type of event, get that type of fsm, and then call fsm_callmethod to handle the event. As the above description, fsm_callmethod will find the transition according to event type and transaction state, and the call transition->method. For ICT transaction in ICT_PRE_CALLING state, __ict_load_fsm set method to ict_snd_invite

            ict_snd_invite will call osip-> cb_send_message, which is set by eXosip_set_callbacks as cb_snd_message

            cb_snd_message will send the message to remote peer. _eXosip_thread will wait for remote response, and call osip_ict_execute to handle the response. The transaction state machine will be changed to different state according to the response. Meanwhile, the state machine will call callback set by eXosip_set_callbacks to notify eXosip state change. When eXosip receive the notification, eXosip will send eXosip-defined event to upper layer by  queuing it to j_events. Upper layer applilcation which should call eXosip_event_wait to wait for events will get event, and handle it. Please refer to the example application  UCT IMS Client.

 

4 The process to receive an incoming message

It is processed in _eXosip_thread:

receives the incoming message

eXosip_process_newrequest to create a new transaction, put to transaction FIFO

osip_ist_execute will handle the event

the following process is similar to osip_ict_execute described on the section 3.