The parser

oSIP now supports utf8 and the full SIP grammar. The release 0.7.0 contains a compliant SIP parser with minimal exceptions. Also, the new parser has just been released (25th of July 2001) and may have some bugs. Please report them 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 url_t type definition in the request-uri and in the following headers: "to", "from", "contact", "route", and "record-route".

type definition of url_t.

typedef struct _sipurl_t {
  char *scheme;
  char *username;
  char *password;
  char *host;
  char *port;
  list_t *url_params;
  list_t *url_headers;
} url_t ;

API for SIP-URL

#include <smsg.h>

url_init

url_free

url_parse

url_2char

url_clone

url_uparam_add

url_uheader_add

url_uparam_getbyname

API for url_param_t and url_header_t

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

  typedef struct _url_param_t {
    char *pname;
    char *pvalue;
  } url_param_t;

  typedef struct _url_header_t {
    char *hname;
    char *hvalue;
  } url_header_t;

url_param_init

url_param_free

url_param_set

url_param_freelist

url_param_add

url_param_getbyname

Definition and purpose

The rfc2543 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 _to_t {
  char *displayname;
  url_t *url;
  list_t *gen_params;
} to_t;

Common API for all implemented header.

The SIP parser can parse entirely the following headers: Via, To, From, CSeq, Call-Id, Contact, Route, Record-Route, Content-Type, Content-length, Mime-Version. The other headers are accessible as strings through a special API.

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

#include <smsg.h>

to_init

to_free

to_parse

to_2char

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.

to_setdisplayname

to_getdisplayname

to_seturl

to_geturl

to_param_add

to_param_get

to_gettag

to_settag

to_param_getbyname

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 _to_t {
      char *displayname;
      url_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_getname

generic_param_setname

generic_param_getvalue

generic_param_setvalue

generic_param_add

generic_param_getbyname

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 _sip_t {
  /* Start-Line definition */
  char *sipversion;
  /* req */
  osip_uri_t *rquri;
  char *sipmethod;
  /* resp */
  char *statuscode;
  char *reasonphrase;
  /* End of Start-Line definition */

  /* for all header fully implemented by oSIP */
  from_t           *from;
  to_t             *to;
  call_id_t        *call_id;
  cseq_t           *cseq;
  list_t           *vias;
  list_t           *contacts;
  list_t           *record_routes;
  list_t           *routes;
  content_type_t   *content_type;
  content_length_t *contentlength;
  mime_version_t   *mime_version;

  /* for all other headers */
  list_t           *headers;

  /* for all attachments */
  list_t           *bodies;

} sip_t;

API for SIP message

#include <smsg.h>

msg_init

osip_message_free

msg_parse

msg_2char

msg_clone

msg_setheader

msg_getheader

msg_header_getbyname

msg_setcall_id

msg_getcall_id

msg_setcseq

msg_getcseq

msg_setcontact

msg_getcontact

msg_setfrom

msg_getfrom

msg_setto

msg_getto

msg_setvia

msg_getvia

msg_setrecord_route

msg_getrecord_route

msg_setroute

msg_getroute

msg_setcontent_length

msg_getcontent_length

msg_setcontent_type

msg_getcontent_type

msg_setmime_version

msg_getmime_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 */
#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))

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 sip_t, or from_t) a method "xxxx_init()" exists and MUST be used to request allocation. Using this method with the correspondent "xxxx_free()" allows a competitive memory management thus avoiding as many memory leaks as possible.

 sip_t  *msg;
 msg_init(&msg);

 osip_message_free(msg);
 free(msg);

 url_t *url;
 url_init(&url);

 url_free(url);
 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. */
 url_t  *uri;
 url_init(&uri);
 url_setscheme(url,sstrdup("sip"));
 url_setuserinfo(url,sstrdup("jack"));
 url_sethost(url,sstrdup("atosc.org"));

 msg_setmethod(msg,sstrdup("INVITE"));
 msg_seturi(msg,uri);
 msg_setversion(msg,sstrdup("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:

 {
  url_t    *url;
  to_t     *to;
  url_init(&url);
  url_setusername(url,sstrdup("jack"));
  url_sethost(url,sstrdup("atosc.org"));

  to_init(&to);
  to_seturl(to,url);
  to_setdisplayname(to,sstrdup("jack..."));

  msg_setto(msg, to);
 }

  /* the same API is available for the from_t structure */
 {
  from_t   *from;
  /* allocate a url_t */
  url_init(&url);
  url_setusername(url,sstrdup("cha"));
  url_sethost(url,sstrdup("anywhere.org"));

  /* allocate a from_t */
  from_init(&from);
  from_seturl(from,url);
  from_setdisplayname(from,sstrdup("My love"));
  from_set_tag(from,sstrdup("a48a"));

  msg_setfrom(msg, from);
 }

 {
  via_t    *via;
  via_init(&via);

  via_setversion(via,sstrdup("2.0"));
  via_setprotocol(via,sstrdup("UDP"));
  via_sethost(via,sstrdup("137.137.137.137"));
  via_set_branch(via,sstrdup("branch"),sstrdup("a7c6a8dlze.1"));

  msg_setvia(msg, via);
 }

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

  msg_setcseq(msg, cseq);
 }

 {
  callid_t *callid;
  callid_init(&callid);

  callid_setnumber(callid,sstrdup("f81d4"));
  callid_sethost(callid,sstrdup("foo.atosc.org"));

  msg_setcallid(msg, callid);
 }

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

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

 /* add a body */
 msg_setbody(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 sip_t like for the structure used for the headers (to_t, from_t, call_id_t...), a method exist to retrieve printed version of the element.

  char *astring;
  astring = sip_2char(msg);
  free(astring);

free resource in a structure

 sip_free(msg);
 free(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 rfc2543. oSIP uses the 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 (sipevent_t) which concern this transaction.

The proxy attribute give the host and port to be used for requests. (all requests will be forced to go to the proxy whatever the request-uri contains.

typedef struct _transaction_t {
  void *your_instance;       /* add whatever you want here.       */
  int transactionid;         /* simple id used to identify the tr.*/
  fifo_t *transactionff;     /* events must be added in this FIFO */
  url_t *proxy;              /* url used to send requests        */    

  from_t    *from;           /* CALL-LEG definition */
  to_t      *to;
  call_id_t *callid;
  cseq_t    *cseq;
  sip_t *lastrequest;        /* last request received or sent     */
  sip_t *lastresponse;       /* last response received or sent    */

  state_t state;             /* state of transaction              */
  statemachine_t *statemachine; /* state-machine of transaction   */

  time_t birth_time;         /* birth_date of transaction         */
  time_t completed_time;     /* end   date of transaction         */
  int retransmissioncounter; /* facilities for internal timer     */

  void *config;              /* transaction is managed by config */
                             /* of type osip_t */
} transaction_t;

Definition and purpose of sipevent

sipevents 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 _sipevent_t {
  type_t type;
  int transactionid;
  sip_t *sip;
} sipevent_t;

API

#include <osip.h>

osip_init

osip_free

osip_init_proxy

osip_execute

osip_distribute_event

osip_parse

osip_new_event

osip_new_incoming_event

osip_new_outgoing_event

osip_find_asincomingmessage

osip_find_asoutgoingmessage

osip_find_byid

osip_remove_byid

transaction_init

transaction_free

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).

void osip_setcb_rcvinvite  (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvack     (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvbye     (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvcancel  (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvinfo    (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvoptions (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvregister(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvprack   (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcvunkrequest(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));

void osip_setcb_sndinvite  (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndack     (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndbye     (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndcancel  (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndinfo    (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndoptions (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndregister(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndprack   (osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_sndunkrequest(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));

void osip_setcb_rcv1xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcv2xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcv3xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcv4xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcv5xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_rcv6xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));

void osip_setcb_snd1xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_snd2xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_snd3xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_snd4xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_snd5xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));
void osip_setcb_snd6xx(osip_t *cf,void (*cb)(sipevent_t*,transaction_t*));

void osip_setcb_rcvresp_retransmission(osip_t *cf,void (*cb)(transaction_t*));
void osip_setcb_sndreq_retransmission (osip_t *cf,void (*cb)(transaction_t*));
void osip_setcb_sndresp_retransmission(osip_t *cf,void (*cb)(transaction_t*));
void osip_setcb_rcvreq_retransmission (osip_t *cf,void (*cb)(transaction_t*));

void osip_setcb_killtransaction   (osip_t *cf,void (*cb)(transaction_t*));
void osip_setcb_endoftransaction  (osip_t *cf,void (*cb)(transaction_t*));
void osip_setcb_connection_refused(osip_t *cf,void (*cb)(transaction_t*));
void osip_setcb_network_error     (osip_t *cf,void (*cb)(transaction_t*));

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)       (event->type==RCV_REQINVITE)
#define EVT_IS_RCV_ACK(event)          (event->type==RCV_REQACK)
#define EVT_IS_RCV_REQUEST(event)      (event->type==RCV_REQUEST)
#define EVT_IS_RCV_STATUS_1XX(event)   (event->type==RCV_STATUS_1XX)
#define EVT_IS_RCV_STATUS_23456XX(event)   (event->type==RCV_STATUS_23456XX)

/* FOR OUTGOING TRANSACTION */
#define EVT_IS_SND_INVITE(event)       (event->type==SND_REQINVITE)
#define EVT_IS_SND_ACK(event)          (event->type==SND_REQACK)
#define EVT_IS_SND_REQUEST(event)      (event->type==SND_REQUEST)
#define EVT_IS_SND_STATUS_1XX(event)   (event->type==SND_STATUS_1XX)
#define EVT_IS_SND_STATUS_23456XX(event)   (event->type==SND_STATUS_23456XX)

#define EVT_IS_INCOMINGMSG(event)      (event->type>=RCV_REQINVITE \
                	               &&event->type<=RCV_STATUS_23456XX)
#define EVT_IS_INCOMINGREQ(event)      (EVT_IS_RCV_INVITE(event) \
                                       ||EVT_IS_RCV_ACK(event) \
                                       ||EVT_IS_RCV_REQUEST(event))
#define EVT_IS_INCOMINGRESP(event)     (EVT_IS_RCV_STATUS_1XX(event) \
                                       ||EVT_IS_RCV_STATUS_23456XX(event))
#define EVT_IS_OUTGOINGMSG(event)      (event->type>=SND_REQINVITE \
                	               &&event->type<=SND_STATUS_23456XX)
#define EVT_IS_OUTGOINGREQ(event)      (EVT_IS_SND_INVITE(event) \
                                       ||EVT_IS_SND_ACK(event) \
                                       ||EVT_IS_SND_REQUEST(event))
#define EVT_IS_OUTGOINGRESP(event)     (EVT_IS_SND_STATUS_1XX(event) \
                                       ||EVT_IS_SND_STATUS_23456XX(event))
#define EVT_IS_MSG(event)              (event->type>=RCV_REQINVITE \
                	               &&event->type<=SND_STATUS_23456XX)
#define EVT_IS_KILL_TRANSACTION(event) (event->type==KILL_TRANSACTION)
#define EVT_IS_UNKNOWN_EVT(event)      (event->type==UNKNOWN_EVT)
#define EVT_IS_TIMEOUT(event)          (event->type==TIMEOUT)

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_global_init())
    return -1; /* mutex is not initialized properly */

  osip_init(&osip);
  osip_init_proxy(osip,url_of_proxy);

  osip_setcb_rcvresp_retransmission(cf,&cb_rcvresp_retransmission);
  osip_setcb_sndreq_retransmission(cf,&cb_sndreq_retransmission);
  osip_setcb_sndresp_retransmission(cf,&cb_sndresp_retransmission);
  osip_setcb_rcvreq_retransmission(cf,&cb_rcvreq_retransmission);
  
  osip_setcb_killtransaction(cf,&cb_killtransaction);
  osip_setcb_endoftransaction(cf,&cb_endoftransaction);
  
  osip_setcb_connection_refused(cf,&cb_connection_refused);
  osip_setcb_network_error(cf,&cb_network_error);
  
  osip_setcb_rcv1xx(cf,&cb_rcv1xx);
  osip_setcb_rcv2xx(cf,&cb_rcv2xx);
  osip_setcb_rcv3xx(cf,&cb_rcv3xx);
  osip_setcb_rcv4xx(cf,&cb_rcv4xx);
  osip_setcb_rcv5xx(cf,&cb_rcv5xx);
  osip_setcb_rcv6xx(cf,&cb_rcv6xx);
  
  osip_setcb_sndinvite  (cf,&cb_sndinvite);
  osip_setcb_sndack     (cf,&cb_sndack);
  osip_setcb_sndbye     (cf,&cb_sndbye);
  osip_setcb_sndcancel  (cf,&cb_sndcancel);
  osip_setcb_sndinfo    (cf,&cb_sndinfo);
  osip_setcb_sndoptions (cf,&cb_sndoptions);
  osip_setcb_sndregister(cf,&cb_sndregister);
  osip_setcb_sndprack   (cf,&cb_sndprack);
  osip_setcb_sndunkrequest(cf,&cb_sndunkrequest);

  osip_setcb_snd1xx(cf,&cb_snd1xx);
  osip_setcb_snd2xx(cf,&cb_snd2xx);
  osip_setcb_snd3xx(cf,&cb_snd3xx);
  osip_setcb_snd4xx(cf,&cb_snd4xx);
  osip_setcb_snd5xx(cf,&cb_snd5xx);
  osip_setcb_snd6xx(cf,&cb_snd6xx);

  osip_setcb_rcvinvite  (cf,&cb_rcvinvite);
  osip_setcb_rcvack     (cf,&cb_rcvack);
  osip_setcb_rcvbye     (cf,&cb_rcvbye);
  osip_setcb_rcvcancel  (cf,&cb_rcvcancel);
  osip_setcb_rcvinfo    (cf,&cb_rcvinfo);
  osip_setcb_rcvoptions (cf,&cb_rcvoptions);
  osip_setcb_rcvregister(cf,&cb_rcvregister);
  osip_setcb_rcvprack   (cf,&cb_rcvprack);
  osip_setcb_rcvunkrequest(cf,&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)
{
  sip_t         *invite;
  transaction_t *transaction;

  /* You must create your own SIP message. */
  msg_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.)             */
  trn_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(transaction_t *transaction,sip_t *msg)
{
    sipevent_t *sipevent;

    sipevent = osip_new_outgoing_sipmessage(msg);
    sipevent->transactionid =  transaction->transactionid;

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

#ifdef OSIP_MT
    fifo_add(transaction->transactionff,sipevent);
#else
    transaction_execute(transaction,sipevent);
#endif

    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. A state machine for statefull proxy will be added in the future. The existing state machines are not easily usable for proxy implementation!

For stateless proxy, a state machine is very simple (No state is needed!). Nevertheless, A state machine will be implemented. its only role will be to cache results for a short time.