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], "5195551234");

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 - line is already active.
Category: Signed static int LINE_NOT_AVAILABLE
          Pre-switching validation failure reason - line 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 PhoneListener with the system.
Category: Signed static void clearVoicemailIndicator(int lineId)
          Clears (removes) the voicemail indicator for the given line.
Category: Signed static PhoneCall getActiveCall()
          Retrieves 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)
          Retrieves call by ID.
Category: Signed static String getDevicePhoneNumber(boolean format)
          Retrieves a device's phone number if present.
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)
          Retrieves 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.
Category: Signed static int getWAF(int lineId)
          Returns the WAF for a given line.
Category: Signed static void initiateCall(int lineId, String dest)
          Switches the line id to that which is specified and initiates a phone call to the specified phone number.
Category: Signed static boolean isLineAvailable(int lineId)
          Verifies a line's availability to make outgoing calls or receive incoming calls.
Category: Signed static boolean isVoicemailIndicatorOn(int lineId)
          Queries the line to see if the voicemail indicator is turned on, indicating to the user that there are one or more voicemail 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 - line 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 - 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()
Retrieves the currently active phone call.

Returns:
The currently active call.
Throws:
ControlledAccessException - thrown 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 4.0.0

getCall

public static PhoneCall getCall(int callid)
Retrieves call by ID.

Parameters:
callid - ID of the call to retrieve.
Returns:
PhoneCall corresponding to callid, or null if callid is invalid.
Throws:
ControlledAccessException - thrown 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 4.0.0

addPhoneListener

public static void addPhoneListener(PhoneListener pl)
Registers a PhoneListener with the system. Applications should de-register any PhoneListener objects before closing.

Parameters:
pl - Listener to handle phone events.
Throws:
ControlledAccessException - thrown if the user is not granted 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 - thrown 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 4.0.0

getDevicePhoneNumber

public static String getDevicePhoneNumber(boolean format)
Retrieves a device's phone number if present.

Parameters:
format - True if you wish to retrieve the phone number in its formatted form, which varies from region to region.
Returns:
A String representing the device's phone number, or null if no phone number is currently available.
Throws:
ControlledAccessException - thrown 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 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 for which to retrieve a phone number.
Returns:
The non-formatted phone number as a String.
Throws:
InvalidIDException - If the line ID is not valid.
ControlledAccessException - thrown 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
Retrieves a line description.

Parameters:
lineId - - The line ID for which to retrieve a description.
Returns:
The line description as a String.
Throws:
InvalidIDException - If the line ID is not valid.
ControlledAccessException - thrown 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

getWAF

public static int getWAF(int lineId)
                  throws InvalidIDException
Returns the WAF for a given line.

Parameters:
lineId - The line ID for which to return the WAF.
Returns:
A bitmask of 3GPP = 1, CDMA = 2, WLAN = 4 and IDEN = 8.
Throws:
InvalidIDException - If the line ID is not valid.
ControlledAccessException - thrown 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

getLineType

public static int getLineType(int lineId)
                       throws InvalidIDException
Returns the line type. A line type can be mobile or PBX.

Parameters:
lineId - The line ID for which to return the line type.
Returns:
1 = mobile; 2 = PBX and 0 = neither.
Throws:
InvalidIDException - If the line ID is not valid.
ControlledAccessException - thrown 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

getLineIds

public static int[] getLineIds()
Returns all the line IDs of a device.

Returns:
A primitive int array of line IDs.
Throws:
ControlledAccessException - thrown 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

isLineAvailable

public static boolean isLineAvailable(int lineId)
Verifies a line's availability 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 - thrown 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

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 - thrown 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

getLineId

public static int getLineId(int callId)
                     throws InvalidIDException
Returns the line ID associated with a connected call .

Parameters:
callId - - The ID for the call for which to retrieve the line ID.
Returns:
The line ID for the specified call.
Throws:
ControlledAccessException - thrown if the user is not granted to use the phone features.
InvalidIDException - If the specified call is not in the connected state.
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 phone listener's preSwitchingConditionFailure() callback will be invoked if:
1. The 1ine does not exist
2. The line is not available
3. The line is already active
4. A call is already in progress
5. Line switching is already in progress

Parameters:
lineId - The ID of the line to switch to.
Throws:
ControlledAccessException - thrown 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

initiateCall

public static void initiateCall(int lineId,
                                String dest)
                         throws RadioException
Switches the line id to that which is specified and initiates a phone call to the specified phone number. The phone listener's preSwitchingConditionFailure() callback will be invoked if:
1. The 1ine does not exist
2. The line is not available
3. The line is already active
4. A call is already in progress
5. Line switching is already in progress

Parameters:
lineId - The ID of the line to switch to.
dest - The destination phone numberfor which to initiate a call.
Throws:
ControlledAccessException - thrown if the user is not granted 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)
Queries the line to see if the voicemail indicator is turned on, indicating to the user that there are one or more voicemail messages waiting.

Parameters:
lineId - The ID of the line to query.
Returns:
True if the voicemail indicator is currently displayed for the line, false otherwise.
Throws:
ControlledAccessException - thrown 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

clearVoicemailIndicator

public static void clearVoicemailIndicator(int lineId)
Clears (removes) the voicemail indicator for the given line.

Parameters:
lineId - The ID of the line whose indicator should be removed.
Throws:
ControlledAccessException - thrown 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





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.