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


Apple iPhone target is supported by PJSIP version 1.7 and later.

== 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
    * change input route to bluetooth input
    * change output route
    * input latency setting
    * output latency setting
 - supports for the built-in iLBC codec
 - Note: video (from 2.x) is not yet supported on iOS.

== Requirements ==

You'll need an iPhone SDK, part of Xcode. Apple iPad is supported starting with iPhone SDK 3.2 onwards.

Make sure {{{Command Line Tools}}} in Xcode {{{Preferences}}} is installed:

[[Image(XCodeCommandLineToolsInstalled.png)]]

== 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
 }}}

For iPhone 5, use armv7s architecture:

 {{{
$ cd /path/to/your/pjsip/dir
$ ARCH='-arch armv7s' ./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] and build the project. 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).

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.

== Simulator ==

To configure the build system for the iPhone simulator:

 {{{
export DEVPATH=/Developer/Platforms/iPhoneSimulator.platform/Developer
export CC=/Developer/Platforms/iPhoneSimulator.platform/Developer/usr/bin/gcc-4.0
CFLAGS="-O2 -m32 -miphoneos-version-min=4.0" LDFLAGS="-O2 -m32" ./configure-iphone
make dep && make clean && make
 }}}

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

== OpenSSL Suport ==

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):
 {{{
export OPENSSL=${HOME}/openssl/openssl_arm
export CFLAGS="-O2 -Wno-unused-label -I${OPENSSL}/include"
export LDFLAGS="-L${OPENSSL}/lib"
./configure-iphone
 }}}
 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 ==

=== Unable to accept incoming call in background mode (iOS4) ===

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.

=== Supporting multiple architectures (armv6, armv7, armv7s, 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), then you need to set '''{{{ARCH}}}''' environment variable to the desired architecture before running {{{configure-iphone}}}, for example:
{{{
export ARCH = "-arch armv6"
}}}

For traditional gcc, you need to use these compilation flags (for armv7):

{{{
export CFLAGS += -march=armv7 -mcpu=arm1176jzf-s -mcpu=cortex-a8
export LDFLAGS += -march=armv7 -mcpu=arm1176jzf-s -mcpu=cortex-a8
}}}

For armv6, you need to compile using the flags:

{{{
export CFLAGS += -march=armv6 -mcpu=arm1176jzf-s
export LDFLAGS += -march=armv6 -mcpu=arm1176jzf-s
}}}

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
}}}

=== Unable to support Bluetooth input ===

Since Bluetooth input support is only available for iOS 3.1 or later, you need to specifically specify that your deployment target is iOS 3.1 or above. You can do this either in '''{{{user.mak}}}''':
{{{
export CFLAGS += -D__IPHONE_OS_VERSION_MIN_REQUIRED=30100
}}}
or in '''{{{config_site.h}}}''':
{{{
#define __IPHONE_OS_VERSION_MIN_REQUIRED 30100
}}}
You need to recompile PJSIP after this.

=== Problem with interruption (by a phone call or an alarm), headset plug/unplug, or Bluetooth input === 

For devices running iOS 4.0 or later, you need to enable your application to respond to remote-control events. This allows PJSIP to properly receive and process the above events. You can do this by adding the following code in your application:
{{{
[[UIApplication sharedApplication] beginReceivingRemoteControlEvents];
}}}
For more details, please refer to Apple's doc on [http://developer.apple.com/library/ios/#documentation/EventHandling/Conceptual/EventHandlingiPhoneOS/RemoteControl/RemoteControl.html Remote Control of Multimedia].

=== Problem with deprecated CPU_SUBTYPE_ARM_ALL subtype ===

If you get this warning during compilation:
{{{
CPU_SUBTYPE_ARM_ALL subtype is deprecated
warning: -force_cpusubtype_ALL will become unsupported for ARM architectures
}}}

Modify your '''{{{user.mak}}}''' (this requires at least gcc 4.2.1 so please use r3462 or later (see ticket #1218)):

{{{
export CFLAGS += -march=armv7 -mcpu=arm1176jzf-s -mcpu=cortex-a8
export LDFLAGS += -march=armv7 -mcpu=arm1176jzf-s -mcpu=cortex-a8
}}}

Then rebuild PJSIP.
Next, change your XCode setting, go to Targets-ipjsua(or your application name)-Get Info-Build, select Architectures-armv7 and tick Build Active Architecture Only-Yes.

If you need to support another architecture and/or cpu subtype, you can visit [http://en.wikipedia.org/wiki/ARM_architecture Wikipedia doc on ARM architecture].

=== Sound not working in the simulator ===

Go to System Preferences > Sound > Sound Effects and then uncheck and recheck "Play user interface sound effects". If it still doesn't work, you can try some other suggestions [http://stackoverflow.com/questions/302399/sound-not-working-in-iphone-simulator here].

=== 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