Phone (BlackBerry JDE 7.1.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.rim.blackberry.api.phone
Class Phone

java.lang.Object
  net.rim.blackberry.api.phone.Phone

public final class Phone
extends Object
extends Object

This class provides the following:

Advanced utilities for interaction with the Phone application. You can use the methods in this class for finer manipulation of the Phone application. For example, injecting DTMF tones into active calls.
Access multiple lines on the device.
Adding data to the incoming and active call screens, if supported.

Multi-line examples

Example A: Switching a line

Create a class that extends MultiLineListener.

public class MultiLineAction extends MultiLineListener

Implement the MultiLineListener callbacks so that the app can be notified of switching results.

public void setPreferredLineFailure(int lineId)
 {
     _screen.popupMessage("Switching failed");
 }
 public void setPreferredLineSuccess(int lineId)
 {
  _screen.popupMessage("Switching to " + Phone.getLineNumber(lineId) + " completed" );
 }

Invoke Phone.setPreferredLine().

Phone.setPreferredLine( Phone.getLineIds()[0]);

Example B: Initiate an outgoing call

Invoke Phone.initiateCall.

Phone.initiateCall(Phone.getLineIds()[0], "5195550123");

Deregister the class from the phone listener before the application is closed.
```
Phone.removePhoneListener(this);
```

Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 4.0.0

Field Summary
	`static int`	`CALL_IN_PROGRESS` Pre-switching validation failure reason - there is already a call in progress.
	`static int`	`EMERGENCY_CALLBACK` Pre-switching validation failure reason - the phone's network service is in emergency mode.
	`static int`	`LINE_ALREADY_ACTIVE` Pre-switching validation failure reason - the line is already active.
	`static int`	`LINE_NOT_AVAILABLE` Pre-switching validation failure reason - the line is not available.
	`static int`	`LINE_NOT_EXIST` Pre-switching validation failure reason - the line does not exist.
	`static int`	`MOBILE_TYPE` Represents mobile line type.
	`static int`	`PBX_TYPE` Represents PBX line type.
	`static int`	`SWITCHING_IN_PROGRESS` Pre-switching validation failure reason - the phone is in the process of switching to a new line.

Method Summary
	`static void`	`addPhoneListener(PhoneListener pl)` Registers a phone listener with the system.
	`static void`	`clearVoicemailIndicator(int lineId)` Clears (removes) the voice mail indicator for a specified line.
	`static PhoneCall`	`getActiveCall()` Returns the currently active phone call.
	`static int`	`getActiveLineId()` Returns the line ID that is currently used for dialing.
	`static PhoneCall`	`getCall(int callid)` Returns the call by ID.
	`static Vector`	`getContactsByPhoneNumber(String phoneNumber)` Returns the contacts that match a specified phone number.
	`static String`	`getDevicePhoneNumber(boolean format)` Returns a device's phone number.
	`static int`	`getLineId(int callId)` Returns the line ID associated with a connected call.
	`static int[]`	`getLineIds()` Returns all the line IDs of a device.
	`static String`	`getLineLabel(int lineId)` Returns a line description.
	`static String`	`getLineNumber(int lineId)` Returns a phone number for a given line ID.
	`static int`	`getLineType(int lineId)` Returns the line type for a given line ID.
	`static int`	`getWAF(int lineId)` Returns the WAF for a given line ID.
	`static void`	`initiateCall(int lineId, String dest)` Switches the line ID and initiates a phone call to the specified phone number.
	`static boolean`	`isLineAvailable(int lineId)` Determines whether or not a line is available to make outgoing calls or receive incoming calls.
	`static boolean`	`isVoicemailIndicatorOn(int lineId)` Determines for a line whether or not the voice mail indicator is turned on, indicating to the user that there are one or more voice mail messages waiting.
	`static void`	`removePhoneListener(PhoneListener pl)` De-registers a phone listener from the system.
	`static void`	`setPreferredLine(int lineId)` Switches preferred line to a specified line.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

MOBILE_TYPE

public static final int MOBILE_TYPE

Represents mobile line type.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

PBX_TYPE

public static final int PBX_TYPE

Represents PBX line type.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

LINE_NOT_AVAILABLE

public static final int LINE_NOT_AVAILABLE

Pre-switching validation failure reason - the line is not available.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

LINE_ALREADY_ACTIVE

public static final int LINE_ALREADY_ACTIVE

Pre-switching validation failure reason - the line is already active.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

CALL_IN_PROGRESS

public static final int CALL_IN_PROGRESS

Pre-switching validation failure reason - there is already a call in progress.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

SWITCHING_IN_PROGRESS

public static final int SWITCHING_IN_PROGRESS

Pre-switching validation failure reason - the phone is in the process of switching to a new line.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

EMERGENCY_CALLBACK

public static final int EMERGENCY_CALLBACK

Pre-switching validation failure reason - the phone's network service is in emergency mode.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

LINE_NOT_EXIST

public static final int LINE_NOT_EXIST

Pre-switching validation failure reason - the line does not exist.

See Also:: Constant Field Values
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

Method Detail

getActiveCall

public static PhoneCall getActiveCall()

Returns the currently active phone call.

Returns:: The currently active call.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 4.0.0

getCall

public static PhoneCall getCall(int callid)

Returns the call by ID.

Parameters:: callid - ID of the call to return.
Returns:: PhoneCall corresponding to callid, or null if callid is invalid.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 4.0.0

addPhoneListener

public static void addPhoneListener(PhoneListener pl)

Registers a phone listener with the system. You should de-register any phone listeners before closing your application.

Parameters:: pl - Listener to handle phone events.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
See Also:: Phone.removePhoneListener(PhoneListener)
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 4.0.0

removePhoneListener

public static void removePhoneListener(PhoneListener pl)

De-registers a phone listener from the system.

Parameters:: pl - The phone listener to de-register.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 4.0.0

getDevicePhoneNumber

public static String getDevicePhoneNumber(boolean format)

Returns a device's phone number.

Parameters:: format - true if you want to return the phone number in its formatted form, which varies by region.
Returns:: A String representing the device's phone number, UNKNOWN NUMBER if the phone number is null or has a length of 0.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 4.1.0

getLineNumber

public static String getLineNumber(int lineId)
                            throws InvalidIDException

Returns a phone number for a given line ID.

Parameters:: lineId - The line ID.
Returns:: The non-formatted phone number as a String.
Throws:: InvalidIDException - if the line is not available or is not ready.; ControlledAccessException - if the user is not granted to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getLineLabel

public static String getLineLabel(int lineId)
                           throws InvalidIDException

Returns a line description.

Parameters:: lineId - The line ID.
Returns:: The line description as a String.
Throws:: InvalidIDException - if the line is not available or is not ready.; ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getWAF

public static int getWAF(int lineId)
                  throws InvalidIDException

Returns the WAF for a given line ID.

Parameters:: lineId - The line ID.
Returns:: A bitmask of 3GPP = 1, CDMA = 2, WLAN = 4 and IDEN = 8.
Throws:: InvalidIDException - if the line is not available or is not ready.; ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getLineType

public static int getLineType(int lineId)
                       throws InvalidIDException

Returns the line type for a given line ID. A line type can be mobile or PBX.

Parameters:: lineId - The line ID.
Returns:: 1 = mobile, 2 = PBX, 0 = neither.
Throws:: InvalidIDException - if the line is not available or is not ready.; ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getLineIds

public static int[] getLineIds()

Returns all the line IDs of a device.

Returns:: An int array of line IDs.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

isLineAvailable

public static boolean isLineAvailable(int lineId)

Determines whether or not a line is available to make outgoing calls or receive incoming calls.

Parameters:: lineId - The line ID for which to check availability.
Returns:: true if the line is available.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getActiveLineId

public static int getActiveLineId()

Returns the line ID that is currently used for dialing.

Returns:: The ID for the currently active line.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getLineId

public static int getLineId(int callId)
                     throws InvalidIDException

Returns the line ID associated with a connected call.

Parameters:: callId - The ID for the connected call.
Returns:: The line ID for the specified call.
Throws:: InvalidIDException - if the specified call is not in the connected state.; ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

setPreferredLine

public static void setPreferredLine(int lineId)

Switches preferred line to a specified line. The multiple line phone listener's preSwitchingConditionFailure() callback is invoked if:

The line does not exist
The line is not available
The line is already active
A call is already in progress
Line switching is already in progress

Parameters:: lineId - The ID of the line to switch to.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

initiateCall

public static void initiateCall(int lineId,
                                String dest)
                         throws RadioException

Switches the line ID and initiates a phone call to the specified phone number. The multiple line phone listener's preSwitchingConditionFailure() callback is invoked if:

The 1ine does not exist
The line is not available
The line is already active
A call is already in progress
Line switching is already in progress

Parameters:: lineId - The ID of the line to switch to.; dest - The phone number to use to initiate the call.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.; RadioException
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

isVoicemailIndicatorOn

public static boolean isVoicemailIndicatorOn(int lineId)

Determines for a line whether or not the voice mail indicator is turned on, indicating to the user that there are one or more voice mail messages waiting.

Parameters:: lineId - The ID of the line to query.
Returns:: true if the voice mail indicator is currently displayed for the line, false otherwise.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

clearVoicemailIndicator

public static void clearVoicemailIndicator(int lineId)

Clears (removes) the voice mail indicator for a specified line.

Parameters:: lineId - The ID of the line whose indicator should be removed.
Throws:: ControlledAccessException - if the user is not allowed to use the phone features.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 5.0.0

getContactsByPhoneNumber

public static Vector getContactsByPhoneNumber(String phoneNumber)

Returns the contacts that match a specified phone number. All contact lists are searched.

Parameters:: phoneNumber - A phone number as a String.
Returns:: A vector containing the contacts whose numbers match phoneNumber. The vector is empty if a match is not found, or if the number is private, unknown, an emergency number, voice mail or a SIM startup call.
Throws:: IllegalArgumentException - if the phone number is null or zero in length.; SecurityException - if the device is locked and content protection is enabled, or if the application is not given permissions to read or write a Contact.
Category:: Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:: BlackBerry API 6.0.0