4 * @see http://www.linphone.org
6 * @section what_is_it What is liblinphone
8 * Liblinphone is a high level library for bringing SIP video call functionnality
9 * into an application. It aims at making easy the integration of the SIP
10 * video calls into any applications. All variants of linphone are directly based
12 * - linphone (gtk interface)
13 * - linphonec (console interface)
15 * - linphone for Android
17 * Liblinphone is GPL (see COPYING file). Please understand the licencing details
20 * For any use of this library beyond the rights granted to you by the
21 * GPL license, please contact Belledonne Communications
22 * (contact@belledonne-communications.com)
28 * @page liblinphone_license COPYING
33 * @defgroup initializing Initializing liblinphone
37 * @defgroup call_control Placing and receiving calls
39 * The #LinphoneCall object represents an incoming or outgoing call managed by the #LinphoneCore.
40 * Outgoing calls can be created using linphone_core_invite() or linphone_core_invite_address(), while incoming calls are notified to the application
41 * through the LinphoneCoreVTable::call_state_changed callback.
43 * See the basic call \ref basic_call_tutorials "tutorial".
48 * @defgroup call_misc Obtaining information about a running call: sound volumes, quality indicators
50 * When a call is running, it is possible to retrieve in real time current measured volumes and quality indicator.
55 * @defgroup media_parameters Controlling media parameters
59 * @defgroup proxies Managing proxies
60 *User registration is controled by #LinphoneProxyConfig settings.<br> Each #LinphoneProxyConfig object can be configured with registration informations
61 *like \link linphone_proxy_config_set_server_addr() proxy address \endlink , \link linphone_proxy_config_set_identity() user id \endlink, \link linphone_proxy_config_expires() refresh period \endlink, and so on.
62 *<br> A created proxy config using linphone_proxy_config_new(), once configured, must be added to #LinphoneCore using function linphone_core_add_proxy_config().
63 *<br> It is recommended to set a default \link #LinphoneProxyConfig proxy config \endlink using function linphone_core_set_default_proxy(). Once done, if \link #LinphoneProxyConfig a proxy config \endlink has been configured with attribute \link linphone_proxy_config_enable_register() enable register \endlink , next call to linphone_core_iterate() triggers a SIP register.
64 *<br> Registration status is reported by #LinphoneRegistrationStateCb.
66 *<br> This pseudo code demonstrates basic registration operations:
69 * LinphoneProxyConfig* proxy_cfg;
70 * /*create proxy config*/
71 * proxy_cfg = linphone_proxy_config_new();
73 * LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com");
74 * LinphoneAuthInfo *info;
75 * if (password!=NULL){
76 * info=linphone_auth_info_new(linphone_address_get_username(from),NULL,"secret",NULL,NULL); /*create authentication structure from identity*/
77 * linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/
79 * // configure proxy entries
80 * linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/
81 * const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/
82 * linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/
83 * linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/
84 * linphone_address_destroy(from); /*release resource*/
86 * linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/
87 * linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/ \endcode
89 * Registration sate call back:
91 static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){
92 printf("New registration state %s for user id [%s] at proxy [%s]\n"
93 ,linphone_registration_state_to_string(cstate)
94 ,linphone_proxy_config_get_identity(cfg)
95 ,linphone_proxy_config_get_addr(cfg));
98 *<br><b>Authentication:</b>
99 *<br>Most of the time, registration requires \ref authentication "authentication" to succed. #LinphoneAuthInfo info must be either added to #LinphoneCore using function linphone_core_add_auth_info() before #LinphoneProxyConfig is added to Linphone core, or on demand from call back #AuthInfoRequested .
101 *<br><b>Unregistration:</b>
102 *<br> Unregistration or any changes to #LinphoneProxyConfig must be first started by a call to function linphone_proxy_config_edit() and validated by function linphone_proxy_config_done()
103 *<br> This pseudo code shows how to unregister a user associated to a #LinphoneProxyConfig
105 LinphoneProxyConfig* proxy_cfg;
106 linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
107 linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
108 linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
109 linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/
112 A complete tutorial can be found at : \ref registration_tutorials "Registration tutorial"
116 * @defgroup network_parameters Controlling network parameters (ports, mtu...)
120 * @defgroup authentication Managing authentication: userid and passwords
124 * @defgroup buddy_list Managing Buddies and buddy list and presence
125 <b>Buddies and buddy list</b>
126 <br>Each buddy is represented by a #LinphoneFriend object created by function linphone_friend_new().
127 Buddy configuration parameters like \link linphone_friend_set_addr() sip uri \endlink or \link linphone_friend_set_inc_subscribe_policy() status publication \endlink policy for this \link #LinphoneFriend friend \endlink are configurable for each buddy.
128 <br>Here under a typical buddy creation:
131 LinphoneFriend* my_friend=linphone_friend_new_with_addr("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
132 linphone_friend_enable_subscribes(my_friend,TRUE); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
133 linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/
135 \link #LinphoneFriend friends \endlink status changes are reported by callback LinphoneCoreVTable.notify_presence_recv
137 static void notify_presence_recv_updated (struct _LinphoneCore *lc, LinphoneFriend *friend) {
138 const LinphoneAddress* friend_address = linphone_friend_get_address(friend);
139 printf("New state state [%s] for user id [%s] \n"
140 ,linphone_online_status_to_string(linphone_friend_get_status(friend))
141 ,linphone_address_as_string (friend_address));
144 <br>Once created a buddy can be added to the buddy list using function linphone_core_add_friend() . Added friends will be notified about \link linphone_core_set_presence_info() local status changes \endlink
146 Any subsequente modifications to #LinphoneFriend must be first started by a call to function linphone_friend_edit() and validated by function linphone_friend_done()
148 linphone_friend_edit(my_friend); /* start editing friend */
149 linphone_friend_enable_subscribes(my_friend,FALSE); /*disable subscription for this friend*/
150 linphone_friend_done(my_friend); /*commit changes triggering an UNSUBSCRIBE message*/
154 <b> Publishing presence status </b>
155 <br>Local presence status can be changed using function linphone_core_set_presence_info() .New status is propagated to all friends \link linphone_core_add_friend() previously added \endlink to #LinphoneCore.
157 <b>Handling incoming subscription request</b>
158 <br> New incoming subscription requests are process according to \link linphone_friend_set_inc_subscribe_policy() the incoming subscription policy state \endlink for subscription initiated by \link linphone_core_add_friend() members of the buddy list. \endlink
159 <br> For incoming request comming from an unknown buddy, the call back LinphoneCoreVTable.new_subscription_request is invoked.
161 <br> A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial"
167 * @defgroup chatroom Chat room and Messaging
168 <b> Exchanging text messages</b>
169 <br> Messages are sent using #LinphoneChatRoom object. First step is to create a \link linphone_core_create_chat_room() chat room \endlink
172 LinphoneChatRoom* chat_room = linphone_core_create_chat_room(lc,"sip:joe@sip.linphone.org");
175 <br>Once created, messages are sent using function linphone_chat_room_send_message() .
177 linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/
179 <br>Incoming message are received from call back LinphoneCoreVTable.text_received
181 void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message) {
182 printf(" Message [%s] received from [%s] \n",message,linphone_address_as_string (from));
185 <br> A complete tutorial can be found at : \ref chatroom_tuto "Chat room tutorial"
189 * @defgroup call_logs Managing call logs
194 * @defgroup linphone_address SIP address parser API.
195 * This api is useful for manipulating SIP addresses ('from' or 'to' headers).
199 * @defgroup conferencing Making an audio conference.
200 * This API allows to create a conference entirely managed by the client. No server capabilities are required.
201 * The way such conference is created is by doing the following:<br>
202 * The application shall makes "normal" calls to several destinations (using linphone_core_invite() ), one after another.
203 * While initiating the second call, the first one is automatically paused.
204 * Then, once the second call is established, the application has the possibility to merge the two calls to form a conference where each participant
205 * (the local participant, the remote destination of the first call, the remote destination of the second call) can talk together.
206 * This must be done by adding the two calls to the conference using \link linphone_call_add_to_conference() \endlink
208 * Once merged into a conference the LinphoneCall objects representing the calls that were established remain unchanged, except that
209 * they are tagged as part of the conference (see \link linphone_call_is_in_conference() \endlink ). The calls in a conference are in the LinphoneCallStreamsRunning state.
211 * Only a single conference can be created: the purpose of this feature is to allow the local user to create, take part and manage the conference.
212 * This API is not designed to create a conference server application.
214 * Up to 10 calls can be merged into the conference, however depending on the CPU usage required for doing the encoding/decoding of the streams of each participants,
215 * the effective limit can be lower.
220 * @defgroup misc Miscenalleous: logs, version strings, config storage
224 * @defgroup tutorials Tutorials:
229 * @defgroup port Portability:
237 <br> Liblinphone for IOS natively supports multitasking assuming application follows multitasking guides provided by Apple. First step is to declare application as multitasked. It means adding background mode for both audio and voip to Info.plist file.
240 <key>UIBackgroundModes</key>
242 <string>voip</string>
243 <string>audio</string>
248 <li><b>SIP socket </b><br>Recommended mode is SIP over TCP, because UDP usually requires frequent keep alives for maintaining NAT association at the IP router level. This can be as frequent as one UDP packet every 15 seconds to maintain the NAT association accross NAT routers. Doing such drains the battery very fast, and furthermore the iOS keep-alive designed by Apple to handle this task can only be called with a minimum of 10 minutes interval.<br>
249 For TCP, liblinphone automatically configures SIP socket for voip (I.E kCFStreamNetworkServiceType set to kCFStreamNetworkServiceTypeVoIP).
250 <br><b>Since IOS > 4.1 Apple disabled voip mode for UDP sockets </b>
251 <li><b>Entering background mode</b>
252 <br> Before entering in background mode (through \code - (void)applicationDidEnterBackground:(UIApplication *)application \endcode ), the application must first refresh sip registration using function #linphone_core_refresh_registers();
253 and register a keep-alive handler for periodically refreshing the registration. The speudo code below shows how to register a keep alive handler:
255 //First refresh registration
256 linphone_core_refresh_registers(theLinphoneCore);
257 //wait for registration answer
259 while (!linphone_proxy_config_is_registered(proxyCfg) && i++<40 ) {
260 linphone_core_iterate(theLinphoneCore);
263 //register keepalive handler
264 [[UIApplication sharedApplication] setKeepAliveTimeout:600/*minimal interval is 600 s*/
266 //refresh sip registration
267 linphone_core_refresh_registers(theLinphoneCore);
268 //make sure sip REGISTER is sent
269 linphone_core_iterate(theLinphoneCore);
272 <li><b>Incoming call notification while in background mode</b>
273 <br>Assuming application using liblinphone is well configured for multitasking, incoming calls arriving while liblinphone is in background mode will simply wakeup liblinphone thread but not resume GUI. To wakeup GUI, it is recommended to send a Local Notification to the user from the #LinphoneCallStateCb. Here under a speudo code for this operation:
275 if ([UIApplication sharedApplication].applicationState != UIApplicationStateActive) {
276 // Create a new notification
277 UILocalNotification* notif = [[[UILocalNotification alloc] init] autorelease];
279 notif.repeatInterval = 0;
280 notif.alertBody =@"New incoming call";
281 notif.alertAction = @"Answer";
282 notif.soundName = @"oldphone-mono-30s.caf";
284 [[UIApplication sharedApplication] presentLocalNotificationNow:notif];
290 <ul><li><b>WWAN connection</b>
291 <br>Liblinphone relies on iOS's standard BSD socket layer for sip/rtp networking. On IOS, WWAN connection is supposed to automatically bring up on any networking resquest issued by an application. At least on iPhone OS 3.x, BSD sockets do not implement this behavior. So it is recomended to add a special code to make sure the WWAN connection is properly setup. Pseudo code below describes a way to force WWAN connection by setting up a dummy TCP connection.
293 /*start a new thread to avoid blocking the main ui in case of peer host failure*/
294 [NSThread detachNewThreadSelector:@selector(runNetworkConnection) toTarget:self withObject:nil];
295 -(void) runNetworkConnection {
296 CFWriteStreamRef writeStream;
297 //create a dummy socket
298 CFStreamCreatePairWithSocketToHost(NULL, (CFStringRef)@"192.168.0.200", 15000, nil, &writeStream);
299 CFWriteStreamOpen (writeStream);
300 const char* buff="hello";
301 //try to write on this socket
302 CFWriteStreamWrite (writeStream,(const UInt8*)buff,strlen(buff));
303 CFWriteStreamClose (writeStream);
306 It is recommanded to perform this task each time the application is woken up, including keep alive handler.
307 <li><b>Managing IP connection state</b>
308 <br>Liblinphone for IOS relies on the application to be informed of network connectivity changes. Network state changes when the IP connection moves from DOWN to UP, or from WIFI to WWAN. Applications using liblinphone must inform libliblinphone of this changes using function #linphone_core_set_network_reachable(). Usually this method is called from the IOS NetworkReachability callback. Here under a sample code:
310 //typical reachability callback
311 void networkReachabilityCallBack(SCNetworkReachabilityRef target, SCNetworkReachabilityFlags flags, void * info) {
312 if ((flags == 0) | (flags & (kSCNetworkReachabilityFlagsConnectionRequired |kSCNetworkReachabilityFlagsConnectionOnTraffic))) {
313 //network state is off
314 linphone_core_set_network_reachable(lc,false);
315 ((LinphoneManager*)info).connectivity = none;
317 Connectivity newConnectivity = flags & kSCNetworkReachabilityFlagsIsWWAN ? wwan:wifi;
318 if (lLinphoneMgr.connectivity == none) {
319 //notify new network state
320 linphone_core_set_network_reachable(lc,true);
321 } else if (lLinphoneMgr.connectivity != newConnectivity) {
322 // connectivity has changed
323 linphone_core_set_network_reachable(lc,false);
324 linphone_core_set_network_reachable(lc,true);
326 //store new connectivity status
327 lLinphoneMgr.connectivity=newConnectivity;
335 <br> Since IOS 5.0, liblinphone supports 2 sound cards. <i>AU: Audio Unit Receiver</i> based on IO units for voice calls plus <i>AQ: Audio Queue Device</i> dedicated to rings. Here under the recommended settings (I.E default one)
337 linphone_core_set_playback_device(lc, "AU: Audio Unit Receiver");
338 linphone_core_set_ringer_device(lc, "AQ: Audio Queue Device");
339 linphone_core_set_capture_device(lc, "AU: Audio Unit Receiver");
341 <b> GSM call interaction </b>
342 <br> To ensure gentle interaction with GSM calls, it is recommended to register an AudioSession delegate. This allows the application to be notified when its audio session is interrupted/resumed (presumably by a GSM call).
344 // declare a class handling the AVAudioSessionDelegate protocol
345 @interface MyClass : NSObject <AVAudioSessionDelegate> { [...] }
346 // implement 2 methods : here's an example implementation
347 -(void) beginInterruption {
348 LinphoneCall* c = linphone_core_get_current_call(theLinphoneCore);
349 ms_message("Sound interruption detected!");
351 linphone_core_pause_call(theLinphoneCore, c);
355 -(void) endInterruption {
356 ms_message("Sound interruption ended!");
357 const MSList* c = linphone_core_get_calls(theLinphoneCore);
360 ms_message("Auto resuming call");
361 linphone_core_resume_call(theLinphoneCore, (LinphoneCall*) c->data);
365 @see http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSessionDelegate_ProtocolReference/Reference/Reference.html
367 <br> Declare an instance of your class as AudioSession's delegate :
369 [audioSession setDelegate:myClassInstance];
371 @see http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSession_ClassReference/Reference/Reference.html
374 <br>Since 3.5 video support has been added to liblinphone for IOS. It requires the application to provide liblinphone with pointers to IOS's views hosting video display and video previous.
375 <br> These 2 UIView objects must be passed to the core using functions #linphone_core_set_native_video_window_id() and #linphone_core_set_native_preview_window_id(). here under speudo code:
377 UIView* display = [[UIView alloc] init];
378 UIView* preview = [[UIView alloc] init];
379 linphone_core_set_native_video_window_id(lc,(unsigned long)display);
380 linphone_core_set_native_preview_window_id(lc,(unsigned long)preview);
382 <br> Screen rotations are also handled by liblinphone. 2 positions are currently supported, namely <i>UIInterfaceOrientationPortrait</i> and <i>UIInterfaceOrientationLandscapeRight</i>. Applications may invoke #linphone_core_set_device_rotation() followed by #linphone_core_update_call() to notify liblinphone of an orientation change. Here under a speudo code to handle orientation changes
385 -(void) configureOrientation:(UIInterfaceOrientation) oritentation {
386 int oldLinphoneOrientation = linphone_core_get_device_rotation(lc);
387 if (oritentation == UIInterfaceOrientationPortrait ) {
388 linphone_core_set_native_video_window_id(lc,(unsigned long)display-portrait);
389 linphone_core_set_native_preview_window_id(lc,(unsigned long)preview-portrait);
390 linphone_core_set_device_rotation(lc, 0);
392 } else if (oritentation == UIInterfaceOrientationLandscapeRight ) {
393 linphone_core_set_native_video_window_id(lc,(unsigned long)display-landscape);
394 linphone_core_set_native_preview_window_id(lc,(unsigned long)preview-landscape);
395 linphone_core_set_device_rotation(lc, 270);
398 if ((oldLinphoneOrientation != linphone_core_get_device_rotation(lc))
399 && linphone_core_get_current_call(lc)) {
400 //Orientation has changed, must call update call
401 linphone_core_update_call(lc, linphone_core_get_current_call(lc), NULL);
408 <br>Liblinphone provides functions \link #linphone_core_play_dtmf() to play dtmf \endlink to the local user. Usually this is used to play a sound when the user presses a digit, inside or outside of any call. On IOS, libLinphone relies on AudioUnits for interfacing with the audio system. Unfortunately the Audio Unit initialization is a quite long operation that may trigger a bad user experience if performed each time a DTMF is played, the sound being delayed half a second after the press. To solve this issue and thus insure real-time precision, liblinphone introduces 2 functions for \link linphone_core_start_dtmf_stream() preloading \endlink and \link #linphone_core_start_dtmf_stream() unloading \endlink the underlying audio graph responsible for playing DTMFs.
409 <br> For an application using function #linphone_core_play_dtmf(), it is recommanded to call #linphone_core_start_dtmf_stream() when entering in foreground and #linphone_core_stop_dtmf_stream() upon entering background mode.