<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>liblinphone: IOS</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">liblinphone
 <span id="projectnumber">3.5.2</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">IOS</div> </div>
<div class="ingroups"><a class="el" href="group__port.html">Portability:</a></div></div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gaef3c840b3c9f576c642b49cf306c7461"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__IOS.html#gaef3c840b3c9f576c642b49cf306c7461">linphone_core_start_dtmf_stream</a> (<a class="el" href="group__initializing.html#gaa5cf635b82dd338e7ee2dd3599d05f0a">LinphoneCore</a> *lc)</td></tr>
<tr class="memitem:gad0ecef2fb7a77c3363aa94edeadaf65b"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__IOS.html#gad0ecef2fb7a77c3363aa94edeadaf65b">linphone_core_stop_dtmf_stream</a> (<a class="el" href="group__initializing.html#gaa5cf635b82dd338e7ee2dd3599d05f0a">LinphoneCore</a> *lc)</td></tr>
</table>
<a name="details" id="details"></a><h2>Detailed Description</h2>
<p><br/>
<b>Multitasking</b> <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. <br/>
</p>
<div class="fragment"><div class="line"><key>UIBackgroundModes</key></div>
<div class="line"><array></div>
<div class="line"> <<span class="keywordtype">string</span>>voip</<span class="keywordtype">string</span>></div>
<div class="line"> <<span class="keywordtype">string</span>>audio</<span class="keywordtype">string</span>></div>
<div class="line"></array></div>
</div><!-- fragment --><p> <br/>
</p>
<ul>
<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/>
For TCP, liblinphone automatically configures SIP socket for voip (I.E kCFStreamNetworkServiceType set to kCFStreamNetworkServiceTypeVoIP). <br/>
<b>Since IOS > 4.1 Apple disabled voip mode for UDP sockets </b> </li>
<li>
<b>Entering background mode</b> <br/>
Before entering in background mode (through <div class="fragment"><div class="line">- (void)applicationDidEnterBackground:(UIApplication *)application </div>
</div><!-- fragment --> ), the application must first refresh sip registration using function <a class="el" href="group__proxies.html#ga130795ea67730f7b01f7b51fe6bdb44f">linphone_core_refresh_registers()</a>; and register a keep-alive handler for periodically refreshing the registration. The speudo code below shows how to register a keep alive handler: <div class="fragment"><div class="line"><span class="comment">//First refresh registration</span></div>
<div class="line"><a class="code" href="group__proxies.html#ga130795ea67730f7b01f7b51fe6bdb44f">linphone_core_refresh_registers</a>(theLinphoneCore);</div>
<div class="line"><span class="comment">//wait for registration answer</span></div>
<div class="line"><span class="keywordtype">int</span> i=0;</div>
<div class="line"><span class="keywordflow">while</span> (!<a class="code" href="group__proxies.html#gaed2155106b24f7e418b67c2774b6a0c7">linphone_proxy_config_is_registered</a>(proxyCfg) && i++<40 ) {</div>
<div class="line"> <a class="code" href="group__initializing.html#ga7bdac8ac386483fc4e0876e4c5d13755">linphone_core_iterate</a>(theLinphoneCore);</div>
<div class="line"> usleep(100000);</div>
<div class="line">}</div>
<div class="line"><span class="comment">//register keepalive handler</span></div>
<div class="line">[[UIApplication sharedApplication] setKeepAliveTimeout:600<span class="comment">/*minimal interval is 600 s*/</span> </div>
<div class="line"> handler:^{</div>
<div class="line"> <span class="comment">//refresh sip registration</span></div>
<div class="line"> <a class="code" href="group__proxies.html#ga130795ea67730f7b01f7b51fe6bdb44f">linphone_core_refresh_registers</a>(theLinphoneCore);</div>
<div class="line"> <span class="comment">//make sure sip REGISTER is sent</span></div>
<div class="line"> <a class="code" href="group__initializing.html#ga7bdac8ac386483fc4e0876e4c5d13755">linphone_core_iterate</a>(theLinphoneCore);</div>
<div class="line"> }];</div>
</div><!-- fragment --> </li>
<li>
<b>Incoming call notification while in background mode</b> <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 <a class="el" href="group__initializing.html#gacf692730f4aceefa92422d128cc4c069">LinphoneCallStateCb</a>. Here under a speudo code for this operation: <div class="fragment"><div class="line"><span class="keywordflow">if</span> ([UIApplication sharedApplication].applicationState != UIApplicationStateActive) {</div>
<div class="line"> <span class="comment">// Create a new notification</span></div>
<div class="line"> UILocalNotification* notif = [[[UILocalNotification alloc] init] autorelease];</div>
<div class="line"> <span class="keywordflow">if</span> (notif) {</div>
<div class="line"> notif.repeatInterval = 0;</div>
<div class="line"> notif.alertBody =<span class="stringliteral">@"New incoming call"</span>;</div>
<div class="line"> notif.alertAction = <span class="stringliteral">@"Answer"</span>;</div>
<div class="line"> notif.soundName = <span class="stringliteral">@"oldphone-mono-30s.caf"</span>;</div>
<div class="line"> </div>
<div class="line"> [[UIApplication sharedApplication] presentLocalNotificationNow:notif];</div>
<div class="line"> }</div>
</div><!-- fragment --> </li>
</ul>
<p><b>Networking</b> <br/>
</p>
<ul>
<li>
<b>WWAN connection</b> <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. <div class="fragment"><div class="line"><span class="comment">/*start a new thread to avoid blocking the main ui in case of peer host failure*/</span></div>
<div class="line">[NSThread detachNewThreadSelector:<span class="keyword">@selector</span>(runNetworkConnection) toTarget:<span class="keyword">self</span> withObject:nil];</div>
<div class="line">-(void) runNetworkConnection {</div>
<div class="line"> CFWriteStreamRef writeStream;</div>
<div class="line"> <span class="comment">//create a dummy socket</span></div>
<div class="line"> CFStreamCreatePairWithSocketToHost(NULL, (CFStringRef)<span class="stringliteral">@"192.168.0.200"</span>, 15000, nil, &writeStream);</div>
<div class="line"> CFWriteStreamOpen (writeStream);</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span>* buff=<span class="stringliteral">"hello"</span>;</div>
<div class="line"> <span class="comment">//try to write on this socket</span></div>
<div class="line"> CFWriteStreamWrite (writeStream,(<span class="keyword">const</span> UInt8*)buff,strlen(buff));</div>
<div class="line"> CFWriteStreamClose (writeStream);</div>
<div class="line">} </div>
</div><!-- fragment --> It is recommanded to perform this task each time the application is woken up, including keep alive handler. </li>
<li>
<b>Managing IP connection state</b> <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 <a class="el" href="group__network__parameters.html#ga50986600d8f528e083a2c8e6269734e3">linphone_core_set_network_reachable()</a>. Usually this method is called from the IOS NetworkReachability callback. Here under a sample code: <div class="fragment"><div class="line"><span class="comment">//typical reachability callback</span></div>
<div class="line"><span class="keywordtype">void</span> networkReachabilityCallBack(SCNetworkReachabilityRef target, SCNetworkReachabilityFlags flags, <span class="keywordtype">void</span> * info) {</div>
<div class="line"> <span class="keywordflow">if</span> ((flags == 0) | (flags & (kSCNetworkReachabilityFlagsConnectionRequired |kSCNetworkReachabilityFlagsConnectionOnTraffic))) {</div>
<div class="line"> <span class="comment">//network state is off</span></div>
<div class="line"> <a class="code" href="group__network__parameters.html#ga50986600d8f528e083a2c8e6269734e3">linphone_core_set_network_reachable</a>(lc,<span class="keyword">false</span>);</div>
<div class="line"> ((LinphoneManager*)info).connectivity = none;</div>
<div class="line"> } <span class="keywordflow">else</span> {</div>
<div class="line"> Connectivity newConnectivity = flags & kSCNetworkReachabilityFlagsIsWWAN ? wwan:wifi;</div>
<div class="line"> <span class="keywordflow">if</span> (lLinphoneMgr.connectivity == none) {</div>
<div class="line"> <span class="comment">//notify new network state</span></div>
<div class="line"> <a class="code" href="group__network__parameters.html#ga50986600d8f528e083a2c8e6269734e3">linphone_core_set_network_reachable</a>(lc,<span class="keyword">true</span>);</div>
<div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (lLinphoneMgr.connectivity != newConnectivity) {</div>
<div class="line"> <span class="comment">// connectivity has changed</span></div>
<div class="line"> <a class="code" href="group__network__parameters.html#ga50986600d8f528e083a2c8e6269734e3">linphone_core_set_network_reachable</a>(lc,<span class="keyword">false</span>);</div>
<div class="line"> <a class="code" href="group__network__parameters.html#ga50986600d8f528e083a2c8e6269734e3">linphone_core_set_network_reachable</a>(lc,<span class="keyword">true</span>);</div>
<div class="line"> }</div>
<div class="line"> <span class="comment">//store new connectivity status</span></div>
<div class="line"> lLinphoneMgr.connectivity=newConnectivity;</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --> </li>
</ul>
<p><b> Sound cards </b> <br/>
Since IOS 5.0, liblinphone supports 2 sound cards. <em>AU: Audio Unit Receiver</em> based on IO units for voice calls plus <em>AQ: Audio Queue Device</em> dedicated to rings. Here under the recommended settings (I.E default one) </p>
<div class="fragment"><div class="line"><a class="code" href="group__media__parameters.html#ga918921988d674e6709dbbf40c76fde2c">linphone_core_set_playback_device</a>(lc, <span class="stringliteral">"AU: Audio Unit Receiver"</span>);</div>
<div class="line"><a class="code" href="group__media__parameters.html#gaf39872ecc72222f20f21f43b1d801c7d">linphone_core_set_ringer_device</a>(lc, <span class="stringliteral">"AQ: Audio Queue Device"</span>);</div>
<div class="line"><a class="code" href="group__media__parameters.html#gabca57ab3569c2e4bc7811336be6ea989">linphone_core_set_capture_device</a>(lc, <span class="stringliteral">"AU: Audio Unit Receiver"</span>);</div>
</div><!-- fragment --><p> <b> GSM call interaction </b> <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). </p>
<div class="fragment"><div class="line"><span class="comment">// declare a class handling the AVAudioSessionDelegate protocol</span></div>
<div class="line"><span class="keyword">@interface </span>MyClass : NSObject <AVAudioSessionDelegate> { [...] }</div>
<div class="line"><span class="comment">// implement 2 methods : here's an example implementation</span></div>
<div class="line">-(void) beginInterruption {</div>
<div class="line"> LinphoneCall* c = <a class="code" href="group__call__control.html#gac268a222347024ad7adb4eaf1fd27241">linphone_core_get_current_call</a>(theLinphoneCore);</div>
<div class="line"> ms_message(<span class="stringliteral">"Sound interruption detected!"</span>);</div>
<div class="line"> <span class="keywordflow">if</span> (c) {</div>
<div class="line"> <a class="code" href="group__call__control.html#ga8cdae37a26ba7633067ea03bc43bd887">linphone_core_pause_call</a>(theLinphoneCore, c);</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line">-(void) endInterruption {</div>
<div class="line"> ms_message(<span class="stringliteral">"Sound interruption ended!"</span>);</div>
<div class="line"> <span class="keyword">const</span> MSList* c = <a class="code" href="group__call__control.html#gaf1f76b5a5d62e8bef5e1ad60e4f7b042">linphone_core_get_calls</a>(theLinphoneCore);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">if</span> (c) {</div>
<div class="line"> ms_message(<span class="stringliteral">"Auto resuming call"</span>);</div>
<div class="line"> <a class="code" href="group__call__control.html#ga3897c517486091f71e38986912bbecf5">linphone_core_resume_call</a>(theLinphoneCore, (LinphoneCall*) c->data);</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --> <dl class="section see"><dt>See Also</dt><dd><a href="http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSessionDelegate_ProtocolReference/Reference/Reference.html">http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSessionDelegate_ProtocolReference/Reference/Reference.html</a></dd></dl>
<p><br/>
Declare an instance of your class as AudioSession's delegate : </p>
<div class="fragment"><div class="line">[audioSession setDelegate:myClassInstance];</div>
</div><!-- fragment --> <dl class="section see"><dt>See Also</dt><dd><a href="http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSession_ClassReference/Reference/Reference.html">http://developer.apple.com/library/ios/#documentation/AVFoundation/Reference/AVAudioSession_ClassReference/Reference/Reference.html</a></dd></dl>
<p><b> Video </b> <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. <br/>
These 2 UIView objects must be passed to the core using functions <a class="el" href="group__media__parameters.html#ga90d0abb20b5c4a93836c861e540f975c">linphone_core_set_native_video_window_id()</a> and <a class="el" href="group__media__parameters.html#ga61c95bf5b044388e0b1084a9424b6d59">linphone_core_set_native_preview_window_id()</a>. here under speudo code: </p>
<div class="fragment"><div class="line">UIView* display = [[UIView alloc] init];</div>
<div class="line">UIView* preview = [[UIView alloc] init];</div>
<div class="line"><a class="code" href="group__media__parameters.html#ga90d0abb20b5c4a93836c861e540f975c">linphone_core_set_native_video_window_id</a>(lc,(<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span>)display); </div>
<div class="line"><a class="code" href="group__media__parameters.html#ga61c95bf5b044388e0b1084a9424b6d59">linphone_core_set_native_preview_window_id</a>(lc,(<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span>)preview);</div>
</div><!-- fragment --><p> <br/>
Screen rotations are also handled by liblinphone. 2 positions are currently supported, namely <em>UIInterfaceOrientationPortrait</em> and <em>UIInterfaceOrientationLandscapeRight</em>. Applications may invoke <a class="el" href="group__media__parameters.html#ga309fdb0f39432b125ff1f36347cea362">linphone_core_set_device_rotation()</a> followed by <a class="el" href="group__call__control.html#ga1a7819d96573bb8dbcbf2a128145457e">linphone_core_update_call()</a> to notify liblinphone of an orientation change. Here under a speudo code to handle orientation changes </p>
<div class="fragment"><div class="line">-(void) configureOrientation:(UIInterfaceOrientation) oritentation {</div>
<div class="line"> <span class="keywordtype">int</span> oldLinphoneOrientation = <a class="code" href="group__media__parameters.html#gae39b1bea4370f32c28fa446f97540d4f">linphone_core_get_device_rotation</a>(lc);</div>
<div class="line"> <span class="keywordflow">if</span> (oritentation == UIInterfaceOrientationPortrait ) {</div>
<div class="line"> <a class="code" href="group__media__parameters.html#ga90d0abb20b5c4a93836c861e540f975c">linphone_core_set_native_video_window_id</a>(lc,(<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span>)display-portrait); </div>
<div class="line"> <a class="code" href="group__media__parameters.html#ga61c95bf5b044388e0b1084a9424b6d59">linphone_core_set_native_preview_window_id</a>(lc,(<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span>)preview-portrait);</div>
<div class="line"> <a class="code" href="group__media__parameters.html#ga309fdb0f39432b125ff1f36347cea362">linphone_core_set_device_rotation</a>(lc, 0);</div>
<div class="line"> </div>
<div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (oritentation == UIInterfaceOrientationLandscapeRight ) {</div>
<div class="line"> <a class="code" href="group__media__parameters.html#ga90d0abb20b5c4a93836c861e540f975c">linphone_core_set_native_video_window_id</a>(lc,(<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span>)display-landscape); </div>
<div class="line"> <a class="code" href="group__media__parameters.html#ga61c95bf5b044388e0b1084a9424b6d59">linphone_core_set_native_preview_window_id</a>(lc,(<span class="keywordtype">unsigned</span> <span class="keywordtype">long</span>)preview-landscape);</div>
<div class="line"> <a class="code" href="group__media__parameters.html#ga309fdb0f39432b125ff1f36347cea362">linphone_core_set_device_rotation</a>(lc, 270);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">if</span> ((oldLinphoneOrientation != <a class="code" href="group__media__parameters.html#gae39b1bea4370f32c28fa446f97540d4f">linphone_core_get_device_rotation</a>(lc))</div>
<div class="line"> && <a class="code" href="group__call__control.html#gac268a222347024ad7adb4eaf1fd27241">linphone_core_get_current_call</a>(lc)) {</div>
<div class="line"> <span class="comment">//Orientation has changed, must call update call</span></div>
<div class="line"> <a class="code" href="group__call__control.html#ga1a7819d96573bb8dbcbf2a128145457e">linphone_core_update_call</a>(lc, <a class="code" href="group__call__control.html#gac268a222347024ad7adb4eaf1fd27241">linphone_core_get_current_call</a>(lc), NULL);</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><p><b>DTMF feebacks</b> <br/>
Liblinphone provides functions <a class="el" href="group__media__parameters.html#ga11b05c55741a236cb8d07b8a197ebcca">to play dtmf </a> 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 <a class="el" href="group__IOS.html#gaef3c840b3c9f576c642b49cf306c7461">preloading </a> and <a class="el" href="group__IOS.html#gaef3c840b3c9f576c642b49cf306c7461">unloading </a> the underlying audio graph responsible for playing DTMFs. <br/>
For an application using function <a class="el" href="group__media__parameters.html#ga11b05c55741a236cb8d07b8a197ebcca">linphone_core_play_dtmf()</a>, it is recommanded to call <a class="el" href="group__IOS.html#gaef3c840b3c9f576c642b49cf306c7461">linphone_core_start_dtmf_stream()</a> when entering in foreground and <a class="el" href="group__IOS.html#gad0ecef2fb7a77c3363aa94edeadaf65b">linphone_core_stop_dtmf_stream()</a> upon entering background mode. </p>
<h2>Function Documentation</h2>
<a class="anchor" id="gaef3c840b3c9f576c642b49cf306c7461"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void linphone_core_start_dtmf_stream </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__initializing.html#gaa5cf635b82dd338e7ee2dd3599d05f0a">LinphoneCore</a> * </td>
<td class="paramname"><em>lc</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Special function to warm up dtmf feeback stream. <a class="el" href="group__IOS.html#gad0ecef2fb7a77c3363aa94edeadaf65b">linphone_core_stop_dtmf_stream</a> must() be called before entering FG mode </p>
</div>
</div>
<a class="anchor" id="gad0ecef2fb7a77c3363aa94edeadaf65b"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void linphone_core_stop_dtmf_stream </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__initializing.html#gaa5cf635b82dd338e7ee2dd3599d05f0a">LinphoneCore</a> * </td>
<td class="paramname"><em>lc</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Special function to stop dtmf feed back function. Must be called before entering BG mode </p>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.1.2
</small></address>
</body>
</html>
