Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Native Development Knowledge Base

BlackBerry 10 Developer’s Guide to Telephony APIs

by Retired on ‎02-05-2014 09:01 AM - edited on ‎05-28-2015 09:43 AM by BlackBerry Development Advisor (2,022 Views)

 

Introduction

 

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.

 

Untitled picture.png

  • 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,

 

qmlRegisterType<phone::Phone>("bb.system.phone", 1, 0, "Phone");
DataSource::registerQmlTypes();

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.

 

attachedObjects: [
        Phone {
            id: phone
        }
]

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.

 

In C++:

PhoneObj->requestDialpad(("+5195550100");

In QML:

 ActionItem {
      title: "Dial Pad"
      ActionBar.placement: ActionBarPlacement.InOverflow
      imageSource: "asset:///images/icon_127.png"
      onTriggered: {
          phone.requestDialpad(dialPadCtn.phoneNumber)
      }
 }

  

Start Outgoing Phone Calls

Calling InitiateCellularCall method will initiate an outgoing cellular call. This method takes the phone number to dial as a parameter.

 

In C++:

PhoneObj->initiateCellularCall("+5195550100");

In QML:

ImageButton {
        defaultImageSource: "asset:///images/phone81.png"
         onClicked: {
              if(phoneNumbertxt.text.length > 0){
                    phone.initiateCellularCall(phoneNumbertxt.text);
              }
         }
 }

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.

 

Call-Communicator-Editted.png

 

  • 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.

 

In C++:

First: Connect to the callUpdated Signal in the application class constructor.

bool Connected = connect(PhoneObj,SIGNAL(callUpdated(const Call &)), this,SLOT(onCallUpdated(const Call &)));

Second: Create Slot in the application class Header (.hpp) file.

public slots: void onCallUpdated(const Call &call);

Finally, Implement the onCallUpdated Slot to be triggered every time the call updated.

void ApplicationUI::onCallUpdated(const Call &call) {
  //DO ANYTHING WITH THE CALL object here
_currentCallId = call.callId();
qDebug() << "Call ID : " << call.callId(); qDebug() << "Call Type : " << call.callType(); qDebug() << "Call State : " << call.callState(); }

In QML:

Just connect to the callUpdated Signal once the page is created.

onCreationCompleted: {
    phone.callUpdated.connect(communicatorApp.onCallUpdated);
}

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.

 

Terminate calls

Apps can terminate phone calls by calling the endCall function and passing the ID of the call to terminate.

 

In QML:

Button {
    text: "End Call"
    onClicked: {
        phone.endCall(communicatorApp.CurrentCallId)
    }
}

In C++:

_PhoneObj->endCall(_currentCallId);

 

Application Descriptor Issues

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:

 

 <permission>access_phone </permission>
 <permission>control_phone</permission>
  • Figure 3 - Permissions required for Telephony API use

 

Build Issues

To use the APIs featured in this article, you’ll also need to include the following in your project’s .pro file:

LIBS += -lbbsystem
  •   Figure 4 - Library referenced in .pro file

  

API References

You’ll find the APIs we’ve been exploring in the Cascades API reference:

 

https://developer.blackberry.com/native/documentation/cascades/device_comm/phone/

https://developer.blackberry.com/native/reference/cascades/device_and_communication_phone.html 

 

Other sample applications

The “Call Pizza” application in the Cascades-Samples repository is another example of use of the Telephony APIs.

 

https://github.com/blackberry/Cascades-Samples/tree/master/callapizza

 

Summary

 I hope that this article helps you make use of telephony in your BlackBerry 10 applications.

 

You can download the Communicator sample app, including full source code from:

 

https://github.com/blackberry/Cascades-Community-Samples/tree/master/communicator

 

All applications were written for the BlackBerry 10 Z10 , Q10, and Z30 devices and the following versions of the NDK and device software should be used to build and run them:

 

  • BlackBerry 10 Native SDK version 10.0.0 and above
  • BlackBerry 10 Software version 10.0.0 and above

The Author

This article was written by Kareem ELSayed who works in the BlackBerry Developer Relations team. 

 

You can contact Kareem either through the BlackBerry support forums or through Twitter®:

 

 

Support Forum ID

Twitter

Kareem

Kareem_ELSayed

@kemobyte

Comments
by Developer
on ‎05-28-2015 05:34 AM
The c++ signal is written with uppercase C, which is incorrect. It should be callUpdated, not CallUpdated
by BlackBerry Development Advisor
‎05-28-2015 09:44 AM - edited ‎05-28-2015 09:45 AM
Thanks for the note.  I've fixed this.
Users Online
Currently online: 29 members 1,785 guests
Please welcome our newest community members: