= 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

== Requirements ==

You'll need an iPhone SDK. We tested mainly with version 3.x SDK/devices, but SDK version 2.x would build fine too. Apple iPad is supported starting with iPhone SDK 3.2.

== 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/ipjsua pjproject/pjsip-apps/src/ipjsua] and build the project.

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
$ ./configure-iphone
$ make dep && make clean && make
 }}}

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

== 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. Make sure that voip is included in the required background modes (UIBackgroundModes) in the application’s Info.plist file.
 2. Make sure that the TCP socket is successfully wrapped with CFReadStreamRef (check if there a message: "Failed to configure TCP transport for VoIP usage").
 3. 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.

=== Compilation error using iPhoneSimulator SDK version 3.2 ===

If you get this error during compilation:
{{{
/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator3.2.sdk/usr/include/available.h:111:6:
error: #error __MAC_OS_X_VERSION_MAX_ALLOWED must be >= __MAC_OS_X_VERSION_MIN_REQUIRED
}}}

Add this in your '''{{{config_site.h}}}''':

{{{
#undef __MAC_OS_X_VERSION_MIN_REQUIRED
#undef __MAC_OS_X_VERSION_MAX_ALLOWED
#define __MAC_OS_X_VERSION_MIN_REQUIRED __MAC_OS_X_VERSION_10_4
#define __MAC_OS_X_VERSION_MAX_ALLOWED __MAC_OS_X_VERSION_10_5
}}}

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