Example 2-1. INVITE request

INVITE requests are used to initiate and modify sessions. Here, cha from sipworld.net is calling jack from domain atosc.org. This request should be sent to the proxy server managing atosc.org, it will forward the call to jack at his real IP address.

INVITE sip:jacK@atosc.org SIP/2.0
Via: SIP/2.0/UDP home.sipworld.org
To: sip:jacK@atosc.org
From: sip:cha@sipworld.org
Call-ID: 35778645354@home.sipworld.org
CSeq: 1 INVITE
Contact: sip:cha@home.sipworld.org
Content-type: application/sdp
Content-length: 267

v=0
o=user1 53655765 2353687637 IN IP4 128.3.4.5
s=Mbone Audio
i=Discussion of Mbone Engineering Issues
e=mbone@somewhere.com
c=IN IP4 128.3.4.5
t=0 0
m=audio 3456 RTP/AVP 0
a=rtpmap:0 PCMU/8000

Example 2-2. INVITE transaction

This is the most basic call flow showing the initiation of a session. Only two SIP User Agents (UAC/UAS) are involved. (retransmissions are hidden)

	          UAC1               UAS2

	  jacks    |   INVITE         |
	initiate a |----------------->|   Bob's
	  call     |                  | Phone starts
	           |       180 Ringing|   ringing
	           |<-----------------|
	           |       180 Ringing|
        	   |<-----------------|
	           |           200 OK |
	           |<-----------------|
	           |   ACK            |
	           |----------------->|

Example 2-3. A complete session

First, both user agents must send a REGISTER to a registrar. In the following example, the proxy also support registration.

This session is initiated with an INVITE transaction to join jack at home.net. A redirection to jack's office is made by the redirect server of home.net. UA1 understand the redirection and send a new INVITE towards the real User Agent (UA2) currently used by jack at office.atosc.org. UA2 first rings and jack accepts the call with a 200 OK response. After several minutes, jack and bob want to use their new cameras. The session is modified with an INVITE sent by jack to negociate new parameters for video. The session is finally ended by bob.

         BOB           home.net    Jack (atosc.org)
         UA1            PROXY            UA2
          | REGISTER      |               .
          |-------------->|               .
          |        200 OK |               .
          |<--------------|               .
          .               .               .
later...  .               .               .
          .               .               .
          .               |      REGISTER |
          .               |<--------------|
          .               | 200 OK        |
          .               |-------------->|
          .               .               .
later...  .               .               .
          | INVITE jack@home.net          .
          |-------------->|               .
          |302 Moved temporily            .
          |<--------------|               .
          | ACK           |               .
          |-------------->|               .
          | INVITE jack@office.atosc.org  |
          | audio                         |
          |------------------------------>|
          |                  180 Ringing  |
          |<------------------------------|
          |                  180 Ringing  |
          |<------------------------------|
          |                       200 OK  |
          |<------------------------------|
          | ACK jack@office.atosc.org     |
          |------------------------------>|
          .                               .
later     .                               .
          .                               .
          |      INVITE bob@bob.home.net  |
          |      audio + video            |
          |<------------------------------|
          |    200 OK                     |
          |------------------------------>|
          |     ACK bob@bob.home.org      |
          |<------------------------------|
          .                               .
later     .                               .
          .                               .
          | BYE jack@office.atosc.org     |
          |------------------------------>|
          |                       200 OK  |
          |<------------------------------|
          |                               |

Example 4-5. Declaration of the sip_t structure.

Currently this structure is not complete. All other header than From, To, Call-Id, CSeq, via, contact 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 _sip_t {
  startline_t  *strtline;

  from_t    *from;
  to_t      *to;
  call_id_t *call_id;
  cseq_t    *cseq;
  list_t    *vias;
  list_t    *contacts;

  list_t    *headers;

  content_type_t   *content_type;
  content_length_t *contentlength;
  mime_version_t   *mime_version;
  list_t    *bodies;

} sip_t;

Example 4-6. Method to manage "sip_t"

The oSIP stack only parses a minimal set of headers. Nevertheless, you still have access to other headers which are available as strings. (This is also a way to support headers not defined by the initial RFC)

int   msg_parse(sip_t *dest , char *message, err_t *err);
int   msg_init(sip_t **sip, err_t *err);
void  msg_free(sip_t *sip);

/* Those methods parse some specific headers.         */
int   msg_setheader(sip_t *sip, char *hname,
		    char *hvalue, err_t *err);
int   msg_setcall_id(sip_t *sip, char *hvalue, err_t *err);
int   msg_setcontact(sip_t *sip, char *hvalue, err_t *err);
int   msg_setcseq   (sip_t  *sip, char *hvalue, err_t *err);
int   msg_setfrom(sip_t *sip, char *hvalue, err_t *err);
int   msg_setto(sip_t *sip, char *hvalue, err_t *err);
int   msg_setvia(sip_t *sip, char *hvalue, err_t *err);
int   msg_setcontent_length(sip_t *sip, char *hvalue, err_t *);
int   msg_setcontent_type(sip_t *sip, char *hvalue,err_t *err);
int   msg_setmime_version(sip_t *sip, char *hvalue, err_t *err);
#define msg_setcontent_encoding(C, S, E) msg_setcontent_length(C, S, E) 

int   url_parse      (url_t *url,  char *buf, err_t *err);


/* The following macros can be used to access other headers   */
/* This list is not complete, but a MACRO exists for each SIP */
/* header (in osip/smsg.h). */
#define setaccept(P,R)    msg_setheader((sip_t *)P,(char *)"accept",R)
...
...
...

Example 4-7. List of MACROs

#define MSG_IS_RESPONSE(resp)     (resp->strtline->statuscode!=NULL)
#define MSG_IS_REQUEST(req)       (req->strtline->statuscode==NULL)

#define MSG_IS_INVITE(msg)        (0==strncmp(msg->strtline->sipmethod,"INVITE",6))
#define MSG_IS_ACK(msg)           (0==strncmp(msg->strtline->sipmethod,"ACK",6))
#define MSG_IS_BYE(msg)           (0==strncmp(msg->strtline->sipmethod,"BYE",6))
#define MSG_IS_REGISTER(msg)      (0==strncmp(msg->strtline->sipmethod,"REGISTER",6))
#define MSG_IS_CANCEL(msg)        (0==strncmp(msg->strtline->sipmethod,"CANCEL",6))
#define MSG_IS_OPTIONS(msg)       (0==strncmp(msg->strtline->sipmethod,"OPTIONS",6))
#define MSG_IS_INFO(msg)          (0==strncmp(msg->strtline->sipmethod,"INFO",6))
#define MSG_IS_PRACK(msg)         (0==strncmp(msg->strtline->sipmethod,"PRACK",6))

#define MSG_IS_STATUS_1XX(msg)    (0==strncmp(msg->strtline->statuscode,"1",1))
#define MSG_IS_STATUS_2XX(msg)    (0==strncmp(msg->strtline->statuscode,"2",1))
#define MSG_IS_STATUS_3XX(msg)    (0==strncmp(msg->strtline->statuscode,"3",1))
#define MSG_IS_STATUS_4XX(msg)    (0==strncmp(msg->strtline->statuscode,"4",1))
#define MSG_IS_STATUS_5XX(msg)    (0==strncmp(msg->strtline->statuscode,"5",1))
#define MSG_IS_STATUS_6XX(msg)    (0==strncmp(msg->strtline->statuscode,"6",1))
#define MSG_TEST_CODE(resp, code) (resp->strtline->statuscode!=NULL \
				   && code==(int)satoi(resp->strtline->statuscode))
#define MSG_IS_RESPONSEFOR(resp,requestname) \
                                  (0==strcmp(resp->cseq->method,requestname))

Example 4-8. header API

int   msg_init(sip_t **sip, err_t *err);
int   msg_free(sip_t *sip, err_t *err);
int   msg_parse(sip_t *sip, char *message, err_t *err);
int   msg_2char(sip_t *sip, char **dest, err_t *err);

int   header_init(header_t **header, err_t *err);
void  header_free(header_t *header);
int   header_parse(header_t *header,char *string, err_t *err);
int   header_2char(header_t *header,char **dest, err_t *err);

int   call_id_init     (callid_t **dest, err_t *err);
void  call_id_free     (callid_t *callid);
int   call_id_parse    (callid_t *callid, char *hvalue, err_t *err);
int   call_id_2char    (callid_t *callid, char **dest, err_t *err);
int   call_id_getnumber(callid_t *callid, char** dest);
int   call_id_gethost  (callid_t *callid, char** dest);
void  call_id_setnumber(callid_t *callid, char *number);
void  call_id_sethost  (callid_t *callid, char *host);

void  cseq_init     (cseq_t **dest, err_t *err);
void  cseq_free     (cseq_t *cseq);
char* cseq_2char    (cseq_t *cseq, char **dest, err_t *err);
int   cseq_parse    (cseq_t *cseq, char *hvalue, err_t *err);
char* cseq_getnumber(cseq_t *cseq, char **dest);
char* cseq_getmethod(cseq_t *cseq, char **dest);
void  cseq_setnumber(cseq_t *cseq, char *number);
void  cseq_setmethod(cseq_t *cseq, char *method);

int   from_init     (from_t **dest, err_t *err);
void  from_free     (from_t *from);
int   from_parse    (from_t *from, char *string, err_t *err);
int   from_2char    (from_t *from, char **dest, err_t *err);
int   from_compare  (from_t *from1, from_t *from2);

int   to_init(to_t **dest, err_t *err);
void  to_free(to_t *to);
int   to_parse(to_t *to, char *string, err_t *err);
int   to_2char(to_t *to, char **dest, err_t *err);

int   via_init(via_t **dest, err_t *err);
void  via_free(via_t *via);
int   via_parse(via_t *via, char *string, err_t *err);
int   via_2char(via_t *via, char **dest, err_t *err);

int   content_length_init (content_length_t **dest, err_t *err);
void  content_length_free (content_length_t *content_length);
int   content_length_parse(content_length_t *content_length,
			   char *string, err_t *err);
char* content_length_2char(content_length_t *content_length,
                           char **dest, err_t *err);

int   contact_init (contact_t **dest, err_t *err);
void  contact_free(contact_t *contact);
int   contact_parse(contact_t *contact, char *string, err_t *err);
char* contact_2char(contact_t *contact, err_t *err);

int   body_init(body_t *body, err_t *err);
void  body_free(body_t *body);
int   body_parse(body_t *body, char *string, err_t *err);
int   body_parse_mime(body_t *body, char *string, err_t *err);
char* body_2char(body_t *body, err_t *err);

/* this is a default method to create generic response      */
/* You SHOULD NOT use it. Creating your own is recommended  */
int   msg_makereply(int status, char *reason, sip_t *request,
                    sip_t *dest, char *body, char *content_type,
                    int options, err_t *err);

Example 4-9. Example for INVITE

sip_t *
msg_create_invite()
{
 /* allocation of the structure */
 sip_t  *msg;
 url_t  *uri;
 err_t  err;
 msg_init(&msg,&err);

 /* make a request line. */
 uri_init(&uri,&err);
 url_setscheme(url,sstrdup("sip"));
 url_setuserinfo(url,sstrdup("jack"));
 url_sethost(url,sstrdup("atosc.org"));

 sip_setmethod(msg,sstrdup("INVITE"));
 sip_setversion(msg,sstrdup("2.0"));
 sip_seturi(msg,uri);

 /* set main headers */
 {
  url_t    *url;
  to_t     *to;

  url_init(&url, &err);
  url_setscheme(url,sstrdup("sip"));
  url_setuserinfo(url,sstrdup("jack"));
  url_sethost(url,sstrdup("atosc.org"));
  url_setport(url,sstrdup("5060"));
  url_seturlparam(url,sstrdup("transport"),sstrdup("TCP"));
  url_seturlparam(url,sstrdup("ttl"),sstrdup("100"));
  url_seturlparam(url,sstrdup("maddr"),sstrdup("here.atosc.org"));
  url_setheader(url,sstrdup("subject"),sstrdup("oSIP stack"));

  to_init(&to, &err);
  to_seturl(to,url);
  to_setdisplayname(to,sstrdup("jack the stack"));
  to_settoparam(to,sstrdup("tag"),sstrdup("a48a"));

  sip_setto(msg, to);
 }

  /* the same API is available for the from_t structure */
 {
  from_t   *from;
  ...
  ...
  sip_setfrom(msg, from);
 }

 {
  via_t    *via;
  via_init(&via, &err);

  via_setprotocolname(via,sstrdup("SIP")); /* this is a default value */
  via_setsentprotocol(via,sstrdup("UDP")); /* this is a default value */
  via_setsentbyhost(via,sstrdup("137.137.137.137"));
  via_setsentbyport(via,sstrdup("5060"));  /* this is a default value */
  via_sethidden(via);                      /* default is not hidden   */
  via_setparam(via,sstrdup("branch"),sstrdup("a7c6a8dlze.1"));

  sip_setvia(msg, via);
 }

 {
  cseq_t   *cseq;
  cseq_init(&cseq, &err);
  ...

  sip_setcseq(msg, cseq);
 }

 {
  callid_t *callid;
  callid_init(&callid, &err);

  callid_settoken1(callid,sstrdup("f81d4"));
  callid_settoken2(callid,sstrdup("foo.atosc.org"));

  sip_setcallid(msg, callid);
 }

 /* this API can also be used, but it is much more time consuming! */
 /* msg_setto(msg,"sip:cha@anydomain.org", &err); */
 /* msg_setfrom(msg,"sip:jacK@atosc.org", &err); */
 /* msg_setcall_id(msg,"132485@foo.atosc.org", &err); */
 /* msg_setcseq(msg,"1 INVITE", &err); */
 /* msg_setvia(msg,"SIP/2.0/UDP 202.202.202.202:5080", &err); */

 msg_setcontact(msg,"sip:jacK@office.atosc.org", &err);

 /* Let's add some headers */
 msg_setheader(msg,sstrdup("SuBjecT"),sstrdup("Need support for oSIP!"), &err);

 /* add a body */
 sip_setbody(msg,"v=0\\o=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\r\n", &err);

 /* get the message as a string */
 {
  char *astring;
  astring = sip_2char(msg, &err);
  sfree(astring);
 }

 return msg;
 /* This is how you must free all memory */
 sip_free(sip);
 sfree(sip);
}

Example 5-1. How to use the finite state machine

Each user layer has access to its list of pending transactions (through a set of methods). Each context is stored in a transaction_t structure. The transaction_t structure has a attribute which is the FIFO address of the transaction.

/* method to send events */
transaction_t *trn_findid(list_t *transactions, int transactionid);
void fifo_add(fifo_t *fifo, void *element);

                                                    Transaction
          User Layer                                  contexts
        +------------+                             +-----------+
        |            |    events          +--------|           |
        |            |-----+------------->| FIFO 1 |     1     |
        +------------+     |              +--------|           |
                           |                       +-----------+
                           |
                           |                       +-----------+
                           |              +--------|           |
                           +------------->| FIFO N |     N     |
                                          +--------|           |
                                                   +-----------+

Example 5-2. Your application

At the beginning of your program and before you start using the SIP stack, you must build your own osip_t configuration. The osip_t structure is described below:

typedef struct _osip_t {

  /* this is the (udp) port where sipd is waiting */
  int udp_port;
  int tcp_port;

  list_t *transactions;
  /* One layer can handle several transactions */

  fifo_t *uas_timerff;
  pthread_t *uas_timerthread;
  fifo_t *uac_timerff;
  pthread_t *uac_timerthread;

  /* CAUTION: THIS IS NOT YET AVAILABLE IN RELEASE 0.6.0 */
  int  (*cb_connection_refused)(sipevent_t*, transaction_t *);
  int  (*cb_network_error)(sipevent_t*, transaction_t *);

  int  (*cb_inc_sndresp_retransmission(sipevent_t*, transaction_t *);
  int  (*cb_inc_rcvreq_retransmission(sipevent_t*, transaction_t *);
  int  (*cb_incoming_invite)(sipevent_t*, transaction_t *);
  int  (*cb_inc_ack)(sipevent_t*, transaction_t *);
  int  (*cb_inc_bye)(sipevent_t*, transaction_t *);
  int  (*cb_inc_cancel)(sipevent_t*, transaction_t *);
  int  (*cb_inc_info)(sipevent_t*, transaction_t *);
  int  (*cb_inc_options)(sipevent_t*, transaction_t *);
  int  (*cb_inc_register)(sipevent_t*, transaction_t *);
  int  (*cb_inc_prack)(sipevent_t*, transaction_t *);
  int  (*cb_inc_unknownreq)(sipevent_t*, transaction_t *);
  int  (*cb_inc_1xx)(sipevent_t*, transaction_t *);
  int  (*cb_inc_2xx)(sipevent_t*, transaction_t *);
  int  (*cb_inc_3xx)(sipevent_t*, transaction_t *);
  int  (*cb_inc_4xx)(sipevent_t*, transaction_t *);
  int  (*cb_inc_5xx)(sipevent_t*, transaction_t *);
  int  (*cb_inc_6xx)(sipevent_t*, transaction_t *);

  int  (*cb_outg_sndreq_retransmission)(transaction_t *);
  int  (*cb_outg_rcvresp_retransmission)(transaction_t *);
  int  (*cb_outg_invite)(sipevent_t*, transaction_t *);
  int  (*cb_outg_ack)(sipevent_t*, transaction_t *);
  int  (*cb_outg_bye)(sipevent_t*, transaction_t *);
  int  (*cb_outg_cancel)(sipevent_t*, transaction_t *);
  int  (*cb_outg_info)(sipevent_t*, transaction_t *);
  int  (*cb_outg_options)(sipevent_t*, transaction_t *);
  int  (*cb_outg_register)(sipevent_t*, transaction_t *);
  int  (*cb_outg_prack)(sipevent_t*, transaction_t *);
  int  (*cb_outg_unknownreq)(sipevent_t*, transaction_t *);
  int  (*cb_outg_1xx)(sipevent_t*, transaction_t *);
  int  (*cb_outg_2xx)(sipevent_t*, transaction_t *);
  int  (*cb_outg_3xx)(sipevent_t*, transaction_t *);
  int  (*cb_outg_4xx)(sipevent_t*, transaction_t *);
  int  (*cb_outg_5xx)(sipevent_t*, transaction_t *);
  int  (*cb_outg_6xx)(sipevent_t*, transaction_t *);

} osip_t;

Example 5-3. Callback registration API

osip_t *osip;
osip_init(&osip, &err);

/************/
/* UAS part */
/************/

/* register callbacks for new incoming requests */
/* Those callbacks are highly needed for UAS    */
osip_on_inc_invite    (osip, app_inc_invite);
osip_on_inc_ack       (osip, app_inc_ack);
osip_on_inc_bye       (osip, app_inc_bye
osip_on_inc_cancel    (osip, app_inc_cancel);
osip_on_inc_info      (osip, app_inc_info);
osip_on_inc_options   (osip, app_inc_options);
osip_on_inc_register  (osip, app_inc_register);
osip_on_inc_unknown   (osip, app_inc_unknown);

/* register callbacks for new outgoing response  */
/* Those callbacks may be useless in many cases. */
osip_on_outg_1xx       (osip, app_outg_1xx);
osip_on_outg_2xx       (osip, app_outg_2xx);
osip_on_outg_3xx       (osip, app_outg_3xx);
osip_on_outg_4xx       (osip, app_outg_4xx);
osip_on_outg_5xx       (osip, app_outg_5xx);
osip_on_outg_6xx       (osip, app_outg_6xx);

/* register callbacks to be aware of retransmissions */
/* Those callbacks may be useless in many cases.     */
osip_on_sndresp_retransmission(osip, app_sndresp_retransmission);
osip_on_rcvreq_retransmission (osip, app_rcvreq_retransmission);

/* register callback to be aware of network errors */
osip_on_connection_refused(osip, app_network_error);
osip_on_network_error(osip,app_network_error);

/************/
/* UAC part */
/************/
/* register callbacks for new incoming response */
/* those callbacks are mandatory.               */
osip_on_inc_1xx       (osip, app_inc_1xx);
osip_on_inc_2xx       (osip, app_inc_2xx);
osip_on_inc_3xx       (osip, app_inc_3xx);
osip_on_inc_4xx       (osip, app_inc_4xx);
osip_on_inc_5xx       (osip, app_inc_5xx);
osip_on_inc_6xx       (osip, app_inc_6xx);


/* register callbacks for new outgoing request  */
/* Those callbacks may be useless in many cases */
osip_on_outg_invite   (osip, app_outg_invite);
osip_on_outg_ack      (osip, app_outg_ack);
osip_on_outg_bye      (osip, app_outg_bye);
osip_on_outg_cancel   (osip, app_outg_cancel);
osip_on_outg_info     (osip, app_outg_info);
osip_on_outg_options  (osip, app_outg_options);
osip_on_outg_register (osip, app_outg_register);
osip_on_outg_unknown  (osip, app_outg_unknown);

/* register callbacks to be aware of retransmissions */
/* Those callbacks may be useless in many cases.     */
osip_on_rcvresp_retransmission(osip, app_rcvresp_retransmission);
osip_on_sndreq_retransmission (osip, app_sndreq_retransmission);

Example 5-4. Relations between interface and SIP behavior

The application controls the behavior of transactions by sending events to a FIFO (an event generally contains a SIP message). In the following example, the user has to allocate two SIP messages (INVITE and ACK) and transmits them to the stack. All responses are filtered by the finite state machines and the stack will start the appropriate actions. If the stack does not require any additional information to handle the event, the task is executed automatically and the application is informed through a callback.

         *add_event(INVITE)*   |           |
              ------------>    |           |  INVITE
                               |   STACK   |------------>
                               | internals |  INVITE retransmission
osip->cb_rcvresp_retransmission(e)         |------------>
              <------------    |           |
                               |           |  100 Trying
osip->cb_inc_1xx(evt)          |           |<------------
              <------------    |           |
                               |           |  180 Ringing
osip->cb_inc_1xx(evt)          |           |<------------
              <------------    |           |
                               |           |  200 OK
osip->cb_inc_2xx(evt)          |           |<------------
              <------------    |           |  200 OK retransmission
                               |           |<------------
     add_event(fifo,evt)       |           |
              ------------>    |           |  ACK
                               |           |------------>
                               |           |  200 OK
osip->cb_rcvresp_retransmission(e)         |<------------
              <------------    |           |
                               |           |  ACK
                               |           |------------>

osip->cb_*(sipevent_t *) are methods implemented by the application layer. They are used by the stack to announce states of transactions.