This article is intended to help developers wishing to incorporate telephony features in their BlackBerry® 10 applications.
Readers of this article should be familiar with BlackBerry 10 Native development, including Qt® and QML, and should be familiar with C++ in order to understand the sample applications that are used to demonstrate the concepts.
An open source application, “Communicator”, which incorporates the features discussed in this article, has been published on GitHub® as open source. Code fragments from this application are used in this article to illustrate important points.
Figure 1 - Screen shots from the communicator app.
Telephony APIs Use Cases
In simple terms, developers will want to use the BlackBerry 10 Telephony API in their apps to start a phone call, listen to incoming and outgoing calls, invoke call logs and system dial pad, etc.
The BlackBerry 10 Telephony APIs include two main classes: the Phone class and the Call class. The Phone class used for initiating phone calls and showing the dial pad or calls log, while the Call class provides access to active calls and their properties such as class type, call status, etc.
Adding Phone Functionality to Applications
The Phone class is the entry point for phone-related functionality, such as showing the dial pad, starting an outgoing call, checking the available lines supported on the phone, listening to call-related notifications, and so on. By creating an instance of the Phone class in your app, you get access to the BlackBerry 10 device's phone functionality.
You can instantiate a Phone object in either QML or C++, Let’s take our first look at some code. (All the code snippets are taken from the Communicator sample.)
In C++, You would create an object from the Phone class. It's recommended to have one Phone object for the entire application.
Phone *PhoneObj = new Phone();
In QML, Since the Phone class is a C++ class, the first thing we must do is to register the Phone class as qmlRegisterType for QML access,
Adding those two lines to the application constructor will allow the phone class to be accessed from any QML document that has the registered custom library "bb.system.phone" reference imported into it.
import bb.system.phone 1.0
Adding this line to the import section of any QML document will ensure the document gets access to the Phone class and its functionality.
Now the Phone class is ready and accessible from our QML document, We can create a Phone object as an attached object for the page or container or any control etc.
Now let's have a look at the phone class functionality.
Request Phone's Dial Pad
To display Phone's dial pad, you can simply call the requestDialpad method, passing in the phone number to dial.
Every time the app initiates an outgoing call, the user will be prompted to allow /disallow the call. Users have the choice to continue with the call or cancel it.
Figure 2 - Making Phone Call from the Communicator app.
Subsequent updates for the initiated call are indicated by the callUpdated() signal explained in the next section.
Listening to Incoming and Outgoing Calls
The app can listen to the incoming and outgoing calls by connecting to the callUpdated Signal and implementing a slot to be triggered every time the call gets updated. A callUpdated signal passes a call object to the slot so the app can get access to the call information. The app can retrieve the call type (incoming / outgoing) , call state ( connected / disconnected / missed / etc.) and the call ID. Retrieving the called/calling phone number is not available in the 10.2 SDK.
First: Connect to the callUpdated Signal in the application class constructor.
As shown above, we are passing a C++ Slot Method as parameter. Why? Because the Call class is not available in QML, it means that if you are implementing onCallUpdated in QML, you will be getting a reference to an object that you can't do anything with in QML. The slot must be implemented in C++ so you can get a good reference of the Call object being updated.
To learn more about accessing C++ slots & methods in QML, Please visit this link.
Apps can terminate phone calls by calling the endCall function and passing the ID of the call to terminate.
To use the Telephony APIs in your application, you need to indicate that permissions to access and control the phone will be required and that the user must grant these. To do so you, must include the following lines in your application’s bar-descriptor.xml file: