howto0_initialize(3) [debian man page]

How-To initialize libeXosip2.(3)				    libeXosip2					  How-To initialize libeXosip2.(3)

NAME

       How-To initialize libeXosip2. - When using eXosip, your first task is to initialize both eXosip context and libosip library (parser and
       state machines). This must be done prior to any use of libeXosip2.

	       #include <eXosip2/eXosip.h>

	       int i;

	       TRACE_INITIALIZE (6, stdout);

	       i=eXosip_init();
	       if (i!=0)
		 return -1;

	       i = eXosip_listen_addr (IPPROTO_UDP, NULL, port, AF_INET, 0);
	       if (i!=0)
		 {
		   eXosip_quit();
		   fprintf (stderr, 'could not initialize transport layer
');
		   return -1;
		 }

	       ... then you have to send messages and wait for eXosip events...

       In the previous code, you've learned how to:

       o Initialize the osip trace (compile this code with -DENABLE_TRACE)
       o Initialize eXosip (and osip) stack
       o Open a socket for signalling (only UDP with initial eXosip2 version)
       Now you have to handle eXosip events. Here is some code to get eXosip_event from the eXosip2 stack.
	 eXosip_event_t *je;
	 for (;;)
	   {
	     je = eXosip_event_wait (0, 50);
	     eXosip_lock();
	     eXosip_automatic_action ();
	     eXosip_unlock();
	     if (je == NULL)
	       break;
	     if (je->type == EXOSIP_CALL_NEW)
	       {
	       ....
	       ....
	       }
	     else if (je->type == EXOSIP_CALL_ACK)
	       {
	       ....
	       ....
	       }
	     else if (je->type == EXOSIP_CALL_ANSWERED)
	       {
	       ....
	       ....
	       }
	     else .....
	     ....
	     ....
	     eXosip_event_free(je);
	   }
       You will receive one event for each SIP message sent. Each event contains the original request of the affected transaction and the last
       response that triggers the event when available.
       You can access all headers from those messages and store them in your own context for other actions or graphic displays.
       For example, when you receive a REFER request for a call transfer, you'll typically retreive the 'refer-To' header:
	 osip_header_t *referto_head = NULL;
	 i = osip_message_header_get_byname (evt->sip, 'refer-to', 0, &referto_head);
	 if (referto_head == NULL || referto_head->hvalue == NULL)
       The eXosip_event also contains identifiers for calls, registrations, incoming subscriptions or outgoing subscriptions when applicable.
       Those identifiers are used in API to control calls, registrations, incoming or outgoing subscriptions. These API will build default
       messages with usual SIP headers (From, To, Call-ID, CSeq, Route, Record-Route, Max-Forward...) and send thoses messages for you.
Author
       Generated automatically by Doxygen for libeXosip2 from the source code.

Version 3.1.0							  Sun Jun 24 2012				  How-To initialize libeXosip2.(3)

How-To initiate, modify or terminate calls.(3)			    libeXosip2			    How-To initiate, modify or terminate calls.(3)

NAME

       How-To initiate, modify or terminate calls. - eXosip2 offers a flexible API to help you controling calls.

   Initiate a call
       To start an outgoing call, you typically need a few headers which will be used by eXosip2 to build a default SIP INVITE request. The code
       below is used to start a call:

	 osip_message_t *invite;
	 int i;

	 i = eXosip_call_build_initial_invite (&invite, '<sip:to@antisip.com>',
					       '<sip:from@antisip.com>',
					       NULL, // optional route header
					       'This is a call for a conversation');
	 if (i != 0)
	   {
	     return -1;
	   }

	 osip_message_set_supported (invite, '100rel');

	 {
	   char tmp[4096];
	   char localip[128];

	   eXosip_guess_localip (AF_INET, localip, 128);
	   snprintf (tmp, 4096,
		     'v=0
'
		     'o=josua 0 0 IN IP4 %s
'
		     's=conversation
'
		     'c=IN IP4 %s
'
		     't=0 0
'
		     'm=audio %s RTP/AVP 0 8 101
'
		     'a=rtpmap:0 PCMU/8000
'
		     'a=rtpmap:8 PCMA/8000
'
		     'a=rtpmap:101 telephone-event/8000
'
		     'a=fmtp:101 0-11
', localip, localip, port);
	   osip_message_set_body (invite, tmp, strlen (tmp));
	   osip_message_set_content_type (invite, 'application/sdp');
	 }

	 eXosip_lock ();
	 i = eXosip_call_send_initial_invite (invite);
	 if (i > 0)
	   {
	     eXosip_call_set_reference (i, reference);
	   }
	 eXosip_unlock ();
	 return i;

       The above code is using eXosip_call_build_initial_invite to build a default SIP INVITE request for a new call. You have to insert a SDP
       body announcing your audio parameter for the RTP stream.

       The above code also show the flexibility of the eXosip2 API which allow you to insert additionnal headers such as 'Supported: 100rel'
       (announcing support for a SIP extension). Thus you can enterely control the creation of SIP requests.

       The returned element of eXosip_call_send_initial_invite is the call identifier that you can use to send a CANCEL. In future events other
       than 100 Trying, you'll also get the dialog identifier that will also be needed to control established calls.

       eXosip_call_set_reference is also a mean to attach one of your own context to a call so that you'll get your pointer back in eXosip_event.

   Answer a call
       The code below is another example that teach you how to answer an incoming call.

       You'll usually need to send a '180 Ringing' SIP answer when receiving a SIP INVITE:

	 eXosip_lock ();
	 eXosip_call_send_answer (ca->tid, 180, NULL);
	 eXosip_unlock ();

       Note: The above code also shows that the stack is sometimes able to build and send a default SIP messages with only one API call

       Then, when the user wants to answer the call, you'll need to send a 200 ok and insert a SDP body in your SIP answer:

	 osip_message_t *answer = NULL;

	 eXosip_lock ();
	 i = eXosip_call_build_answer (ca->tid, 200, &answer);
	 if (i != 0)
	 {
	    eXosip_call_send_answer (ca->tid, 400, NULL);
	 }
	 else
	 {
	    i = sdp_complete_200ok (ca->did, answer);
	    if (i != 0)
	    {
	       osip_message_free (answer);
	       eXosip_call_send_answer (ca->tid, 415, NULL);
	    }
	    else
	       eXosip_call_send_answer (ca->tid, 200, answer);
	 }
	 eXosip_unlock ();

       Note: In the above code, you can note that to send a response to a request, you have to use the transaction identifier (and not a call
       identifier or a dialog identifier!)

       Note2: For sending a 200ok, you'll usually need to insert a SDP body in the answer and before this, to negotiate the parameters and codecs
       that you want to support. In the test tool, provided by eXosip2 (josua application), you'll find a very basic implementation of the SDP
       negotiation.

   Sending other request
       The call control API allows you to send and receive REFER, UPDATE, INFO, OPTIONS, NOTIFY and INVITEs whitin calls. A few limitations still
       exist for answering other requests within calls, but it should be already possible to send any kind of request.

       Here you have a code sample to send an INFO requests used to send an out of band dtmf within the signalling layer.

	 osip_message_t *info;
	 char dtmf_body[1000];
	 int i;

	 eXosip_lock ();
	 i = eXosip_call_build_info (ca->did, &info);
	 if (i == 0)
	 {
	    snprintf (dtmf_body, 999, 'Signal=%c
Duration=250
', c);
	    osip_message_set_content_type (info, 'application/dtmf-relay');
	    osip_message_set_body (info, dtmf_body, strlen (dtmf_body));
	    i = eXosip_call_send_request (ca->did, info);
	 }
	 eXosip_unlock ();

Author
       Generated automatically by Doxygen for libeXosip2 from the source code.

Version 3.1.0							  Sun Jun 24 2012		    How-To initiate, modify or terminate calls.(3)