Getting Started: Building for Apple iPhone, iPad and iPod Touch

1. Features
2. Requirements
3. Build Preparation
4. Building PJSIP
5. Simulator
6. OpenSSL Suport
7. Common problems
   1. Unable to accept incoming call in background mode (iOS4)
   2. Compilation error using iPhoneSimulator SDK version 3.2
   3. Sound not working in the simulator
   4. List of Issues
8. Other iPhone Projects

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. Get the source code, if you haven't already.
2. Set your 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 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 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.

OpenSSL Suport

Follow the instructions below to enable TLS transport by using OpenSSL:

1. Build and install OpenSSL-0.9.8o for iPhone by following ​these instructions.
2. 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
   ...
   

3. Build the libraries:

   make dep && make
   

4. 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:
   1. In Group & Files pane, expand ipjsua, then right click Libraries, and select Add -> Existing Files....
   2. Find libssl.a and libcrypto.a from OpenSSL ARM directory (for example, ${HOME}/openssl/openssl_arm) and add them to the project.
5. 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.

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 ​here.

List of Issues

#1113

iPhone: Echo cancellation may not work on iOS using SDK 4.x

#1115

iPhone: Long delay when calling AudioConverterNew() causing timeout in acquiring pjsua lock (thanks Bogdan Krakowski the report)

#1130

Incoming TCP connection on iPhone iOS4 BG mode would fail over and over with EAGAIN error (thanks Bogdan Krakowski for the report)

#1172

Crash in coreaudio_dev (iPhone OS) when there is no call during a GSM interruption

#1174

Fix crash in coreaudio_dev's interruptionListener (iPhone OS) and support for multiple interrupted streams (thanks to Seth Hinze for the patch)

#1194

iPhone: Fix problems with echo cancellation and Bluetooth input (SDK 4.x)

#1225

iPhone: UDP socket send error after waking up from background mode (thanks Joe Meade for the report)

#1226

iPhone (info only): No audio in calls if app is woken up from background mode without network connectivity (thanks Joe Meade for the report)

#1228

Long delay in iPhone initialization (thanks Guy Zelkha for the report)

#1231

Crash in iPhone iOS when trying to make a call after the application is left running for days (thanks Alejandro Orellana for the report)

#1245

Assertion may be raised if iPhone app woken up to perform registration and the server is down (thanks Alejandro Orellana for the report)

#1246

Use CFHost API for pj_getaddrinfo() on iPhone OS

#1324

Build correctness on non-video platforms (Symbian, iPhone, Windows Mobile)

#1335

Fixes assertion when interruptionListener is called from an unregistered thread on iPhone OS (thanks to Ilya Kalinin for the patch)

#1342

Disable local host resolution on iPhone OS

#1482

iPhone: Solution for application getting killed by iOS 5 due to too many wakeups

#1597

Handle socket failure in STUN resolution when coming back from iPhone/iOS background mode

Other iPhone Projects

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

• ​Siphon Project by Samuel Vinson
• ​iPhone Audio Driver by ​Voalté
• ​TabikPhone, an adaptation of Sipphone code from V-Net Corp