It seems like the browser you are using has JavaScript disabled. As a result, the site will not function properly. We really want you to enable it so you may experience our site as we intended it. If you have no idea what we are talking about or if you need help, visit http://www.enable-javascript.com×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here.×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Telephony

Cascades provides basic Phone APIs that you can use to
show the dial pad, start a call, or listen to call-related
notifications.

You can use the Phone class to show the dial pad on a BlackBerry device and start a call. You can use the
Call, CallState, and CallType classes to learn about active
calls on a device. For example, you can find out if the current call
is connected, ringing, on hold, or disconnected. You can also find
out what type of call it is, such as incoming, outgoing, multiparty,
or emergency. You can use the Line and LineType classes to find out information
about the line on a device, such as the device phone number or the
PIN of the participant in a BBM Video chat.

If your app uses API level 10.2 or later, you can use the CallCommandResponse class to display information about a call and
details about the network response to a call command. For more information about setting
an API level, see API levels.

You can use the Phone APIs to integrate the phone on a device with your
app. For example, you could use Phone APIs to create a pizzeria finder app that finds
and displays the phone numbers of the pizzerias in your area.

Permissions

To enable your app to access the phone, you must add access_phone and control_phone
permissions to your bar-descriptor.xml file. The access_phone permission allows your app to access the phone app (for
example, to request the dial pad). The control_phone permission allows your app to control an ongoing call
(for example, to send DTMF tones or end the call).

10.3 If your app uses
API level 10.3, you can also use the following permissions:

The read_phonecall_details permission
allows your app to view the status of calls that are in progress and the phone
number of the remote party.

Depending on the API that you are using in your app, you may need
one or more of these permissions. To make sure that you have all the permissions
that you need, you should always check the API documentation for the class and
function that you are using. To learn more about the bar-descriptor.xml file, see
The bar-descriptor.xml file. To learn more about permissions, see App permissions.

Show the dial pad

You can use the requestDialpad() function to display a dial pad in your app. You
can supply an address to prepopulate the dial pad with
a phone number to call. If you don't supply an address, the dial pad doesn't display a
phone number. You can use the LineType enumeration to supply
the type of line to use when a user initiates a call
(for example, Cellular or BBM Video chat). If you don't supply a type, the Cellular line
type is used.

The QML code sample below displays a single button to call a specific
phone number. A Phone object is added to the
Container by
using attachedObjects. When the user taps the button, the clicked()
signal is emitted and the requestDialpad() function is
called.

Initiate an outgoing call

When you use the requestDialpad()
function, your app presents a dial pad on the user's device, but your app doesn't start
a call. The user must tap (the Call button) on the device to initiate the call.

Using the example of the pizzeria finder app, you
might want to include the option for users to call to reserve seats
at the selected pizzeria. You can initiate the call by changing
requestDialpad() to initiateCall(). By default, initiateCall() makes a Cellular call if you do not supply a
line type.

If you change the code sample above to use initiateCall(), a dialog box is
presented when a user taps the button. This dialog box is a SystemDialog that the Phone app creates.
For more information about system dialog boxes, see Dialog boxes.

When a user makes an outgoing call from your app, you can control the
type of call that the user makes. You can restrict your app to make cellular calls by
using the initiateCellularCall() function, or you can supply a BlackBerry
ID or PIN to the initiateCall() function to start a BBM Video
chat.

Before you use these functions, you should learn more about which line
types are supported on the user's device. The lines()
function returns a QMap of lines
that are supported on a device. You can use the lines() function to find all the Line types that are available
on the device, as well as information about each line, such as the id, the type, the
address, and
a description
of the line.

If the line type is Cellular, the address is the phone number of the line.

You can use the activeLine()
function to find out which line on a device is active. Then, your app can send an
outgoing call to an alternate line. You can use the isLineAvailable() function to check to see if a line is available
for outgoing calls.

If your app uses API level 10.2 or later, you can use the availableLines() function to find all the lines that are currently
available to start a call. You can use the endcall()
function to end a call on a device. For more information about setting an API level, see
API levels.

Initiate a video call 10.3

You can use initiateVideoCall() to start an outgoing video
call in your app. You provide an address to call and a lineType to specify the type of video call that you are
initiating.

If you are making a video call over a cellular line, the address is a phone number. If
you are making a BBM Video
call, the address is a BlackBerry
ID or PIN.

The following code sample initiates a BBM Video call by supplying
a PIN to initiateVideoCall().

You can use mergeCall() to merge two ongoing calls into a
conference call. The two calls that you merge together can be single-party calls or
multiparty calls. Each call is represented by a unique ID. You can use callid() to find the unique ID of
a call. When you merge two calls together, you generate a new callid
that represents the new call.

The callUpdated() signal is emitted when two calls
are merged. You can respond to the callUpdated() signal to find the new
callid of the conference call by calling the
callid() function. You can merge a conference call with another
call to extend the conference.

When two calls have been merged, you can use splitCall() to remove a particular call that is
identified by a callid from the conference call. If
splitCall() removes a call from a conference, this call becomes
active and the other call in the conference is on hold. You can use resumeCall() to resume the call that is on
hold.

If a conference call has more than two calls in the conference,
splitCall() removes a particular call from the conference and
leaves the rest of the calls in the conference call. To end a conference call and all of
the calls in it, you can use endCall() and pass in the conference
callid.

Find call command details 10.2

The CallCommandResponse object provides details about the network
response to a call command. You can learn about the command the response is for, the
call ID of the call the command was run on, the error, and an error description. You can
listen for the callCommandResponseReceived() signal to learn about the details
of the call command response.

Here's a code sample that shows you how to connect to the callCommandResponseReceived() signal.

bool res = (QObject::connect(m_pPhone,
SIGNAL(callCommandResponseReceived(
const bb::system::phone::CallCommandResponse &)),
this,
SLOT(onCallCommandResponseReceived(
const bb::system::phone::CallCommandResponse&))));
Q_ASSERT(res);
// Because the variable is not used in the app,
// this is added to avoid a compiler warning.
Q_UNUSED(res);

Listen for incoming calls

You can use the callUpdated()
signal to listen for incoming and outgoing calls in your app. The callUpdated() signal is emitted when an incoming call is
received or updated, or an outgoing call is updated. Here's a code sample that connects
the callUpdated() signal to an onCallUpdated() slot that handles the incoming call.

bool success = connect(phone,
SIGNAL(callUpdated(bb::system::phone::Call&)),
this,
SLOT(onCallUpdated(bb::system::phone::Call&)));
if (success) {
// Signal was successfully connected
} else {
// Failed to connect to signal.
// This is not normal in most cases and can be a critical
// situation for your app! Make sure you know exactly why
// this has happened. Add some code to recover from the
// lost connection below this line.
}

When the callUpdated() signal is
emitted, the Call object is updated with information
about the incoming call. You can use the callState()
function to perform different actions in your app based on the state of the call.

Here's a code sample that shows a simple onCallUpdated() slot that is invoked when the callUpdated() signal is emitted. This function checks the state of the
call before it performs an action.

Send DTMF tones

Dual Tone Multi-Frequency (DTMF) tones are the sounds used for
touch-tone dialing. You can send DTMF tones to an active call on a device by using the
sendDTMFTones() function. You can use this function to create an
app that works with an interactive voice response system. If the user taps the dial pad
during an active call, you can send the corresponding tones to the active call to select
items in a directory or choices from a recorded menu. Here's a QML code sample that
sends the tones of the numbers "12345" to the active call.

When you test your app, you may not hear the DTMF tones on the device
because they are sent directly to the device programmatically.

Find the phone number of a device

Sometimes you need to know some information about the device that your
app is running on, such as what type of hardware is available, which network is being
used, or its phone number. You can use the HardwareInfo class to find
general information about the device, such as its name, model, and physical attributes.
Here's a sample that shows you how to extract the device name and the wireless network
information. In this sample, the output is sent to the console log file.

You can also find information about the user's wireless network by using
the Radio and SIM APIs. You can determine the
capabilities and state of a connected wireless network, determine the specific services
that the network supports, retrieve status information for an inserted SIM card, and
more.

If you need only the phone number of the device, you can use the address()
function. If the active line is a Cellular line, the
line address is the phone number. If the active line
is a BBM Video chat, the address is the PIN of the device. You can use the activeLine()
function to find out which line is active on the user's device. Here's a code sample
that finds the number of lines on a device, and then finds the address of each line on the device. In this sample, the output is sent to
the console log file.

10.3 If your app uses API level 10.3, you can
use the callLine() function to retrieve the line type
of the call as defined by LineType. If the Call object is invalid, the value returned by
callLine() is undefined and you can't determine the type of line
your app is running on.

Find the phone number of the remote party 10.3

An app running in the work space doesn't have access to the phone number on a cellular
call. An app running in the personal space doesn't have access to the phone number of a
call on a work line, for example, a SecuVOICE call.

The following code sample finds the phone number of call in progress when the callUpdated() signal is
emitted:

Invoke the Phone app

Cascades provides basic classes that let you interact with the phone on a
device. You can also use the invocation framework to integrate your app with the Phone
app. You can register your app with the invocation framework and invoke the Phone app to
initiate a call, including emergency calls. For more information, see Invoking core apps.

1. Download the tools

Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

2. Try the sample apps

Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

Select either the Core or Cascades radio buttons to display the samples relevant to you.

3. Educate yourself

The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

You can access all the documentation that you need in the left-hand navigation.

4. Start developing

The Reference tab is where you'll find essential details about how to use our APIs.

You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.