Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Phone

The net.rim.blackberry.api.phone package contains the APIs that you can use to access the phone application on the BlackBerry device. You can use this package to make calls, switch between available phone lines, receive notification events, and change phone options.

Making a call from a BlackBerry device application

BlackBerry devices can support multiple types of phone lines, including the cellular lines that are provided by a wireless service provider and work lines that are integrated with an organization's PBX phone system. You can create an application that interacts with the phone lines that are available on a device. You can verify the types of phone lines that are available, and use a specific phone line to make an outgoing call.

Make a call from a BlackBerry device application (single-line environment)

Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.invoke.PhoneArguments;

Create an instance of the PhoneArguments class, passing in the ARG_CALL field, and the destination phone number.

PhoneArguments call = new PhoneArguments(PhoneArguments.ARG_CALL, "519-555-0100");

Invoke Invoke.invokeApplication() to open the phone application from your application, providing the APP_TYPE_PHONE field, and the PhoneArguments instance.

Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, call);

Check for IllegalArgumentException.

Make a call from a BlackBerry device application (multi-line environment)

Import the required classes and interfaces.

import net.rim.blackberry.api.phone.Phone;
import net.rim.device.api.system.RadioException;

Invoke initiateCall() to use a specific phone line to make a call. For the destination number, pass in a hard-coded number or user text. In the following code sample, the application makes a call to the destination number 519-555-0100 and uses the line ID that returns at index 0.

Phone.initiateCall(Phone.getLineIds()[0], "519-555-0100");

Add DTMF tones to the send queue

Import the required class.

import net.rim.blackberry.api.phone.PhoneCall;

To add a single DTMF tone to the send queue, invoke PhoneCall.sendDTMFTone().

PhoneCall pc = new PhoneCall();
boolean added = pc.sendDTMFTone('7');

To add multiple DTMF tones to the send queue, invoke PhoneCall.sendDTMFTones().

PhoneCall ph = new PhoneCall();
boolean added = ph.sendDTMFTones("72");

BlackBerry DTMF tones

Key

Low Tone (Hz)

High Tone (Hz)

1

697

1209

2

697

1336

3

697

1477

4

770

1209

5

770

1336

6

770

1477

7

852

1209

8

852

1336

9

852

1477

0

941

1209

*

941

1336

#

941

1477

Listen for and handle phone events

You can configure your app to listen for and automatically handle various phone events by implementing the PhoneListener interface. The PhoneListener interface provides a set of callback methods that you can use to receive notification of phone events.

Import the required classes and interfaces.

import net.rim.blackberry.api.phone.*;

Create a class that implements the PhoneListener interface.

Register the class that implements PhoneListener by invoking addPhoneListener().

Phone.addPhoneListener(this);

Handle incoming phone events by using the PhoneListener callback methods. For example, to receive notification that a call is disconnected, implement the notification in callDisconnected(int); to receive notification that a new call has arrived, implement the notification in callIncoming(int); and to receive notification that a call is waiting, implement the notification in callWaiting(int).

To deregister the PhoneListener, invoke Phone.removePhoneListener().

 Phone.removePhoneListener(this);

Listen for and handle multi-line events

For BlackBerry devices that support multiple phone lines, you can configure your application to listen for and automatically handle multi-line phone events by using the MultiLineListener class. The MultiLineListener class is a helper class that implements the PhoneListener interface and provides a set of callback methods that you can use to receive notification of multi-line phone events.

Import the required classes.

import net.rim.blackberry.api.phone.Phone;
import net.rim.blackberry.api.phone.MultiLineListener;

Create a class that extends MultiLineListener.

Register the class as a PhoneListener by invoking Phone.addPhoneListener().

Phone.addPhoneListener(this);

To handle line switching events, perform the following actions:

Override the MultiLineListener callback methods to notify the application when a line switching event occurs. This is particularly important when using this feature on devices that operate on CDMA networks, as a delay might occur when the application switches between phone lines.

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

Invoke Phone.setPreferredLine(), passing in the line ID of the phone line to switch to. In the following code sample, the application selects the line that returns at index 0.

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

Retrieve call information by using call logs

Call information on a BlackBerry device is recorded in the call logs which can be accessed from the messages list. The call logs are stored in call log folders that you can access by using the PhoneLogs.FOLDER_NORMAL_CALLS or PhoneLogs.FOLDER_MISSED_CALLS constants.

Import the required classes.

import net.rim.blackberry.api.phone.phonelogs.*;

Invoke getInstance() to retrieve an instance of the call log.

PhoneLogs _logs = PhoneLogs.getInstance();

Invoke numberOfCalls() to retrieve the total number of calls in a specified call log folder (FOLDER_MISSED_CALLS or FOLDER_NORMAL_CALLS).

int numberOfCalls = _logs.numberOfCalls(PhoneLogs.FOLDER_NORMAL_CALLS);

Invoke PhoneLogs.callAt() to retrieve call information from a call log, passing in the index for the call log, and the call log folder.

PhoneCallLog phoneLog = (PhoneCallLog)_logs.callAt(0,PhoneLogs.FOLDER_NORMAL_CALLS);

Invoke PhoneCallLog.getType() to retrieve the call type. The possible return values are TYPE_MISSED_CALL_OPENED, TYPE_MISSED_CALL_UNOPENED, TYPE_PLACED_CALL, or TYPE_RECEIVED_CALL.

int phoneType = phoneLog.getType();

Retrieve a call participant

You can use the PhoneCallLogID and ConferencePhoneCallLog classes to retrieve a call participant from a the call log.

Import the required classes and interfaces.

import net.rim.blackberry.api.phone.phonelogs.*;

Invoke PhoneCallLog.getParticipant() or ConferencePhoneCallLog.getParticipantAt() to retrieve the call particpant information.

PhoneCallLogID participant = myPhoneCallLog.getParticipant();
PhoneCallLogID participant = myConferencePhoneCallLog.getParticipantAt(0);

Retrieve call information

Import the required class.

import net.rim.blackberry.api.phone.PhoneCall;

Invoke PhoneCall.getElapsedTime() to retrieve the length of time of the current call. Invoke PhoneCall.getStatus() to retrieve the connection status for the call. Invoke PhoneCall.getDisplayPhoneNumber() to retrieve the phone number of the call. In the following code sample, a status message displays on the screen when the phone call has lasted more than 120 seconds.

int threshold = 120; 
int elapsedTime = call.getElapsedTime();

int status = call.getStatus();
if ((status == PhoneCall.STATUS_CONNECTED 
   || status == PhoneCall.STATUS_CONNECTING) 
   && call.isOutGoing() && elapsedTime > threshold)
{
   String phoneNumber = call.getDisplayPhoneNumber();
   Status.show("Your call to " + call.getDisplayPhoneNumber() + " has lasted more than " + 
      (String)threshold + ".");
}

Retrieve the phone number of a BlackBerry device

Import the required class.

import net.rim.blackberry.api.phone.Phone;

Invoke Phone.getDevicePhoneNumber(), passing in true to return the phone number in its regional format.

String phNumber = Phone.getDevicePhoneNumber(true);

Check for ControlledAccessException to catch instances where your application does not have permission to access the phone number information.

Retrieve a call by call ID

Import the required classes.

import net.rim.blackberry.api.phone.Phone;
import net.rim.blackberry.api.phone.PhoneCall;

Invoke Phone.getCall(), passing in the call ID of the call to be retrieved.

PhoneCall ph = Phone.getCall(5);

Displaying content on a call screen

On BlackBerry devices that are running BlackBerry Device Software 5.0 or later, you can customize the incoming call screen and active call screen to display content by using the Phone Screen API that is provided in the net.rim.blackberry.api.phone.phonegui package. For example, you can display information that is provided by your application when a BlackBerry device user receives a call from a specific caller.

The device displays the content on the lower part of the call screen. If multiple applications provide content for a call screen, the device displays each application's content in sequence for approximately two seconds until the next call screen appears. For example, if you display content on the incoming call screen, the device displays the content until the user answers the call and the active call screen appears.

The Phone Screen sample application that is included in the demonstrates how to use this API.


This screen shows a customized phone screen.

Code sample: Displaying content on a phone screen

To make sure that the following sample application runs in the background when the BlackBerry device starts: In the BlackBerry Java Plug-in for Eclipse, change the BlackBerry application descriptor for the sample application.

In the following code sample, custom content is added to the incoming call screen by overriding AbstractPhoneListener.callIncoming(). You can display content on other call screens by overriding callWaiting(), callInitiated(), and callAnswered().

import net.rim.blackberry.api.phone.*;
import net.rim.blackberry.api.phone.phonegui.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;

//Create the application framework by extending the Application class. In the 
//constructor, invoke Phone.addPhoneListener() to register the listener. 
//In main(), invoke enterEventDispatcher() to enable the app to receive events.  
public final class MyPhoneScreen extends Application
{
    public MyPhoneScreen()
    {
        Phone.addPhoneListener(new MyPhoneScreenContent());
    }
    public static void main(String[] args)
    {
        new MyPhoneScreen().enterEventDispatcher();
    }
}

//Create a class that extends the AbstractPhoneListener class. Create a 
//constructor for this new class.
final class MyPhoneScreenContent extends AbstractPhoneListener
{
    public MyPhoneScreenContent()
    {

    }

//In the class that extendsAbstractPhoneListener, override 
//AbstractPhoneListener.callIncoming(). Create an instance of the ScreenModel 
//class. Obtain an instance of the incoming call screen by invoking 
//ScreenModel.getPhoneScreen(). Pass in parameters to specify the call screen 
//orientation and type that you want to obtain. In the following code sample, 
//the portrait orientation of the incoming call screen is obtained. Devices 
//with touch screens support portrait and landscape orientations, so pass in 
//PhoneScreen.LANDSCAPE.  
    public void callIncoming(int callId)
    {
        ScreenModel screenModel = new ScreenModel(callId);
        PhoneScreen phoneScreenPortrait = 
                screenModel.getPhoneScreen(
                     PhoneScreen.PORTRAIT, PhoneScreen.INCOMING);

//In callIncoming(), create custom content to add to the call screen. In 
//this example, text is added to the incoming call screen by using label 
//fields. Override LabelField.paint() to change the color.  
        LabelField labelField1 = new LabelField("Hello")
        {
            public void paint(Graphics g)
            {
                g.setColor(Color.GREEN);
                super.paint(g);
            }
        };    
        LabelField labelField2 = new LabelField(" to the World.")
        {
            public void paint(Graphics g)
            {
                g.setColor(Color.RED);
                super.paint(g);
            }
        };

//In callIncoming(), specify the font for the custom content. In this 
//example, the font from the call screen is used. Invoke 
//PhoneScreen.getCallerInfoFont() to obtain the font used by the call screen. 
//Invoke Field.setFont() and pass in the call screen font to specify
//the font for the label fields. Invoke PhoneScreen.add() to add the 
//label fields to the call screen.  
        labelField1.setFont(phoneScreenPortrait.getCallerInfoFont());
        labelField2.setFont(phoneScreenPortrait.getCallerInfoFont());

        phoneScreenPortrait.add(labelField1);
        phoneScreenPortrait.add(labelField2); 

//In callIncoming(), invoke ScreenModel.sendAllDataToScreen() to add the  
//custom content to the incoming call screen.  
        screenModel.sendAllDataToScreen();
    }
}

Displaying content on devices that operate on a CDMA network

The Phone application on a BlackBerry device displays the active call screen when a user answers a call or makes a call. After the user answers a call, the user can receive and answer a second call. On devices that operate on a CDMA network, the second call does not invoke the same events that the original call does. For these devices, to display custom content on the active call screen, you must override the AbstractPhoneListener.callAnswered() method and AbstractPhoneListener.callWaiting() method.

Method

Description

callAnswered()

To display content on the first active call screen, override AbstractPhoneListener.callAnswered() and obtain call screen objects for the active call. The Phone application invokes this method when the user answers the first call. On devices that operate on a GSM network, the Phone application invokes this method when the user answers the first call and second call.

callWaiting()

To display content on the second active call screen, override AbstractPhoneListener.callWaiting() and obtain call screen objects for the active call. The Phone application invokes this method when the user answers the second call.

Code sample: Displaying content on devices that operate on a CDMA network

The following code sample demonstrates how to override AbstractPhoneListener.callWaiting(). You can check whether the device operates on a CDMA network by using the RadioInfo class. You obtain the instances of the active call screen by invoking ScreenModel.getPhoneScreen() and passing in PhoneScreen.ACTIVE so that you are only specifying content for the second call.

public void callWaiting(int callId)
{
    // For CDMA devices, specify the content for the active call screen
    if((RadioInfo.getSupportedWAFs() & RadioInfo.WAF_CDMA) != 0)
    {
        ScreenModel screenModel = new ScreenModel(callId);

        PhoneScreen phoneScreenPortrait = screenModel.getPhoneScreen(
                      PhoneScreen.PORTRAIT, PhoneScreen.ACTIVE);
 
        PhoneScreen phoneScreenLandscape = screenModel.getPhoneScreen(
                      PhoneScreen.LANDSCAPE, PhoneScreen.ACTIVE);
    }
   
    // For GSM and CDMA devices, specify content for the incoming call screen.
}