/** * @mainpage * * @see http://www.linphone.org * * @section what_is_it What is liblinphone * * Liblinphone is a high level library for bringing SIP video call functionnality * into an application. It aims at making easy the integration of the SIP * video calls into any applications. All variants of linphone are directly based * on it: * - linphone (gtk interface) * - linphonec (console interface) * - linphone for iOS * - linphone for Android * * Liblinphone is GPL (see COPYING file). Please understand the licencing details * before using it! * * For any use of this library beyond the rights granted to you by the * GPL license, please contact Belledonne Communications * (contact@belledonne-communications.com) * * **/ /** * @page liblinphone_license COPYING * @include COPYING */ /** * @defgroup initializing Initializing liblinphone **/ /** * @defgroup call_control Placing and receiving calls * * The #LinphoneCall object represents an incoming or outgoing call managed by the #LinphoneCore. * Outgoing calls can be created using linphone_core_invite() or linphone_core_invite_address(), while incoming calls are notified to the application * through the LinphoneCoreVTable::call_state_changed callback. * * See the basic call \ref basic_call_tutorials "tutorial". * **/ /** * @defgroup call_misc Obtaining information about a running call: sound volumes, quality indicators * * When a call is running, it is possible to retrieve in real time current measured volumes and quality indicator. * **/ /** * @defgroup media_parameters Controlling media parameters **/ /** * @defgroup proxies Managing proxies *User registration is controled by #LinphoneProxyConfig settings.
Each #LinphoneProxyConfig object can be configured with registration informations *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. *
A created proxy config using linphone_proxy_config_new(), once configured, must be added to #LinphoneCore using function linphone_core_add_proxy_config(). *
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. *
Registration status is reported by #LinphoneRegistrationStateCb. *
*
This pseudo code demonstrates basic registration operations: *
\code * * LinphoneProxyConfig* proxy_cfg; * /*create proxy config*/ * proxy_cfg = linphone_proxy_config_new(); * /*parse identity*/ * LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com"); * LinphoneAuthInfo *info; * if (password!=NULL){ * info=linphone_auth_info_new(linphone_address_get_username(from),NULL,"secret",NULL,NULL); /*create authentication structure from identity*/ * linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/ * } * // configure proxy entries * linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/ * const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/ * linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/ * linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/ * linphone_address_destroy(from); /*release resource*/ * * linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/ * linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/ \endcode *
* Registration sate call back: \code static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){ printf("New registration state %s for user id [%s] at proxy [%s]\n" ,linphone_registration_state_to_string(cstate) ,linphone_proxy_config_get_identity(cfg) ,linphone_proxy_config_get_addr(cfg)); } \endcode *
Authentication: *
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 . *
*
Unregistration: *
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() *
This pseudo code shows how to unregister a user associated to a #LinphoneProxyConfig *\code LinphoneProxyConfig* proxy_cfg; linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/ linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/ linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/ linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/ \endcode
A complete tutorial can be found at : \ref registration_tutorials "Registration tutorial" **/ /** * @defgroup network_parameters Controlling network parameters (ports, mtu...) **/ /** * @defgroup authentication Managing authentication: userid and passwords **/ /** * @defgroup buddy_list Managing Buddies and buddy list and presence Buddies and buddy list
Each buddy is represented by a #LinphoneFriend object created by function linphone_friend_new(). 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.
Here under a typical buddy creation:
\code LinphoneFriend* my_friend=linphone_friend_new_with_addr("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/ linphone_friend_enable_subscribes(my_friend,TRUE); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/ linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/ \endcode \link #LinphoneFriend friends \endlink status changes are reported by callback LinphoneCoreVTable.notify_presence_recv \code static void notify_presence_recv_updated (struct _LinphoneCore *lc, LinphoneFriend *friend) { const LinphoneAddress* friend_address = linphone_friend_get_address(friend); printf("New state state [%s] for user id [%s] \n" ,linphone_online_status_to_string(linphone_friend_get_status(friend)) ,linphone_address_as_string (friend_address)); } \endcode
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
Any subsequente modifications to #LinphoneFriend must be first started by a call to function linphone_friend_edit() and validated by function linphone_friend_done() \code linphone_friend_edit(my_friend); /* start editing friend */ linphone_friend_enable_subscribes(my_friend,FALSE); /*disable subscription for this friend*/ linphone_friend_done(my_friend); /*commit changes triggering an UNSUBSCRIBE message*/ \endcode Publishing presence status
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. Handling incoming subscription request
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
For incoming request comming from an unknown buddy, the call back LinphoneCoreVTable.new_subscription_request is invoked.
A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial" **/ /** * @defgroup chatroom Chat room and Messaging Exchanging text messages
Messages are sent using #LinphoneChatRoom object. First step is to create a \link linphone_core_create_chat_room() chat room \endlink from a peer sip uri. \code LinphoneChatRoom* chat_room = linphone_core_create_chat_room(lc,"sip:joe@sip.linphone.org"); \endcode
Once created, messages are sent using function linphone_chat_room_send_message() . \code linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/ \endcode
Incoming message are received from call back LinphoneCoreVTable.text_received \code void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message) { printf(" Message [%s] received from [%s] \n",message,linphone_address_as_string (from)); } \endcode
A complete tutorial can be found at : \ref chatroom_tuto "Chat room tutorial" **/ /** * @defgroup call_logs Managing call logs **/ /** * @defgroup linphone_address SIP address parser API. * This api is useful for manipulating SIP addresses ('from' or 'to' headers). **/ /** * @defgroup conferencing Making an audio conference. * This API allows to create a conference entirely managed by the client. No server capabilities are required. * The way such conference is created is by doing the following:
* The application shall makes "normal" calls to several destinations (using linphone_core_invite() ), one after another. * While initiating the second call, the first one is automatically paused. * Then, once the second call is established, the application has the possibility to merge the two calls to form a conference where each participant * (the local participant, the remote destination of the first call, the remote destination of the second call) can talk together. * This must be done by adding the two calls to the conference using \link linphone_call_add_to_conference() \endlink * * Once merged into a conference the LinphoneCall objects representing the calls that were established remain unchanged, except that * 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. * * 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. * This API is not designed to create a conference server application. * * 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, * the effective limit can be lower. * **/ /** * @defgroup misc Miscenalleous: logs, version strings, config storage **/ /** * @defgroup tutorials Tutorials: * **/ /** * @defgroup port Portability: * **/ /** * @defgroup IOS IOS * @ingroup port *
Multitasking
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.
\code UIBackgroundModes voip audio \endcode
Networking
Sound cards
Since IOS 5.0, liblinphone supports 2 sound cards. AU: Audio Unit Receiver based on IO units for voice calls plus AQ: Audio Queue Device dedicated to rings. Here under the recommended settings (I.E default one) \code linphone_core_set_playback_device(lc, "AU: Audio Unit Receiver"); linphone_core_set_ringer_device(lc, "AQ: Audio Queue Device"); linphone_core_set_capture_device(lc, "AU: Audio Unit Receiver"); \endcode GSM call interaction
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). \code // declare a class handling the AVAudioSessionDelegate protocol @interface MyClass : NSObject { [...] } // implement 2 methods : here's an example implementation -(void) beginInterruption { LinphoneCall* c = linphone_core_get_current_call(theLinphoneCore); ms_message("Sound interruption detected!"); if (c) { linphone_core_pause_call(theLinphoneCore, c); } } -(void) endInterruption { ms_message("Sound interruption ended!"); const MSList* c = linphone_core_get_calls(theLinphoneCore); if (c) { ms_message("Auto resuming call"); linphone_core_resume_call(theLinphoneCore, (LinphoneCall*) c->data); } } \endcode @see http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSessionDelegate_ProtocolReference/Reference/Reference.html
Declare an instance of your class as AudioSession's delegate : \code [audioSession setDelegate:myClassInstance]; \endcode @see http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSession_ClassReference/Reference/Reference.html Video
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.
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: \code UIView* display = [[UIView alloc] init]; UIView* preview = [[UIView alloc] init]; linphone_core_set_native_video_window_id(lc,(unsigned long)display); linphone_core_set_native_preview_window_id(lc,(unsigned long)preview); \endcode
Screen rotations are also handled by liblinphone. 2 positions are currently supported, namely UIInterfaceOrientationPortrait and UIInterfaceOrientationLandscapeRight. 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 \code -(void) configureOrientation:(UIInterfaceOrientation) oritentation { int oldLinphoneOrientation = linphone_core_get_device_rotation(lc); if (oritentation == UIInterfaceOrientationPortrait ) { linphone_core_set_native_video_window_id(lc,(unsigned long)display-portrait); linphone_core_set_native_preview_window_id(lc,(unsigned long)preview-portrait); linphone_core_set_device_rotation(lc, 0); } else if (oritentation == UIInterfaceOrientationLandscapeRight ) { linphone_core_set_native_video_window_id(lc,(unsigned long)display-landscape); linphone_core_set_native_preview_window_id(lc,(unsigned long)preview-landscape); linphone_core_set_device_rotation(lc, 270); } if ((oldLinphoneOrientation != linphone_core_get_device_rotation(lc)) && linphone_core_get_current_call(lc)) { //Orientation has changed, must call update call linphone_core_update_call(lc, linphone_core_get_current_call(lc), NULL); } } \endcode DTMF feebacks
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.
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. */