1、exoSip 开发者手册exoSip 开发者手册 本手册指导开发者利用 exoSip 栈开发用户代理原文标题 ： exoSIP User Manual原文作者 ：联系方法 ：版权保护 ： GNU Free Documentation License项目网站 ： http:/ 作者 ： 周芒芝联系方法 ： xing_1 The eXtented eXosip stack.41.1 How-To initialize libeXosip241.2 How-To initiate, modify or terminate calls. 51.2.1 Initiate a call61.2.2 Ans
2、wer a call.71.2.3 Sending other request81.3 How-To send or update registrations. .91.3.1 Initiate a registration .91.3.2 Update a registration .91.3.3 Closing the registration .102 General purpose API .112.1 eXosip2 configuration API112.1.1 Functions112.1.2 Function Documentation.112.2 eXosip2 netwo
3、rk API142.2.2 Functions.142.2.3 Function Documentation.142.3 eXosip2 event API 162.3.1 Data Structures.162.3.2 Enumerations .162.3.3 Functions172.3.4 Enumeration Type Documentation.172.3.5 Function Documentation193 SIP messages and call control API213.1 eXosip2 INVITE and Call Management.213.1.1 Fun
4、ctions.213.1.2 Function Documentation.223.2 eXosip2 request outside of dialog .293.2.1 Functions.293.2.2 Function Documentation.293.3 eXosip2 OPTIONS and UA capabilities Management .313.3.1 Functions.313.3.2 Function Documentation.313.4 eXosip2 Publication Management 333.4.1 Functions.333.4.2 Functi
5、on Documentation.333.5 eXosip2 REFER and blind tranfer Management outside of calls353.5.1 Functions.353.5.2 Function Documentation.353.6 eXosip2 REGISTER and Registration Management 373.6.1 Functions.373.6.2 Function Documentation.373.7 eXosip2 SUBSCRIBE and outgoing subscriptions.393.7.1 Enumeratio
6、ns.393.7.2 Functions.393.7.3 Enumeration Type Documentation403.7.4 Function Documentation.413.8 eXosip2 SUBSCRIBE and incoming subscriptions433.8.1 Functions.433.8.2 Function Documentation.433.9 eXosip2 authentication API.463.9.1 Functions.463.9.2 Function Documentation.463.10 Xosip2 SDP helper API.
7、483.10.1 Functions.483.10.2 Function Documentation.481 The eXtented eXosip stack1.1 How-To initialize libeXosip2.When using eXosip, your first task is to initialize both eXosip context and libosiplibrary (parser and state machines). This must be done prior to any use of libeXosip2.include int i;TRAC
8、E_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 layern“);return -1;. then you have to send messages and wait for eXosip events.In the previous code, youve
9、learned how to: Initialize the osip trace (compile this code with -DENABLE_TRACE) Initialize eXosip (and osip) stack 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 fromthe eXosip2 stack.eXosip_event_t *j
10、e;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 se
11、nt. Each event contains theoriginal request of the affected transaction and the last response that triggers theevent when available.You can access all headers from those messages and store them in your own contextfor other actions or graphic displays.For example, when you receive a REFER request for
12、 a call transfer, youll typicallyretreive the “refer-To“ header:osip_header_t *referto_head = NULL;i = osip_message_header_get_byname (evt-sip, “refer-to“, 0,if (referto_head = NULL | referto_head-hvalue = NULL)The eXosip_event also contains identifiers for calls, registrations, incomingsubscription
13、s or outgoing subscriptions when applicable. Those identifiers are used inAPI to control calls, registrations, incoming or outgoing subscriptions. These API willbuild default messages with usual SIP headers (From, To, Call-ID, CSeq, Route,Record-Route, Max-Forward.) and send thoses messages for you.
14、1.2 How-To initiate, modify or terminate calls.eXosip2 offers a flexible API to help you controling calls.1.2.1 Initiate a callTo start an outgoing call, you typically need a few headers which will be used byeXosip2 to build a default SIP INVITE request. The code below is used to start a call:osip_m
15、essage_t *invite;int i;i = eXosip_call_build_initial_invite (if (i != 0)return -1;osip_message_set_supported (invite, “100rel“);char tmp4096;char localip128;eXosip_guess_localip (AF_INET, localip, 128);snprintf (tmp, 4096,“v=0rn“o=josua 0 0 IN IP4 %srn“s=conversationrn“c=IN IP4 %srn“t=0 0rn“m=audio
16、%s RTP/AVP 0 8 101rn“a=rtpmap:0 PCMU/8000rn“a=rtpmap:8 PCMA/8000rn“a=rtpmap:101 telephone-event/8000rn“a=fmtp:101 0-11rn“, 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_in
17、vite (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 INVITErequest for a new call. You have to insert a SDP body announcing your audioparameter for the RTP stream.The above code also s
18、how the flexibility of the eXosip2 API which allow you to insertadditionnal headers such as “Supported: 100rel“ (announcing support for a SIPextension). Thus you can enterely control the creation of SIP requests.The returned element of eXosip_call_send_initial_invite is the call identifier that youc
19、an use to send a CANCEL. In future events other than 100 Trying, youll also get thedialog 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 callso that youll get your pointer back in eXosip_event.1.2.2 Ans
20、wer a callThe code below is another example that teach you how to answer an incoming call.Youll 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 so
21、metimes able to build and senda default SIP messages with only one API callThen, when the user wants to answer the call, youll need to send a 200 ok and inserta SDP body in your SIP answer:osip_message_t *answer = NULL;eXosip_lock ();i = eXosip_call_build_answer (ca-tid, 200, if (i != 0)eXosip_call_
22、send_answer (ca-tid, 400, NULL);elsei = sdp_complete_200ok (ca-did, answer);if (i != 0)osip_message_free (answer);eXosip_call_send_answer (ca-tid, 415, NULL);elseeXosip_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,
23、 you haveto use the transaction identifier (and not a call identifier or a dialog identifier!)Note2: For sending a 200ok, youll usually need to insert a SDP body in the answerand before this, to negotiate the parameters and codecs that you want to support. Inthe test tool, provided by eXosip2 (josua
24、 application), youll find a very basicimplementation of the SDP negotiation.1.2.3 Sending other requestThe call control API allows you to send and receive REFER, UPDATE, INFO,OPTIONS, NOTIFY and INVITEs whitin calls. A few limitations still exist for answeringother requests within calls, but it shou
25、ld be already possible to send any kind ofrequest.Here you have a code sample to send an INFO requests used to send an out of banddtmf within the signalling layer.osip_message_t *info;char dtmf_body1000;int i;eXosip_lock ();i = eXosip_call_build_info (ca-did, if (i = 0)snprintf (dtmf_body, 999, “Sig
26、nal=%crnDuration=250rn“, 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 ();1.3 How-To send or update registrations.eXosip2 offers a flexible API to help you to regi
27、ster one or several identities.1.3.1 Initiate a registrationTo start a registration, you need to build a default REGISTER request bby providingseveral mandatory headersosip_message_t *reg = NULL;int id;int i;eXosip_lock ();id = eXosip_register_build_initial_register (identity, registrar,NULL,1800, i
28、f (id 0)eXosip_unlock ();return -1;osip_message_set_supported (reg, “100rel“);osip_message_set_supported(reg, “path“);i = eXosip_register_send_register (id, reg);eXosip_unlock ();return i;The returned element of eXosip_register_build_initial_register is the registrationidentifier that you can use to
29、 update your registration. In future events about thisregistration, youll see that registration identifier when applicable.1.3.2 Update a registrationYou just need to reuse the registration identifier:int i;eXosip_lock ();i = eXosip_register_build_register (id, 1800, if (i 0)eXosip_unlock ();return
30、-1;eXosip_register_send_register (id, reg);eXosip_unlock ();Note: The above code also shows that the stack is sometimes able to build and senda default SIP messages with only one API call1.3.3 Closing the registrationA softphone should delete its registration on the SIP server when terminating. To d
31、oso, you have to send a REGISTER request with the expires header set to value “0“.The same code as for updating a registration is used with 0 instead of 1800 for theexpiration delay.2 General purpose API2.1 eXosip2 configuration API2.1.1 Functionsint eXosip_init (void)void eXosip_quit (void)int eXos
32、ip_set_option (eXosip_option opt, const void *value)int eXosip_lock (void)int eXosip_unlock (void)int eXosip_listen_addr (int transport, const char *addr, int port, int family, int secure)int eXosip_set_socket (int transport, int socket, int port)void eXosip_set_user_agent (const char *user_agent)vo
33、id eXosip_enable_ipv6 (int ipv6_enable)void eXosip_masquerade_contact (const char *public_address, int port)2.1.2 Function Documentationint eXosip_init( void )Initiate the eXtented oSIP library.void eXosip_quit( void )Release ressource used by the eXtented oSIP library.inteXosip_set_option( eXosip_o
34、ption opt,const void * value)Set eXosip options. See eXosip_option for available options.Parameters:opt option to configure.value value for options.int eXosip_lock( void )Lock the eXtented oSIP library.int eXosip_unlock( void )UnLock the eXtented oSIP library.inteXosip_listen_addr(inttransport,const
35、char * addr,int port,int family,int secure)Listen on a specified socket.Parameters:transport IPPROTO_UDP for udp. (soon to come: TCP/TLS?)addr the address to bind (NULL for all interface)port the listening port. (0 for random port)family the IP family (AF_INET or AF_INET6).secure 0 for UDP or TCP, 1
36、 for TLS (with TCP).inteXosip_set_socket( int transport,int socket,int port)Listen on a specified socket.Parameters:transport IPPROTO_UDP for udp. (soon to come: TCP/TLS?)socket socket to use for listening to UDP sip messages.port the listening port for masquerading.void eXosip_set_user_agent( const
37、 char * user_agent )Set the SIP User-Agent: header string.Parameters:user_agent the User-Agent header to insert in messages.void eXosip_enable_ipv6( int ipv6_enable )Use IPv6 instead of IPv4.Parameters:ipv6_enable This paramter should be set to 1 to enable IPv6 mode.voideXosip_masquerade_contact(con
38、stchar * public_address,int port)This method is used to replace contact address with the public address of your NAT. The ipaddress should be retreived manually (fixed IP address) or with STUN. This address will onlybe used when the remote correspondant appears to be on an DIFFERENT LAN.Parameters:pu
39、blic_address the ip address.port the port for masquerading.If set to NULL, then the local ip address will be guessed automatically (returns to defaultmode).2.2 eXosip2 network API2.2.2 Functionsint eXosip_transport_set (osip_message_t *msg, const char *transport)int eXosip_guess_localip (int family,
40、 char *address, int size)2.2.3 Function DocumentationinteXosip_transport_set(osip_message_t * msg,const char* transport)Modify the transport protocol used to send SIP message.Parameters:msg The SIP message to modifytransport transport protocol to use (“UDP“, “TCP“ or “TLS“)inteXosip_guess_localip(in
41、tfamily,char* address,int size)Find the current localip (interface with default route).Parameters:family AF_INET or AF_INET6address a string containing the local IP address.size The size of the string2.3 eXosip2 event API2.3.1 Data Structuresstruct eXosip_eventstruct eXosip_event2.3.2 Enumerationsen
42、um eXosip_event_type EXOSIP_REGISTRATION_NEW,EXOSIP_REGISTRATION_SUCCESS,EXOSIP_REGISTRATION_FAILURE,EXOSIP_REGISTRATION_REFRESHED,EXOSIP_REGISTRATION_TERMINATED,EXOSIP_CALL_INVITE,EXOSIP_CALL_REINVITE,EXOSIP_CALL_NOANSWER,EXOSIP_CALL_PROCEEDING,EXOSIP_CALL_RINGING,EXOSIP_CALL_ANSWERED,EXOSIP_CALL_R
43、EDIRECTED,EXOSIP_CALL_REQUESTFAILURE,EXOSIP_CALL_SERVERFAILURE,EXOSIP_CALL_GLOBALFAILURE,EXOSIP_CALL_ACK,EXOSIP_CALL_CANCELLED,EXOSIP_CALL_TIMEOUT,EXOSIP_CALL_MESSAGE_NEW,EXOSIP_CALL_MESSAGE_PROCEEDING,EXOSIP_CALL_MESSAGE_ANSWERED,EXOSIP_CALL_MESSAGE_REDIRECTED,EXOSIP_CALL_MESSAGE_REQUESTFAILURE,EXO
44、SIP_CALL_MESSAGE_SERVERFAILURE,EXOSIP_CALL_MESSAGE_GLOBALFAILURE,EXOSIP_CALL_CLOSED,EXOSIP_CALL_RELEASED,EXOSIP_MESSAGE_NEW,EXOSIP_MESSAGE_PROCEEDING,EXOSIP_MESSAGE_ANSWERED,EXOSIP_MESSAGE_REDIRECTED,EXOSIP_MESSAGE_REQUESTFAILURE,EXOSIP_MESSAGE_SERVERFAILURE,EXOSIP_MESSAGE_GLOBALFAILURE,EXOSIP_SUBSC
45、RIPTION_UPDATE,EXOSIP_SUBSCRIPTION_CLOSED,EXOSIP_SUBSCRIPTION_NOANSWER,EXOSIP_SUBSCRIPTION_PROCEEDING,EXOSIP_SUBSCRIPTION_ANSWERED,EXOSIP_SUBSCRIPTION_REDIRECTED,EXOSIP_SUBSCRIPTION_REQUESTFAILURE,EXOSIP_SUBSCRIPTION_SERVERFAILURE,EXOSIP_SUBSCRIPTION_GLOBALFAILURE,EXOSIP_SUBSCRIPTION_NOTIFY,EXOSIP_S
46、UBSCRIPTION_RELEASED,EXOSIP_IN_SUBSCRIPTION_NEW,EXOSIP_IN_SUBSCRIPTION_RELEASED,EXOSIP_NOTIFICATION_NOANSWER,EXOSIP_NOTIFICATION_PROCEEDING,EXOSIP_NOTIFICATION_ANSWERED,EXOSIP_NOTIFICATION_REDIRECTED,EXOSIP_NOTIFICATION_REQUESTFAILURE,EXOSIP_NOTIFICATION_SERVERFAILURE,EXOSIP_NOTIFICATION_GLOBALFAILU
47、RE,EXOSIP_EVENT_COUNT2.3.3 Functionsvoid eXosip_event_free (eXosip_event_t *je)eXosip_event_t * eXosip_event_wait (int tv_s, int tv_ms)eXosip_event_t * eXosip_event_get (void)2.3.4 Enumeration Type Documentationenum eXosip_event_typeStructure for event type descriptionEnumerator:EXOSIP_REGISTRATION_
48、NEW announce new registration.EXOSIP_REGISTRATION_SUCCESS user is successfully registred.EXOSIP_REGISTRATION_FAILURE user is not registred.EXOSIP_REGISTRATION_REFRESHED registration has been refreshed.EXOSIP_REGISTRATION_TERMINATED UA is not registred any more.EXOSIP_CALL_INVITE announce a new callE
49、XOSIP_CALL_REINVITE announce a new INVITE withincallEXOSIP_CALL_NOANSWER announce no answer within thetimeoutEXOSIP_CALL_PROCEEDING announce processing by aremote appEXOSIP_CALL_RINGING announce ringbackEXOSIP_CALL_ANSWERED announce start of callEXOSIP_CALL_REDIRECTED announce a redirectionEXOSIP_CALL_REQUESTFAILURE announce a request failureEXOSIP_CALL_SERVERFAILURE announce a server failureEXOSIP_CALL_GLOBALFAILURE announce a global fai
