net.rim.blackberry.api.phone
Class Phone
java.lang.Object
net.rim.blackberry.api.phone.Phone
public final class Phone
- 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.
- Multi-line support for GSM devices.
- Data integration on the incoming and active call screens of specific devices.
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 |
|
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 - line is already active. |
|
static int |
LINE_NOT_AVAILABLE
Pre-switching validation failure reason - line 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 PhoneListener with the system. |
|
static void |
clearVoicemailIndicator(int lineId)
Clears (removes) the voicemail indicator for the given line. |
|
static PhoneCall |
getActiveCall()
Retrieves the currently active phone call. |
|
static int |
getActiveLineId()
Returns the line ID that is currently used for dialing. |
|
static PhoneCall |
getCall(int callid)
Retrieves call by ID. |
|
static String |
getDevicePhoneNumber(boolean format)
Retrieves a device's phone number if present. |
|
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)
Retrieves 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. |
|
static int |
getWAF(int lineId)
Returns the WAF for a given line. |
|
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. |
|
static boolean |
isLineAvailable(int lineId)
Verifies a line's availability to make outgoing calls or receive incoming calls. |
|
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. |
|
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. |
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
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.