= Getting Started: Building for Apple iPhone, iPad and iPod Touch =
[[TracNav(Getting-Started/TOC)]]
[[PageOutline(2-3,,inline)]]

== Features ==

Some of the features of the iPhone port:
 - it has a native !CoreAudio based audio device, which supports the following features:
    * the built-in/device's echo canceller
    * output volume setting
    * input latency setting
    * output latency setting
 - supports for the built-in iLBC codec
 - video

== Requirements ==

 - iOS SDK, part of Xcode.

 - {{{Command Line Tools}}} for Xcode: download from [https://developer.apple.com/downloads/index.action Apple Developer Downloads] then install.

== Build Preparation ==

 1. [wiki:Getting-Started/Download-Source Get the source code], if you haven't already.
 2. Set your [wiki:Getting-Started/Build-Preparation config_site.h] to the following:
  {{{
#define PJ_CONFIG_IPHONE 1
#include <pj/config_site_sample.h>
  }}}
  This will activate iPhone specific settings in the {{{config_site_sample.h}}}.

== Building PJSIP ==

Just run:
 {{{
$ cd /path/to/your/pjsip/dir
$ ./configure-iphone
$ make dep && make clean && make
 }}}

Open {{{ipjsua.xcodeproj}}} using Xcode in [source:pjproject/trunk/pjsip-apps/src/pjsua/ios pjproject/pjsip-apps/src/pjsua/ios]. If you enable video and use libyuv/libopenh264, add the libraries into the application. Build the project and run. You will see telnet instructions on the device's screen. Telnet to this address to operate the application. See [wiki:PJSUA-CLI PJSUA CLI Manual] for commands available. (For release 2.1 and below, ipjsua is located in [source:pjproject/trunk/pjsip-apps/src/ipjsua pjproject/pjsip-apps/src/ipjsua] and does not have CLI telnet feature).

To use PJSIP in your application, you need to define PJ_AUTOCONF=1 in the Xcode's project config.

Notes:
 * the {{{./configure-iphone}}} is a wrapper that calls the standard {{{./configure}}} script with settings suitable for iPhone target.
 * the latest iPhone SDK version will be selected by default. You may change this by setting {{{IPHONESDK}}} environment variable to the desired SDK path. For ipjsua, select Project-Edit Project Settings-Base SDK and Targets-ipjsua-Get Info-Base SDK to change the SDK version.
 * you may pass standard {{{./configure}}} options to this script too.
 * for more info, run {{{./configure-iphone --help}}}
 * other customizations are similar to what is explained in [wiki:Getting-Started/Autoconf Building with GNU] page.

=== Supporting multiple architectures (armv6, armv7, armv7s, arm64, and so on) ===

You need to compile separately for each architecture. If your iPhone SDK has '''{{{llvm-gcc}}}''' compiler (which is the supported compiler starting iOS SDK 5) or '''{{{clang}}}''', then you need to set '''{{{ARCH}}}''' environment variable to the desired architecture before running {{{configure-iphone}}}, for example:
{{{
export ARCH="-arch arm64"
}}}

Then you need to combine the resulting libraries using the '''{{{lipo}}}''' command. For example:

{{{
lipo -arch armv6 lib/armv6/libpjlib.a -arch armv7 lib/armv7/libpjlib.a -create -output lib/libpjlib.a
}}}

=== Setting minimum supported iOS version ===

If you want to specify the minimum supported iOS version, you can set {{{MIN_IOS}}} environment variable before running {{{{configure-iphone}}}, for example:
{{{
export MIN_IOS="-miphoneos-version-min=8.0"
}}}

The default setting is iOS 7.0. If you don't want to specify this flag, you can set {{{MIN_IOS}}} to a single space instead ({{{export MIN_IOS=" "}}}) Note that if you don't set the minimum iOS version, you may encounter linker warning in your XCode app, which may lead to crashes when running on older iOS versions:
{{{
ld: warning: object file (...) was built for newer iOS version (10.0) than being linked (7.0)
}}}

=== Simulator ===

To configure the build system for the iPhone simulator:

 {{{
export DEVPATH=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer
# 64-bit simulator
ARCH="-arch x86_64" CFLAGS="-O2 -m64 -mios-simulator-version-min=5.0" LDFLAGS="-O2 -m64 -mios-simulator-version-min=5.0" ./configure-iphone
# or 32-bit
# ARCH="-arch i386" CFLAGS="-O2 -m32 -mios-simulator-version-min=5.0" LDFLAGS="-O2 -m32 -mios-simulator-version-min=5.0" ./configure-iphone
make dep && make clean && make
 }}}

Note that the exact paths may vary according to your SDK version.

[[BR]]

== Video Support ==

=== Features ===
 - native capture
 - native preview
 - native OpenGL ES renderer
 - H.264 codec (using native !VideoToolbox framework or OpenH264 library, see below)

=== Requirements ===

==== libyuv ====

       1. If you are using 2.5.5 or newer, libyuv should be built and enabled automatically, see ticket #1937 for more info.
       1. If you are using 2.5.1 or older, follow the instructions in ticket #1776.

==== OpenH264 or !VideoToolbox (choose only one) ====

       * For OpenH264, follow the instructions in ticket #1947 (or ticket #1758 if you use PJSIP before version 2.6).
       * For !VideoToolbox (supported since PJSIP version 2.7), define this in your config_site.h:
         {{{#define PJMEDIA_HAS_VID_TOOLBOX_CODEC 1}}}

=== Configuring ===

Sample invocation of ./configure-iphone:
{{{
$ ./configure-iphone --with-openh264=/Users/me/opt
}}}

If you use openh264, make sure it is detected by {{{./configure-iphone}}}:
{{{
...
Using OpenH264 prefix... /Users/me/opt
checking OpenH264 availability... ok
...
}}}

Set these in your {{{config_site.h}}}:

{{{
#define PJ_CONFIG_IPHONE 			1
#define PJMEDIA_HAS_VIDEO			1

#include <pj/config_site_sample.h>
}}}

=== Video capture orientation support ===

To send video in the proper orientation (i.e. head always up regardless of the device orientation), application needs to do the following:

1. Setup the device to get orientation change notification (by calling the API {{{UIDevice.beginGeneratingDeviceOrientationNotifications}}} and add a callback to receive {{{UIDeviceOrientationDidChangeNotification}}}).
2. Inside the callback, call PJSUA API
 {{{
pjsua_vid_dev_set_setting(dev_id, PJMEDIA_VID_DEV_CAP_ORIENTATION, &new_orientation, PJ_TRUE)
 }}}
 to set the video device to the correct orientation.

For sample usage, please refer to [https://trac.pjsip.org/repos/browser/pjproject/trunk/pjsip-apps/src/pjsua/ios/ipjsua/ipjsuaAppDelegate.m ipjsua sample app]. Ticket #1861 explains this feature in detail.

[[BR]]

== OpenSSL Support ==

Follow the instructions below to enable TLS transport by using OpenSSL:
 1. Build and install OpenSSL-1.0.0 for iPhone by following [http://www.x2on.de/2010/07/13/tutorial-iphone-app-with-compiled-openssl-1-0-0a-library/ these instructions] or OpenSSL-0.9.8o with [http://www.x2on.de/2010/02/01/tutorial-iphone-app-with-compiled-openssl-library/ these instructions].
 1. Specify OpenSSL location when running {{{configure-iphone}}}, for example (with Bash):
 {{{
./configure-iphone --with-ssl=[your_openssl_dir]
 }}}
 And check that OpenSSL is detected by the configure script:
 {{{
...
checking for OpenSSL installations..
checking openssl/ssl.h usability... yes
checking openssl/ssl.h presence... no
aconfigure: WARNING: openssl/ssl.h: accepted by the compiler, rejected by the preprocessor!
aconfigure: WARNING: openssl/ssl.h: proceeding with the compiler's result
checking for openssl/ssl.h... yes
checking for ERR_load_BIO_strings in -lcrypto... yes
checking for SSL_library_init in -lssl... yes
OpenSSL library found, SSL support enabled
...
 }}}
 1. Build the libraries:
 {{{
make dep && make
 }}}
 1. In XCode project setting of your application (for example, ipjsua), add {{{libssl.a}}} and {{{libcrypto.a}}} from OpenSSL ARM directory to the project's Libraries:
  a. In '''Group & Files''' pane, expand '''ipjsua''', then right click '''Libraries''', and select '''Add -> Existing Files...'''.
  a. Find {{{libssl.a}}} and {{{libcrypto.a}}} from OpenSSL ARM directory (for example, {{{${HOME}/openssl/openssl_arm}}}) and add them to the project.
 1. Build the app


== Common problems ==

=== !PushKit guide, to accept calls in the background after ```kCFStreamNetworkServiceTypeVoIP``` is deprecated (iOS 10/iOS 9) === #bg-call

Starting in iOS 9, [https://developer.apple.com/library/ios/documentation/CoreFoundation/Reference/CFSocketStreamRef/index.html#//apple_ref/doc/constant_group/Stream_Service_Types kCFStreamNetworkServiceTypeVoIP] is deprecated. Apple recommends that applications use VoIP Push Notifications (using !PushKit framework) to avoid persistent connections as described in the [https://developer.apple.com/library/ios/documentation/Performance/Conceptual/EnergyGuide-iOS/OptimizeVoIP.html Apple's official doc]. This will require application to implement the setup and handling of push notifications in the application layer (for more details, you can refer to ticket #1941). For now, PJSIP will still use ```kCFStreamNetworkServiceTypeVoIP```, if you want to disable it right away, you can set ```PJ_IPHONE_OS_HAS_MULTITASKING_SUPPORT``` to 0.

=== !CallKit integration and audio session (AVAudioSession) management (iOS 10) ===

!CallKit requires application to configure audio session and start the call audio at specific times. Thus, to ensure a smooth integration, we disable the setup of audio session in our sound device wrapper to avoid conflict with application's audio session setting.  Starting from ticket #1941, application needs to set its own audio session category, mode, and activation/deactivation.

Here could be used as a quick start reference:
 - [https://developer.apple.com/reference/avfoundation/avaudiosession Apple's AVAudioSession doc]

=== Crash after calling PJLIB APIs using Grand Central Dispatch (GCD) === #gcd-crash

PJLIB API should be called from a registered thread, otherwise it will raise assertion such as "Calling pjlib from unknown/external thread...". With GCD, we cannot really be sure of which thread executing the PJLIB function. Registering that thread to PJLIB seems to be a simple and easy solution, however it potentially introduces a random crash which is harder to debug. Here are few possible crash scenarios:
 - PJLIB's {{{pj_thread_desc}}} should remain valid until the registered thread stopped, otherwise crash of invalid pointer access may occur, e.g: in {{{pj_thread_check_stack()}}}.
 - Some compatibility problems between GCD and PJLIB, see #1837 for more info.

If you want to avoid any possibility of blocking operation by PJLIB (or any higher API layer such as PJMEDIA, PJNATH, PJSUA that usually calls PJLIB), instead of dispatching the task using GCD, the safest way is to create and manage your own thread pool and register that thread pool to PJLIB. Or alternatively, simply use PJSUA timer mechanism (with zero delay), see {{{pjsua_schedule_timer()/pjsua_schedule_timer2()}}} docs for more info.

=== Audio lost or other issues with interruption (by a phone call or an alarm), headset plug/unplug, or Bluetooth input === #interruption
It has been reported that any time an audio interruption happens, audio is lost until the application is killed/restarted.

Here is the reported working solution:
 - application should be configured to receive interruption events, see [https://developer.apple.com/reference/avfoundation/avaudiosession Apple's AVAudioSession doc].
 - forcefully shutdown the sound device when interruption begins, e.g: using {{{pjsua_set_no_snd_dev())}}} for pjsua, or {{{AudDevManager.setNoDev()}}} for pjsua2
 - restart the sound device after interruption ends, e.g: using {{{pjsua_set_snd_dev()}}} for pjsua, or {{{AudDevManager.setPlaybackDev()+setCaptureDev()}}} for pjsua2.

Also note this is the recommended outline of the normal flow for audio interruption:
 - on interruption begin
   1. hold the calls
   1. stop any other media if any (i.e. disconnect all connections in the bridge)
   1. by default, sound device will be stopped after some idle period after there is no connection in the bridge, or alternatively just forcefully shutdown the sound device.

 - on interruption end
   1. unhold the calls
   1. resume any other media if any
   1. if sound device was not shutdown forcefully, first connection to the bridge will cause sound device to be started, otherwise manual restarting the sound device, by setting playback & capture device, is required.

=== SIP transport keepalive while in background === #keepalive

As the process is normally suspended when application is in the background, the worker thread that handles TCP keepalive timer is also suspended. So basically application needs to schedule periodic wakeup to allow the library send TCP keep-alive. Sample code:
{{{
- (void)keepAlive {
    /* Register this thread if not yet */
    if (!pj_thread_is_registered()) {
        static pj_thread_desc   thread_desc;
        static pj_thread_t     *thread;
	pj_thread_register("mainthread", thread_desc, &thread);
    }

    /* Simply sleep for 5s, give the time for library to send transport
     * keepalive packet, and wait for server response if any. Don't sleep
     * too short, to avoid too many wakeups, because when there is any
     * response from server, app will be woken up again (see also #1482).
     */
    pj_thread_sleep(5000);
}

- (void)applicationDidEnterBackground:(UIApplication *)application
{
    /* Send keep alive manually at the beginning of background */
    pjsip_endpt_send_raw*(...);

    /* iOS requires that the minimum keep alive interval is 600s */
    [application setKeepAliveTimeout:600 handler: ^{
	[self performSelectorOnMainThread:@selector(keepAlive)
              withObject:nil waitUntilDone:YES];
    }];
}
}}}

Make sure that keepalive feature of SIP transport is not disabled, see [http://www.pjsip.org/docs/latest/pjsip/docs/html/group__PJSIP__CONFIG.htm#ga02217f4919a7c575d71eed407be63d04 PJSIP_TCP/TLS_KEEP_ALIVE_INTERVAL] docs, and the keepalive interval is set to less than 600s.

Alternatively, configuring server to send keepalive ping packet, if possible, and client responds back by sending keepalive pong to the server, so we have two-way traffic. As there is no way to detect incoming ping from server, currently application can just always send pong packet whenever it becomes active (application will be woken up when receiving TCP packet), e.g: send pong packet in UIApplication::applicationDidBecomeActive().


== Other Problems (problem specific to a particular iOS version/device) ==

=== Unable to accept incoming call in background mode (iOS 8 or before) ===

Starting in iOS 9, this method to accept incoming call in bg is deprecated, please have a look at [#bg-call].

If while in the background, ipjsua (or your application) is unable to detect if there is an incoming call and display the local notification:
 1. Note that background feature only works with TCP.
 2. Make sure that voip is included in the required background modes (UIBackgroundModes) in the application’s Info.plist file.
 3. Make sure that the TCP socket is successfully wrapped with CFReadStreamRef (check if there is a message: "Failed to configure TCP transport for VoIP usage").
 4. Check whether you can accept the incoming call by bringing the app to the foreground. If yes, make sure that the incoming call request comes from the wrapped TCP socket (check the log for the INVITE request).

Note: these steps do not troubleshoot audio problems.

=== Audio issue (no audio) (iOS7) ===

There are a few reports that the audio is not working on iOS 7 (so far it's only reported to happen in iPhone 5) after getting the following error:

{{{
iPhone mediaserverd[45] <Error>: 10:53:59.986 ERROR:     [0x240b000] 740: _vp: initialize hw input: fs mismatched! REF=0.000000Hz, MIC=44100.000000Hz
iPhone mediaserverd[45] <Error>: Resampler2 bad sample rate(s) :        0.00    16000.00
}}}

One solution is to set the sound device's clock rate to 44100 Hz as to avoid resampling.

=== Audio issues (inability to mute, volume control center synchronization, playback reduced volume) (iOS7) ===

There are several issues with the use of Voice Processing IO Audio Unit in iOS 7, such as unable to mute the volume using the side volume button, unable to synchronize with the control center volume slide bar, significantly reduced volume for audio playback to speaker after a call. Currently there is no workaround for this. Please refer to ticket #1697 for more details.

=== List of Issues ===

[[TicketQuery(type=defect&summary~=iphone)]]

== Other iPhone Projects ==

Also have a look at these PJSIP iPhone ports by pjsip users:

 * [http://code.google.com/p/siphon/ Siphon] Project by Samuel Vinson
 * [http://code.google.com/p/pjsip-iphone-audio-driver/ iPhone Audio Driver] by [http://www.voalte.com/ Voalté]
 * [http://code.teluu.com/tabikphone/ TabikPhone], an adaptation of Sipphone code from V-Net Corp