iOS
Adding the liblinphone dependency to your iOS project
Liblinphone for iOS is available using Cocoapods, the de-facto standard in the Apple developer world for "dependency management for Swift and Objective-C". Liblinphone can also be compiled from the sources.
Using Cocoapods
For a project named "Myproject"
open Myproject/, use commands:
Modify the generated Podfile according to your project:
##For macosx
# platform :osx, '10.9'
#source "https://gitlab.linphone.org/BC/public/podspec-macos.git"
#For iOS
platform :ios, '9.0'
source "https://gitlab.linphone.org/BC/public/podspec.git"
target 'Myproject' do
use_frameworks!
# Pods for Myproject
pod 'linphone-sdk' , '4.3'
end
To install or update the liblinphone version, do the following command
pod install
And you're done.
Some alpha (development versions) of liblinphone may also be available. To get them, replace the line:
pod 'linphone-sdk' , '4.3'
by
followed by:
Compiling linphone-sdk
Linphone-sdk is the name of the git project that contains liblinphone and all its dependencies.
Compilation instructions of the SDK are available at: linphone-sdk/README.md
Once done, cocoapods needs to be invoked to update the Xcode workspace to use your locally built linphone-sdk, as follows:
where <path to linphone-sdk-ios> is your build directory of the linphone-sdk project, containing the linphone-sdk.podspec file and a linphone-sdk output directory comprising built frameworks and resources.
Using liblinphone
Liblinphone has a C API, suitable to be used with Objective-C, and a modern Swift API. To use in swift, import the liblinphone swift module in your source file using
API documentation
You can find the liblinphone C API documentation here.
For Swift, online documentation is available here . In addition, this iOS sample app shows how to use liblinphone in a Swift project.
Guidelines for integrating with push notifications
Introduction
An iOS application has in general a very limited capability to run in background, for example to keep a connection to a SIP server in order to receive calls and IM at any time. When the application goes in background, the network connections are killed and the application no longer executes.
The solution to circumvent this limitation is to rely on Apple's push notification system. The push notification first launch or resumes the app, that can then connect to the SIP service and retrieve the pending INVITE or MESSAGE request. In iOS there are three kinds of push notifications:
- The Remote Notification, for general purpose notifications
- The PushKit notifications, dedicated to VoIP calls. Unlike Remote Push Notifications, they do not display anything by themselves.
- The Background Update Notifications, used for service like notifications. They are not real-time and severely rate limited (no more than 3 per hour). They are currently not used by Linphone, liblinphone or Flexisip.
New limitations and restrictions were added by Apple with Xcode 11 and iOS 13:
- applications can no longer use PushKit kind of push notifications for anything else than presenting a VoIP call with CallKit. This is disruptive because previously, communication apps tend to also use PushKit to get notified of incoming IM messages. Since they can wake up the app in background, it was convenient to perform background processing before displaying the message to the user.
- applications receiving a PushKit notification are required to immediately invoke Callkit to display the call to the end-user. This is disruptive also, because at the time of receiving the push notification, the app has not yet the signaling information about the call (ie, the SIP INVITE). The end user may even accept the call while the INVITE is not yet arrived, in which case the app has to postpone the call acceptance to the actual receiving of the INVITE, and also update the CallKit view with the missing information.
The next chapters explain the detailed steps to create a Liblinphone based application that comply with the above requirements. It can be used of course as a guide to upgrade an existing liblinphone based application to iOS 13 / Xcode 11.
Technical solutions to advertise incoming calls
The table below summarizes the technical solutions offered to advertise incoming calls.
| Use case | Push notification type | Solution |
|---|---|---|
| App showing calls with Callkit, with access to internet. | Pushkit | Integrate CallKit into your application according to the guidelines provided in the section "Callkit integration" of this document. This solution is the one implemented in the Linphone application. |
| App showing calls with Callkit, in an isolated network. | No push notification at all. | Use UIApplication's keepAliveTimeout to trigger periodic calls to Core.refreshRegisters() and background sockets. Use Callkit in your app, but without Pushkit. Liblinphone by default attempts to activate background sockets. Using this solution requires a special authorization from Apple. The app must have its main usage done without connection to the internet. |
Basic app not showing calls with Callkit. This is the case where the Callkit UI is not adapted. For example: an app that needs to establish video at first, home automation app showing video before the call is accepted. | Remote Push Notifications | Use Remote Push Notifications in a basic scheme.
When pressed by the user, the notification will launch or resume the app. The app can then connect to the SIP service and display the incoming call in its UI. |
Advanced app not showing calls with Callkit. This is the case where the Callkit UI is not adapted. For example: an app that needs to establish video at first, home automation app showing video before the call is accepted. | Remote Push Notifications used together with a Notification Content Extension | Use Remote Push Notifications, but handle them inside an app extension of type "Notification Content". The app extension is a companion bundled with main application. It executes in a different process with restricted permissions, for example it cannot access geolocation information.
When the notification is pressed by the user, the main app is resumed or launched. The app extension stops, and the call needs to be received a second time by the main app. The main app can know if the user has accepted the call in the notification, and then immediately transition the call to a running state. |
CallKit integration
Starting from linphone-sdk >= 4.3, Callkit must be integrated in the following way:
- Add the CallKit framework into your application's dependencies in Xcode.
- Implement the CXProviderDelegate protocol within your ApplicationDelegate
- Add the configuration "use_callkit=1" in the section "app" or call linphone_core_enable_callkit() before the linphone core starts.
- Your CallKit delegate MUST inform the LinphoneCore when AVAudioSession is activated, as follows:
lc.activateAudioSession(actived: true)
}
func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
lc.activateAudioSession(actived: false)
}
Answer an incoming call
Since iOS 13, Apple requests CallKit to be invoked to display the incoming call immediately when a PushKit notification is received. So sometimes you can answer the CallKit before a LinphoneCall is received. In the callback CXAnswerCallAction, if a LinphoneCall has not yet been received, you need to configure your AVAudioSession and accept the call when you receive it. Otherwise, accept the call directly.
if (call == nil || call.state != Call.State.IncomingReceived) {
// configure audio session here. Use 48000 Hz as sampling rate.
} else {
// accept call here
}
action.fulfill()
}
Terminate a call
// terminate call here
action.fulfill()
}
Start an outgoing call
When starting an outgoing call from the application view, it must following these steps:
Add these codes to your class when starting an outgoing call
let startCallAction = CXStartCallAction(call: uuid, handle: handle)
let transaction = CXTransaction(action: startCallAction)
let callController = CXCallController()
callController.request(_ transaction: transaction, completion: @escaping (Error?) -> Void)
Then this callback will be called.
// start an outgoing call
action.fulfill()
}
To ensure the audio session works properly for this outgoing call.
reportOutgoingCall(with UUID: UUID, startedConnectingAt dateStartedConnecting: Date?)
// When outgoing call is answered
reportOutgoingCall(with UUID: UUID, connectedAt dateConnected: Date?)
Hold/resume a call
// If this is a conference, leave/enter the conference.
// Otherwide, pause/resume the call.
action.fulfill()
}
Mute/un-mute a call
// Mute/un-mute a call
action.fulfill()
}
Play DTMF
// Send DTMF
action.fulfill()
}
Group calls
// add all to conference
action.fulfill()
}
Transfer a call
Callkit does not support call transfer when Linphone does. If you wan to realise the call transfer with Callkit, you must follow these tips:
- For callkit, an unique uuid represents a call.
- For Linphone, the referred call will use a different callid than the original call.
Technical solutions to advertise instant messages
The table below summarizes the possible options. Remember that using PushKit is no longer possible since iOS 13 / Xcode 11.
| Use case | Push notification type | Solution |
|---|---|---|
| Basic app, not using end to end encryption. | Remote Push Notification | The sender identity and the text content must be placed into the push notification sent by the server. The push notification is displayed to the user. When pressed, the app is resumed or launched, and can display the conversation related to the received notification. Please note that the app has no way to perform any kind of pre-processing on the notification, such as perform deciphering of the message or fetching additional content (photos for example). |
| Advanced app, with security requirements. | Remote Push Notification used together with a Notification Service Extension. | Use Remote Push Notifications handled by an app extension of type "Notification Service Extension". The app extension is bundled with the main app. It executes in a different process with restricted permissions, for example it cannot access geolocation information. The Notification Service Extension will receive the remote push notification silently, in background. It has a constrained period of time to do some processing: connect to the SIP service, get the instant message, decipher it, and at the end update the notification to fill it with sender identity and clear text message. The notification is then displayed normally by iOS. When pressed, the main application is launched and can display the conversation that relates to the received message. The app extension and the main app have a shared filesystem and messaging framework, with synchronisation mechanisms. This solution is presented with details in the section "Advertising instant messages with a Notification Service Extension". It is the one implemented in the Linphone application. |
Advertising instant messages with a Notification Service Extension
Handling liblinphone log
In order to see liblinphone logs in your IOS app (for example in your Xcode console) follow these steps :
Put in your code at the launching of the app :
This will make the liblinphone logs to call your_log_handler and so be processed as a log from your app.
You can set the liblinphone log level by using the functions documented here.
IOS log handler for liblinphone
Once you have set your log handler, you need to process liblinphone log in order to incorporate them into your app logs.
Here is a short example of how to manage liblinphone log into an IOS app :
NSString *format = [[NSString alloc] initWithUTF8String:fmt];
NSString *formatedString = [[NSString alloc] initWithFormat:format arguments:args];
NSString *lvl;
if (!domain)
domain = "lib";
// since \r are interpreted like \n, avoid double new lines when logging network packets (belle-sip)
// output format is like: I/ios/some logs. We truncate domain to **exactly** DOMAIN_SIZE characters to have
// fixed-length aligned logs
switch (lev) {
case ORTP_FATAL:
lvl = @"Fatal";
break;
case ORTP_ERROR:
lvl = @"Error";
break;
case ORTP_WARNING:
lvl = @"Warning";
break;
case ORTP_MESSAGE:
lvl = @"Message";
break;
case ORTP_DEBUG:
lvl = @"Debug";
break;
case ORTP_TRACE:
lvl = @"Trace";
break;
case ORTP_LOGLEV_END:
return;
}
if ([formatedString containsString:@"\n"]) {
NSArray *myWords = [[formatedString stringByReplacingOccurrencesOfString:@"\r\n" withString:@"\n"]
componentsSeparatedByString:@"\n"];
for (int i = 0; i < myWords.count; i++) {
NSString *tab = i > 0 ? @"\t" : @"";
if (((NSString *)myWords[i]).length > 0) {
NSLog(@"[%@] %@%@", lvl, tab, (NSString *)myWords[i]);
}
}
} else {
NSLog(@"[%@] %@", lvl, [formatedString stringByReplacingOccurrencesOfString:@"\r\n" withString:@"\n"]);
}
}