Phone

Since: BlackBerry 10.0.0

#include <bb/system/phone/Phone>

To link against this class, add the following line to your .pro file: LIBS += -lbbsystem

Provides phone-related functionality.

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.

The following example shows how to start a cellular call to the phone number "519-555-0100":

bb::system::phone::Phone phone;
phone.initiateCellularCall("519-555-0100");

Permissions:

You must also specify the access_phone and control_phone permissions in your bar-descriptor.xml file.


Overview

Public Functions Index

Phone (QObject *parent=0)
virtual ~Phone ()
LineactiveLine () const
QList< Line >availableLines (const QString &address) const
boolisLineAvailable (LineType::Type type) const
QMap< QString, Line >lines () const

Public Slots Index

boolendCall (int callId)
boolholdCall (int callId)
voidinitiateCall (const QString &address, bb::system::phone::LineType::Type lineType=bb::system::phone::LineType::Cellular)
voidinitiateCellularCall (const QString &phoneNumber, bool applySmartDialing=false)
voidinitiateVideoCall (const QString &address, bb::system::phone::LineType::Type lineType=bb::system::phone::LineType::Cellular)
boolmergeCall (int callId1, int callId2)
voidrequestDialpad (const QString &address, bb::system::phone::LineType::Type type=bb::system::phone::LineType::Cellular)
boolresumeCall (int callId)
boolsendDTMFTones (const QByteArray &tones, bb::system::phone::LineType::Type lineType=bb::system::phone::LineType::Cellular)
boolsplitCall (int callId)

Signals Index

voidcallCommandResponseReceived (const bb::system::phone::CallCommandResponse &commandResponse)
voidcallUpdated (const bb::system::phone::Call &call)
voidlineRemoved (const bb::system::phone::Line &line)
voidlineUpdated (const bb::system::phone::Line &line)

Public Functions

Phone (

Creates a new Phone object.

Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~Phone ()

Destructor.

Since:

BlackBerry 10.0.0

Line activeLine ()

Returns the currently active line.

Return:

The currently active line. If there is no active line, an invalid Line object is returned.

Since:

BlackBerry 10.0.0

QList< Line > availableLines (

Returns a list of phone lines that are currently available to make a call.

The lines are sorted based on priority.

For a given address (a phone number, a PIN, or an email address), more than one line may be available to make a call. For instance a cellular number can be called using MVS, SecuVOICE, or a cellular line. This method returns the list of available lines that can be used to call the given address. The lines are sorted according to their priority. For example, cellular line has higher priority over MVS line when both lines are available, so cellular will be the first item in the list followed by MVS and so on. Note that in a region where a phone number is 8 digits long, a phone number and a digits-only PIN cannot be differentiated by this API. In this case, availableLines() returns a list of available lines that may be used to call a phone number followed by the available lines that may be used to call a PIN.

Parameters
address

The phone number (for example, 3125559678) or PIN (for example, A564BBD1), or BBID (for example, test@blackberry.com) that can be used to make a call.

Return:

A list of currently available lines that can be used to make the call. The lines are sorted based on their priority.

Since:

BlackBerry 10.2.0

bool isLineAvailable (

Checks whether a given line is available.

Parameters
type

The type of the line to check. See LineType for the list of line types.

Return:

true if the given line type is available, false otherwise.

Since:

BlackBerry 10.0.0

QMap< QString, Line > lines ()

Returns a map of lines supported on the device.

Return:

A map of lines keyed on the line identifier supported on the device.

Since:

BlackBerry 10.0.0

Public Slots

bool endCall (
  • intcallId)

Ends an ongoing call.

Returns a Boolean that indicates whether the end call command was sent successfully. To determine the response of the execution of the call command, listen to callCommandResponseReceived signal.

Parameters
callId

Unique call session identifier.

Return:

true if the end call command was sent successfully, false otherwise.

Since:

BlackBerry 10.2

bool holdCall (
  • intcallId)

Holds a call.

Returns a Boolean that indicates whether the hold call command was sent successfully. To determine the response of the execution of the call command, listen to callCommandResponseReceived signal.

Parameters
callId

Unique call session identifier.

Return:

true if the hold call command was sent successfully, false otherwise.

Permissions:

The application must have the read_phonecall_details permission to use this feature.

Since:

BlackBerry 10.3.0

void initiateCall (

Initiates an outgoing call.

Parameters
address

The address (for example, phone number for cellular call, BBID for video chat, and so on) to call.

lineType

The phone line to use when making the call. The default is LineType::Cellular. See LineType for the list of line types.

Since:

BlackBerry 10.0.0

void initiateCellularCall (
  • const QString &phoneNumber,
  • boolapplySmartDialing )

Initiates an outgoing cellular call.

Subsequent updates for the initiated call are indicated by the callUpdated() signal.

Parameters
phoneNumber

The phone number to call.

applySmartDialing

Whether to apply smart dialing or not. The default is false.

Since:

BlackBerry 10.0.0

void initiateVideoCall (

Initiates an outgoing video call.

Parameters
address

The address (for example, phone number for video call over Cellular line, BBID for BBM Video Chat with BBM line selected, and so on) to call.

lineType

The phone line to use when making the video call. The default is LineType::Cellular. See LineType for the list of line types.

Since:

BlackBerry 10.3.0

bool mergeCall (
  • intcallId1,
  • intcallId2 )

Merges two calls into a conference call.

Returns a Boolean that indicates whether the merge call command was sent successfully. To determine the response of the execution of the call command, listen to callCommandResponseReceived signal.

If callId1 and callId2 are single-party calls, after the two calls are merged, a new call ID is generated to represent the conference call. At this point, callId1 and callId2 still exist and they become participants in the conference call identified by the new call ID. Clients can listen to the callUpdated() signal for the new call ID.

See also:

bb::system::Phone::splitCall

Parameters
callId1

Unique call session identifier of the first call to be merged.

callId2

Unique call session identifier of the second call to be merged.

Return:

true if the merge call command was sent successfully, false otherwise.

Permissions:

The application must have the read_phonecall_details permission to use this feature.

Since:

BlackBerry 10.3.0

void requestDialpad (

Brings the phone dial pad to the foreground with the number field pre-populated with the given address.

The callUpdated() signal will not be emitted for calls resulting from the requestDialpad() method.

Parameters
address

The address with which to populate the number field.

type

The phone line to use when making the call. The default is LineType::Cellular. See LineType for the complete list of line types.

Since:

BlackBerry 10.0.0

bool resumeCall (
  • intcallId)

Resumes a call.

Returns a Boolean that indicates whether the resume call command was sent successfully. To determine the response of the execution of the call command, listen to callCommandResponseReceived signal.

Parameters
callId

Unique call session identifier.

Return:

true if the resume call command was sent successfully, false otherwise.

Permissions:

The application must have the read_phonecall_details permission to use this feature.

Since:

BlackBerry 10.3.0

bool sendDTMFTones (

Sends DTMF tones to the active call.

The DTMF tones are sent in the order in which they appear in the QByteArray.

Parameters
tones

The DTMF tones to send. Each element in tones should correspond to a DTMF tone.

lineType

The phone line to which the DTMF tones should be sent. The default is LineType::Cellular. See LineType::Type for the complete list of line types.

Return:

true if the tones were successfully sent to the active call, false otherwise.

Since:

BlackBerry 10.0.0

bool splitCall (
  • intcallId)

Splits the given call from a conference call.

Returns a Boolean that indicates whether the split call command was sent successfully. To determine the response of the execution of the call command, listen to callCommandResponseReceived signal.

callId should refer to a participant in a conference call. After the split, the call identified by callId becomes the current active call. If the conference call has only two participants prior to the split, the other participant will be on hold, while the conference call itself will cease to exist. If the conference call has more than two participants prior to the split, the other participants will continue to be in the conference call, and the conference call will be on hold.

Clients can listen to the callUpdated() signal for updates.

To disconnect all participants in a conference call, use endCall() and pass in the conference call ID.

See also:

bb::system::Phone::endCall

,

bb::system::Phone::mergeCall

Parameters
callId

Unique call session identifier of a conference call participant.

Return:

true if the split call command was sent successfully, false otherwise.

Permissions:

The application must have the read_phonecall_details permission to use this feature.

Since:

BlackBerry 10.3.0

Signals

void callCommandResponseReceived (

Emitted when the response of a call command (for example, end call) initiated through this Phone object instance is returned.

Parameters
commandResponse

A CallCommandResponse object with updated information.

Since:

BlackBerry 10.2

void callUpdated (

Emitted when an incoming call is received or updated, or an outgoing call initiated through this Phone object instance is updated.

Parameters
call

A Call object with updated information.

Since:

BlackBerry 10.0.0

void lineRemoved (

Emitted when a line is removed.

Parameters
line

A Line object that was removed.

Since:

BlackBerry 10.0.0

void lineUpdated (

Emitted when a line is updated.

Parameters
line

A Line object with updated information.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus