net.rim.blackberry.api.phone
Class Phone

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

public final class Phone
extends Object

This class provides the following:

Multi-line examples

Example A: Switching a line

  1. Create a class that extends MultiLineListener.
    public class MultiLineAction extends MultiLineListener
  2. Register the class as a PhoneListener.
    Phone.addPhoneListener(this);
  3. 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" );
     }
  4. Invoke Phone.setPreferredLine().
    Phone.setPreferredLine( Phone.getLineIds()[0]);

Example B: Initiate an outgoing call

  1. Invoke Phone.initiateCall.
    Phone.initiateCall(Phone.getLineIds()[0], "5195550123");
  2. 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
Category: Signed static int CALL_IN_PROGRESS
          Pre-switching validation failure reason - there is already a call in progress.
Category: Signed static int EMERGENCY_CALLBACK
          Pre-switching validation failure reason - the phone's network service is in emergency mode.
Category: Signed static int LINE_ALREADY_ACTIVE
          Pre-switching validation failure reason - the line is already active.
Category: Signed static int LINE_NOT_AVAILABLE
          Pre-switching validation failure reason - the line is not available.
Category: Signed static int LINE_NOT_EXIST
          Pre-switching validation failure reason - the line does not exist.
Category: Signed static int MOBILE_TYPE
          Represents mobile line type.
Category: Signed static int PBX_TYPE
          Represents PBX line type.
Category: Signed static int SWITCHING_IN_PROGRESS
          Pre-switching validation failure reason - the phone is in the process of switching to a new line.
 
Method Summary
Category: Signed static void addPhoneListener(PhoneListener pl)
          Registers a phone listener with the system.
Category: Signed static void clearVoicemailIndicator(int lineId)
          Clears (removes) the voice mail indicator for a specified line.
Category: Signed static PhoneCall getActiveCall()
          Returns the currently active phone call.
Category: Signed static int getActiveLineId()
          Returns the line ID that is currently used for dialing.
Category: Signed static PhoneCall getCall(int callid)
          Returns the call by ID.
Category: Signed static Vector getContactsByPhoneNumber(String phoneNumber)
          Returns the contacts that match a specified phone number.
Category: Signed static String getDevicePhoneNumber(boolean format)
          Returns a device's phone number.
Category: Signed static int getLineId(int callId)
          Returns the line ID associated with a connected call.
Category: Signed static int[] getLineIds()
          Returns all the line IDs of a device.
Category: Signed static String getLineLabel(int lineId)
          Returns a line description.
Category: Signed static String getLineNumber(int lineId)
          Returns a phone number for a given line ID.
Category: Signed static int getLineType(int lineId)
          Returns the line type for a given line ID.
Category: Signed static int getWAF(int lineId)
          Returns the WAF for a given line ID.
Category: Signed static void initiateCall(int lineId, String dest)
          Switches the line ID and initiates a phone call to the specified phone number.
Category: Signed static boolean isLineAvailable(int lineId)
          Determines whether or not a line is available to make outgoing calls or receive incoming calls.
Category: Signed 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.
Category: Signed static void removePhoneListener(PhoneListener pl)
          De-registers a phone listener from the system.
Category: Signed 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:

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:

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.