Developers

Local Navigation

Home  >  Developers  >  Resources  >  Developer Journals  >  January 2005  > 

API Spotlight: BlackBerry Apps Phones Home

Richard Evers, Editor

Research In Motion released its first voice-enabled BlackBerry Wireless Handheld in 2002. The BlackBerry® 5800 series of wireless handhelds supported two cellular bands on the GSM™/GPRS network.

RIM has advanced their voice support technology over the past two and a half years to include:

  • Nextel's iDEN® network in the United States
  • CDMA2000® 1X wireless networks in North America (800/1900 MHz)
  • GSM/GPRS wireless networks in North, Central and South America, the Caribbean, Europe, North Africa, India and Asia Pacific (850/900/1800/1900 MHz)

Topics within this section include:

BlackBerry JDE version 4.0

Research In Motion has made available the BlackBerry JDE v4.0. For the first time in RIM’s history, developers can create phone applications in Java. The phone package is a controlled API and developers must sign their applications. For more information, please see Jonathan Nobel’s article, "Give me a Sign", in Volume 1, Issue 2 of the BlackBerry Developer Journal.

You can put together an application that encapsulates a telephone call in a PhoneCall object. Once you have the object, you can access call particulars such as the telephone number, call status, elapsed time, and determine it it’s an outgoing or incoming call. You can also send DTMF tones and review tones that are in the send queue.

All telephone-related events such as callAnswered, callConnected, callDisconnected, callHeld, callFailed and others can be tapped by setting up listeners to deal with each event. Errors passed to callFailed can be interrogated against a slew of values defined in the default interface.

If you need to make a call from within your application, set up PhoneArguments, and then invoke the phone application directly.

Finally, you can manipulate phone logs to retrieve, add, delete and replace call info, set up listeners and more.

Taken as a whole, this is a nice enhancement to the BlackBerry API.

Top

Package: net.rim.blackberry.api.phone

The phone package consists of:

  • An extensive interface called PhoneListener
  • A helper class called AbstractPhoneListener, which defines an empty implementation of the interface
  • Working classes called Phone and PhoneCall that are used to set up listeners to handle notification events, access phone particulars and send and review DTMF tones
  • Error fields for use with the callFailed event

The following are methods defined in the PhoneListener interface, and skeletally implemented in the AbstractPhoneListener class:

PhoneListener Method Invoked when ...
callAdded() A call is added to a conference call
callAnswered() User answers a call
(user driven)
callConferenceCallEstablished() Conference call has been established
callConnected() Network indicates a connected event
(network driven)
callDirectConnectConnected() Direct Connect® call is connected
callDirectConnectDisconnected() Direct Connect call is disconnected
callDisconnected() Call disconnected
callEndedByUser() User ends the call
callFailed() Call failed
callHeld() Call went into the 'held' state
callIncoming() New call is arriving
callInitiated() Call has been initiated by the handheld
(outbound)
callRemoved() Call removed from a conference call
callResumed() Call went from 'held' to 'resumed' state
callWaiting() Call is waiting
conferenceCallDisconnected() Conference call is terminated
(all members disconnected)

Top

PhoneListener Error Fields Description
CALL_ERROR_AUTHORIZATION_FAILURE Authorization failure
CALL_ERROR_CALL_REPLACED_BY_STK Call replaced by STK
(GSM SIM specific)
CALL_ERROR_CONGESTION Congestion
CALL_ERROR_CONNECTION_
DENIED_BY_NETWORK		 Connection denied by network
CALL_ERROR_DUE_TO_FADING Call failed because of signal fading
CALL_ERROR_EMERGENCY_CALLS_ONLY Emergency calls only
CALL_ERROR_FDN_MISMATCH Fixed dialing number mismatch
CALL_ERROR_GENERAL General call error
CALL_ERROR_HOLD_ERROR Hold error
CALL_ERROR_INCOMING_CALL_BARRED Incoming call barred
CALL_ERROR_LOST_DUE_TO_FADING Call lost because of signal fading
CALL_ERROR_MAINTENANCE_REQUIRED Maintenance required
CALL_ERROR_NUMBER_NOT_IN_SERVICE Number not in service
(iDEN specific)
CALL_ERROR_NUMBER_UNOBTAINABLE Number unobtainable
CALL_ERROR_OUTGOING_CALLS_BARRED Outgoing call barred
CALL_ERROR_PLEASE_TRY_LATER Please try call later
(iDEN specific)
CALL_ERROR_RADIO_PATH_UNAVAILABLE Radio path unavailable
CALL_ERROR_SERVICE_CONFLICT Service conflict TI
(iDEN specific)
CALL_ERROR_SERVICE_NOT_AVAILABLE Service not available
CALL_ERROR_SUBSCRIBER_BUSY Subscriber busy
CALL_ERROR_SYSTEM_BUSY_TRY_LATER System busy, try later
(iDEN specific)
CALL_ERROR_TRY_AGAIN Call failed, please try again
CALL_ERROR_USER_BUSY_IN_DATA User busy in data
(iDEN specific)
CALL_ERROR_USER_BUSY_IN_PRIVATE User busy in private
(iDEN specific)
CALL_ERROR_USER_NOT_AUTHORIZED User not authorized
(iDEN specific)
CALL_ERROR_USER_NOT_AVAILABLE User not available
(iDEN specific)
CALL_ERROR_USER_NOT_REACHABLE User not reachable
(iDEN specific)
CALL_ERROR_USER_UNKNOWN User unknown
(iDEN specific)

Top

The Phone Class
net.rim.blackberry.api.phone.Phone

The Phone class provides four methods to interact with the BlackBerry phone application:

  • addPhoneListener()
    Registers a phone listener with the system
  • removePhoneListener()
    De-registers a phone listener from the system
  • getActiveCall()
    Retrieves the active cell phone call
  • getCall()
    Retrieves cell phone call by identifier

Top

Phone.addPhoneListener()

Description

Registers a phone listener with the system. Once in place, you can catch most events such as callAnswered(), callFailed() and other desired actions.

Syntax

void addPhoneListener(PhoneListener pl)

Parameters

An object of the class that will handle events

Returns

Nothing

Example

/*
 * MyPhone.java
 */
package com.blackberrydeveloper.myphone;

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

public final class MyPhone extends AbstractPhoneListener {
  static public void main(String[] args)
  {
    MyPhone.registerOnStartup();
  }

  static private void registerOnStartup()
  {
    MyPhone phone_handler = new MyPhone();
    Phone.addPhoneListener(phone_handler);
  }
  private MyPhone(){}

  private void checkCall(String ehandler, int callid)
  {
    PhoneCall callInfo = Phone.getCall(callid);

    if ( callInfo != null ) {
      /*
       * Event Handler: ehandler
       * Telephone No.: callInfo.getDisplayPhoneNumber();
       * Elapsed Time : callInfo.getElapsedTime();
       * Call Status  : callInfo.getStatusString();
      */
    }
  }

  // A call has been added to a conference call
  public void callAdded(int callId)
  { checkCall("callAdded", callId); }

  // User answered a call
  public void callAnswered(int callId)
  { checkCall("callAnswered", callId); }

  // Conference call established
  public void callConferenceCallEstablished(int callId)
  { checkCall("callConferenceCallEstablished", callId); }

  // Network indicates a connected event
  public void callConnected(int callId)
  { checkCall("callConnected", callId); }

  // Direct-connect call connected
  public void callDirectConnectConnected(int callId)
  { checkCall("callDirectConnectConnected", callId); }

  // Direct-connect call disconnected
  public void callDirectConnectDisconnected(int callId)
  { checkCall("callDirectConnectDisconnected", callId); }

  // Call disconnected
  public void callDisconnected(int callId)
  { checkCall("callDisconnected", callId); }

  // User ended call
  public void callEndedByUser(int callId)
  { checkCall("callEndedByUser", callId); }

  // Call has been placed on "hold"
  public void callHeld(int callId)
  { checkCall("callHeld", callId); }

  // New call has arrived
  public void callIncoming(int callId)
  { checkCall("callIncoming", callId); }

  // Outbound call initiated by the handheld
  public void callInitiated(int callid)
  { checkCall("callInitiated", callid); }

  // Call removed from a conference call
  public void callRemoved(int callId)
  { checkCall("callRemoved", callId); }

  // Call taken off of "hold"
  public void callResumed(int callId)
  { checkCall("callResumed", callId); }

  // Call is waiting
  public void callWaiting(int callid)
  { checkCall("callWaiting", callid); }

  // Conference call has been terminated
  // (all members disconnected)
  public void conferenceCallDisconnected(int callId)
  { checkCall("conferenceCallDisconnected", callId); }

  // Call failed
  public void callFailed(int callId, int reason)
  {
    checkCall("callFailed", callId);

    // determine reason
    switch( error ) {
      case PhoneListener.CALL_ERROR_AUTHORIZATION_FAILURE: break;
      case PhoneListener.CALL_ERROR_CALL_REPLACED_BY_STK: break;
      case PhoneListener.CALL_ERROR_CONGESTION: break;
      case PhoneListener.CALL_ERROR_CONNECTION_DENIED_BY_NETWORK: break;
      case PhoneListener.CALL_ERROR_DUE_TO_FADING: break;
      case PhoneListener.CALL_ERROR_EMERGENCY_CALLS_ONLY: break;
      case PhoneListener.CALL_ERROR_FDN_MISMATCH: break;
      case PhoneListener.CALL_ERROR_GENERAL: break;
      case PhoneListener.CALL_ERROR_HOLD_ERROR: break;
      case PhoneListener.CALL_ERROR_INCOMING_CALL_BARRED: break;
      case PhoneListener.CALL_ERROR_LOST_DUE_TO_FADING: break;
      case PhoneListener.CALL_ERROR_MAINTENANCE_REQUIRED: break;
      case PhoneListener.CALL_ERROR_NUMBER_NOT_IN_SERVICE: break;
      case PhoneListener.CALL_ERROR_NUMBER_UNOBTAINABLE: break;
      case PhoneListener.CALL_ERROR_OUTGOING_CALLS_BARRED: break;
      case PhoneListener.CALL_ERROR_PLEASE_TRY_LATER: break;
      case PhoneListener.CALL_ERROR_RADIO_PATH_UNAVAILABLE: break;
      case PhoneListener.CALL_ERROR_SERVICE_CONFLICT: break;
      case PhoneListener.CALL_ERROR_SERVICE_NOT_AVAILABLE: break;
      case PhoneListener.CALL_ERROR_SUBSCRIBER_BUSY: break;
      case PhoneListener.CALL_ERROR_SYSTEM_BUSY_TRY_LATER: break;
      case PhoneListener.CALL_ERROR_TRY_AGAIN: break;
      case PhoneListener.CALL_ERROR_USER_BUSY_IN_DATA: break;
      case PhoneListener.CALL_ERROR_USER_BUSY_IN_PRIVATE: break;
      case PhoneListener.CALL_ERROR_USER_NOT_AUTHORIZED: break;
      case PhoneListener.CALL_ERROR_USER_NOT_AVAILABLE: break;
      case PhoneListener.CALL_ERROR_USER_NOT_REACHABLE: break;
    }
  }
}

Top

Phone.removePhoneListener()

Description

De-registers a phone listener from the system

Syntax

void removePhoneListener(PhoneListener pl)

Parameters

An object of the class that has been handling events

Returns

Nothing

Example

...
MyPhoneDeregister phone_handler;
...

  // call this method on exit to deregister the phone listener
  private callOnExit()
  {
    Phone.removePhoneListener(phone_handler);
  }
}

Top

Phone.getCall()

Description

Retrieves a specific telephone call encapsulated within a PhoneCall object

Syntax

PhoneCall getCall(int callid)

Parameters

A call identifier that is provided by one of the PhoneListener methods

Returns

An instance of the PhoneCall, or null if no such call has been built by the phone application

Example

private void checkIt(int callid) {
  PhoneCall callInfo = Phone.getCall(callid);

  if ( callInfo != null ) {
    /*
     * do something
     */
  }
}

Top

Phone.getActiveCall()

Description

Retrieves the active telephone call encapsulated within a PhoneCall object

Syntax

PhoneCall getActiveCall()

Parameters

None

Returns

A PhoneCall object encapsulating the active phone call

Example

private void getActCall() {  PhoneCall callInfo = Phone.getActiveCall();  if ( callInfo != null ) {    /*     * do something    */  }}

Top

The PhoneCall Class
net.rim.blackberry.api.phone.PhoneCall

The PhoneCall class fully encapsulates a telephone call.

PhoneCall.getCallId()

Description

Returns an integer call identifier for the current call

Syntax

int getCallId()

Parameters

None

Returns

The call identifier

Example

private int getCID() {  PhoneCall callInfo = Phone.getActiveCall();  int theID = -1;  if ( callInfo != null )    theID = callInfo.getCallId();  return theID;}

Top

PhoneCall.getDisplayPhoneNumber()

Description

Retrieves the current call's telephone number in String form

Syntax

String getDisplayPhoneNumber()

Parameters

None

Returns

Telephone number in String form

Example

private void chkTelNo() {  PhoneCall callInfo = Phone.getActiveCall();  if ( callInfo != null ) {    String telNumber = callInfo.getDisplayPhoneNumber();  }}

Top

PhoneCall.getDTMFTones()

Description

Retrieves a list of DTMF tones for the current call that are in the send queue waiting to be transmitted. DTMF tones are comprised of a low and high frequency that are played at the same time, as shown in the table below:

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

Syntax

String getDTMFTones()

Parameters

None

Returns

A String list of DTMF tones composed of consecutive characters in the range of ‘0’ through ‘9’, ‘*’ and ‘#’

Example

private String getSendQueue() {  String theQueue;  PhoneCall callInfo = Phone.getActiveCall();  if ( callInfo != null )    theQueue = callInfo.getDTMFTones();  return theQueue;}

Top

PhoneCall.getElapsedTime()

Description

Retrieves the current call's elapsed time in seconds

Syntax

int getElapsedTime()

Parameters

None

Returns

Elapsed time in seconds

Example

private int getETime {  PhoneCall callInfo = Phone.getActiveCall();  int eTime = -1;  if ( callInfo != null )    eTime = callInfo.getElapsedTime();  return eTime;}

Top

PhoneCall.getStatus()

Description

Retrieves the status of the current call

Syntax

int getStatus()

Parameters

None

Returns

One of the STATUS_* values detailed below that describe the state of this call:

Call State Field Description
STATUS_CONNECTED Call is connected
STATUS_CONNECTED_MUTED Call connected, but muted
STATUS_CONNECTING Call is currently connecting, but not yet connected
STATUS_DISCONNECTED Call is disconnected
STATUS_HELD Call is being held

Example

private void handleCallStatus(int callid){  PhoneCall pc = Phone.getCall(callid);  if ( pc != null ) {    switch (pc.getCallStatus())    {      case PhoneCall.STATUS_CONNECTED:        // Call is connected        break;      case PhoneCall.STATUS_CONNECTED_MUTED:        // Call is connected, but muted        break;      case PhoneCall.STATUS_CONNECTING:        // Call is currently connecting,        // but not yet connected        break;      case PhoneCall.STATUS_DISCONNECTED:        // Call is disconnected        break;      case PhoneCall.STATUS_HELD:        // Call is being held        break;    }  }}

Top

PhoneCall.getStatusString()

Description

Retrieves the status of the current call in String form

Syntax

String getStatusString()

Parameters

None

Returns

A String containing the call status such as "Calling", "Connected", "Held", "Muted", "Disconnected", etc.

Example

private String getStatus() {  PhoneCall callInfo = Phone.getActiveCall();  String cStatus;  if ( callInfo != null )    cStatus = callInfo.getStatusString();  return cStatus;}

Top

PhoneCall.isOutgoing()

Description

Determines if the current call is an outgoing call

Syntax

boolean isOutgoing()

Parameters

None

Returns

True if the call is outgoing, else returns False

Example

private boolean isOut {  PhoneCall callInfo = Phone.getActiveCall();  boolean theDir = False;  if ( callInfo != null )    theDir = callInfo.isOutgoing();  return theDir;}

Top

PhoneCall.sendDTMFTone()

Description

Adds a DTMF tone to the current call's send queue

Syntax

boolean sendDTMFTone(char tone)

Parameters

The tone (‘0’ through ‘9’, plus ‘#’ and ‘*’)

Returns

Boolean success flag

Example

private boolean xmitExtension() {  PhoneCall callInfo = Phone.getActiveCall();  boolean isOkay = True;  if ( callInfo != null )    isOkay = callInfo.sendDTMFTone( '3' );  return isOkay;}

Top

PhoneCall.sendDTMFTones()

Description

Adds a number of DTMF tone to the current call's send queue

Syntax

boolean sendDTMFTones(String tones)

Parameters

A String list of tones to add to the call's send queue

Returns

True if entire list of tones were added to the queue

Example

private boolean xmitString(String TheExt) {  PhoneCall callInfo = Phone.getActiveCall();  boolean isOkay = True;  if ( callInfo != null )    isOkay = callInfo.sendDTMFTones(TheExt);  return isOkay;}

Top

The CallLog Class
net.rim.blackberry.api.phone.phonelogs.CallLog

CallLog is an abtract base class for phone call logs contained by the PhoneLogs class.

CallLog objects cannot be instantiated. Instead, use the PhoneCallLog or ConferencePhoneCallLog derived classes.

CallLog Methods Description
getDate() Call log date
getDuration() Logged call's duration
getNotes() Logged call's notes
getStatus() Logged call's status
setDate() Set the call's log date
setDuration() Set duration of logged call
setNotes() Sets notes for logged call
setStatus() Set status for logged call

Top

CallLog Field Description
STATUS_NORMAL No errors
STATUS_BUSY The call is busy
STATUS_CONGESTION Error: Network congestion
STATUS_PATH_UNAVAILABLE Error: Path is unavailable
STATUS_NUMBER_UNOBTAINABLE Error: Number cannot be reached
STATUS_AUTHENTICATION_FAILURE Error: Authorization failure
STATUS_EMERGENCY_CALLS_ONLY Only emergency calls are allowed
STATUS_HOLD_ERROR Error: Call hold
STATUS_OUTGOING_CALLS_BARRED Outgoing calls are barred
STATUS_GENERAL_ERROR A general error has occurred
STATUS_MAINTENANCE_REQUIRED Maintenance is required
STATUS_SERVICE_NOT_AVAILABLE Service is not available
STATUS_CALL_FAIL_DUE_TO_FADING Call failed due to fading of signal
STATUS_CALL_LOST_DUE_TO_FADING Call lost due to fading of signal
STATUS_CALL_FAILED_TRY_AGAIN Call failed, try again
STATUS_FDN_MISMATCH An FDN (Frequently Dialed Number) mismatch occurred
STATUS_CONNECTION_DENIED Call connection was denied
STATUS_INCOMING_CALL_BARRED Incoming calls are barred

Top

The PhoneLogs Class
net.rim.blackberry.api.phone.phonelogs.PhoneLogs

The PhoneLogs class consists of a container to maintain a list of CallLog objects that, together, represents the logs for telephone calls stored in the message list.

Telephone call logs are stored in two folders:

  • Missed calls
  • Normal calls

Once you have retrieved an instance of the PhoneLogs object using the getInstance() method, you can use the object to add, delete, or replace CallLog objects from the log.

Top

PhoneLogs.addCall()

Description

Adds a call to the log. The call will appear in the message list for viewing.

Syntax

void addCall(CallLog call)

Parameters

The call to be added to the log

Returns

Nothing

Example

private PhoneLogs _logs;..._logs = PhoneLogs.getInstance();...private void addLog(CallLog call) {  if (call instanceof PhoneCallLog) {    PhoneCallLog testCall = (PhoneCallLog)call;    _logs.addCall(testCall);  }}

Top

PhoneLogs.addListener()

Description

Registers a PhoneLogListener instance with the system

Syntax

static void addListener(PhoneLogListener listener)

Parameters

The listener to register

Returns

Nothing

Example

/* * MyPhoneLog.java */package com.blackberrydeveloper.myphonelog;import net.rim.blackberry.api.phone.phonelogs.*;public final class MyPhoneLog implements PhoneLogListener {  static public void main(String[] args)  {    MyPhoneLog.registerOnStartup();  }  static private void registerOnStartup()  {    MyPhoneLog mpl = new MyPhoneLog();    PhoneLogs.addListener(mpl);  }  private MyPhoneLog() {}  public void callLogAdded(CallLog cl)  {    // callLogAdded    showLogInfo(cl);  }  public void callLogUpdated(CallLog cl, CallLog oldCl)  {    // CallLogUpdated    showLogInfo(cl);    showLogInfo(oldCl);  }  public void callLogRemoved(CallLog cl)  {    // CallLogRemoved    showLogInfo(cl);  }  private void showLogInfo(CallLog cl)  {    String msg = "CallLog: "        + " Date:" + cl.getDate()        + " Duration:" + cl.getDuration()        + " Notes:" + cl.getNotes()        + " Status:" + cl.getStatus();  }}

Top

PhoneLogs.callAt()

Description

Retrieves a specific call from the log by index

Syntax

CallLog callAt(int index, long folderID)

Parameters

The index of the call within the phone log (range 0 to numberOfCalls-1)

The ID of the folder from which to retrieve the call

Returns

The CallLog object at the index if it exists, either a PhoneCallLog or a ConferencePhoneCallLog

Example

/* * get specific call log * * Pass the folder identifier: * if (PhoneCallLog.getType() == PhoneCallLog.TYPE_MISSED_CALL_OPENED * ||  PhoneCallLog.getType() == PhoneCallLog.TYPE_MISSED_CALL_UNOPENED ) *   pass PhoneLogs.FOLDER_MISSED_CALLS * else *   pass PhoneLogs.FOLDER_NORMAL_CALLS */private PhoneCallLog getCallLogAt(int index, long folder) {  PhoneCallLog thisCall;  PhoneLogs    thisLog = PhoneLogs.getInstance();  thisCall = (PhoneCallLog)thisLog.callAt(index, folder);  //-----------------------------------------  // Information from PhoneCallLog  //-----------------------------------------  // thisCall.getDate().getTime();  // thisCall.getDuration();  // thisCall.getNotes();  // thisCall.getStatus();  // thisCall.getType();  // thisCall.getParticipant().getName();  // thisCall.getParticipant().getAddressBookFormattedNumber();  //-----------------------------------------  return PhoneCallLog;}

Top

PhoneLogs.deleteCall()

Description

Deletes a call from the log

Syntax

void deleteCall(int index, log folderID)

Parameters

The index of the call within the phone log (range 0 to numberOfCalls-1)

The ID of the folder from which to retrieve the call

Returns

Nothing

Example

/* * delete specific call log from specific folder */private PhoneCallLog deleteCallLogAt(int index, long folder) {  PhoneLogs thisLog = PhoneLogs.getInstance();  thisLog.deleteCall(index, folder);}

Top

PhoneLogs.getInstance()

Description

Retrieves an instance of the phone log. This log object contains all the calls that appear in the message list.

Syntax

static PhoneLogs getInstance()

Parameters

None

Returns

Handle to the phone log

Example

/* * delete specific call log from specific folder */private PhoneCallLog deleteCallLogAt(int index, long folder) {  PhoneLogs thisLog = PhoneLogs.getInstance();  thisLog.deleteCall(index, folder);}

Top

PhoneLogs.numberOfCalls()

Description

Retrieves the number of calls in a call log folder

Syntax

int numberOfCalls(long folderID)

Parameters

The ID of the folder to check

Returns

The number of calls in the log at that instant

Example

/* * determine how many logs in both folders */private void countCallLogs() {  PhoneLogs thisLog = PhoneLogs.getInstance();  int Missed = thisLog.numberOfCalls(PhoneLogs.FOLDER_MISSED_CALLS);  int Normal = thisLog.numberOfCalls(PhoneLogs.FOLDER_NORMAL_CALLS);}

Top

PhoneLogs.removeListener()

Description

Removes a registered PhoneLogListener instance from the system

Syntax

static void removeListener(PhoneLogListener listener)

Parameters

The listener instance to remove

Returns

Nothing

Example

/* * MyPhoneDeregister.java */package com.rim.blackberrydeveloper.myphonelogsderegister;import net.rim.blackberry.api.phone.phonelongs.*;public final class MyPhoneLogsDeregister implements PhoneLogListener {  MyPhoneLogDeregister phonelog_handler;  static public void main(String[] args)  {    MyPhoneDeregister.registerOnStartup();  }  static private void registerOnStartup()  {    phonelog_handler = new MyPhoneLogsDeregister();    PhoneLogs.addListener(phonelog_handler);  }  private MyPhoneLogsDeregister() {}// add more working code to this class// then call this method on exit// to deregister the phone log listener  private callOnExit()  {    PhoneLogs.removeListener(phonelog_handler);  }}

Top

PhoneLogs.swapCall()

Description

Replaces the call at the given index with a new call.

Syntax

void swapCall(CallLog call, int index, long folderID)

Parameters

New call to add to the phone log

Index of the call to be replaced

Range: 0 to numberOfCalls-1

ID of the folder containing the calls to replace. Note that you can only swap a call within the same folder.

Returns

Nothing

Example

/* * replace call at passed index position within folder with passed call */private void swapThisCall(int index, long folder, CallLog toSwap ) {  PhoneLogs thisLog = PhoneLogs.getInstance();  int Max = thisLog.numberOfCalls(folder);  boolean isOkay = False;  if ( folder != PhoneLogs.FOLDER_NORMAL_CALLS  &&   folder != PhoneLogs.FOLDER_MISSED_CALLS ) {    // invalid folder ID  } else {    isOkay = (index>=0 && index<Max)?True:False;    if ( !isOkay ) {      // index is invalid    } else {      b>thisLog.swapCall(toSwap, index, folder);    }  }}

Top

The PhoneCallLog Class
net.rim.blackberry.api.phone.phonelogs.PhoneCallLog

The PhoneCallLog class extends CallLog and represents a call log in the message list for a simple phone call. You can set and change how the call is presented in the message list by adjusting the TYPE_* values. Only one call participant can be included in this form of log. For multiple participants, use the ConferencePhoneCallLog class.

Constructor

PhoneCallLog(  Date date, // call date  int callType, // see TYPE_* table to follow  int callDuration, // duration in seconds  int callStatus, // see CallLog.STATUS_*  PhoneCallLogID participant, // detailed later  String notes // notes associated with call)
PhoneCallLog Fields Description
TYPE_MISSED_CALL_OPENED Call was missed and has been viewed
TYPE_MISSED_CALL_UNOPENED Call was missed and has not been viewed
TYPE_PLACED_CALL Successfully connected outgoing call
TYPE_RECEIVED_CALL Successfully received incoming call

Top

PhoneCallLog.getParticipant()

Description

Retrieves the participant for the call. The participant information is presented both in the message list and when the log is opened for viewing.

Syntax

PhoneCallLogID getParticipant()

Parameters

None

Returns

Call participant

Example

private String getParticipant(CallLog cl) {  String msg = "CallLog:"    + " Date:" + cl.getDate()    + " Duration:" + cl.getDuration()    + " Notes:" + cl.getNotes()    + " Status:" + cl.getStatus();  if ( cl instanceof PhoneCallLog) {    PhoneCallLog pcl = (PhoneCallLog)cl;    msg += " Participant:"      + getNameNumber(pcl.getParticipant())      + " Type:"      + pcl.getType();  } else if (cl instanceof ConferencePhoneCallLog) {    ConferencePhoneCallLog cpcl = (ConferencePhoneCallLog)cl;    int el = cpcl.numberOfParticipants() - 1;    do    {      msg += " Participant:" + getNameNumber(cpcl.getParticipantAt(el));    } while (--el >= 0 );  }}private String getNameNumber(PhoneCallLogID id) {  return id.getName() + " " + id.getNumber();}

Top

PhoneCallLog.getType()

Description

Retrieves the call’s type

Syntax

int getType()

Parameters

None

Returns

Type for this call; one of the TYPE_* values.

Example

// Snippet from the getParticipant() example//  if ( cl instanceof PhoneCallLog) {    PhoneCallLog pcl = (PhoneCallLog)cl;    msg += " Particpant:"      + getNameNumber(pcl.getParticipant())      + " Type:"      + pcl.getType();  }

Top

PhoneCallLog.setParticipant()

Description

Sets the participant for thecall

Syntax

void setParticipant(PhoneCallLogID participant)

Parameters

New participant for this call

Returns

Nothing

Example

private void setWho() {  PhoneCallLogID No1 = new PhoneCallLogID("5551000");  PhoneCallLogID No2 = new PhoneCallLogID("5551001");  Date today = new Date(System.currentTimeMillis());  PhoneCallLog pcl = new PhoneCallLog    (today, PhoneCallLog.TYPE_RECEIVED_CALL,      60, PhoneCallLog.STATUS_NORMAL, No1, "NOTES");  // update participant  pcl.setParticipant(No2);}

Top

PhoneCallLog.setType()

Description

Set the call’s type

Syntax

void setType(int callType)

Parameters

None

Returns

New type for this call; one of the TYPE_* values.

Example

private void setTyp() {  PhoneCallLogID No1 = new PhoneCallLogID("5551000");  PhoneCallLogID No2 = new PhoneCallLogID("5551001");  Date today = new Date(System.currentTimeMillis());  PhoneCallLog pcl = new PhoneCallLog    (today, PhoneCallLog.TYPE_RECEIVED_CALL,      60, PhoneCallLog.STATUS_NORMAL, No1, "NOTES");  pcl.setType(PhoneCallLog.TYPE_MISSED_CALL_OPENED);}

Top

The ConferencePhoneCallLog Class
net.rim.blackberry.api.phone.phonelogs. ConferencePhoneCallLog

The ConferencePhoneCallLog class extends CallLog and represents a call log in the message list for a conference phone call (two or more participants). You can add or remove participants from a conference phone-call log as long as there are always at least two other participants involved with the call. Unlike PhoneCallLog, you cannot set the TYPE_* of a conference call.

Constructor

ConferencePhoneCallLog(  Date date, // call date  int callDuration, // duration in seconds  int callStatus, // see CallLog.STATUS_*  PhoneCallLogID caller1, // 1st participant  PhoneCallLogID caller2, // 2nd participant  String notes // notes associated with call)

Top

ConferencePhoneCallLog.addParticipant()

Description

Adds a call participant by appending the new participant to the end of the participant list.

Syntax

void addParticipant(PhoneCallLogID participant)

Parameters

New call participant

Returns

Nothing

Example

private void makeConference() {  PhoneCallLogID id1 = new PhoneCallLogID("5551000");  id1.setName("Stinky Pinky");  PhoneCallLogID id2 = new PhoneCallLogID("5551001");  id2.setName("Funky Monkey");  ConferencePhoneCallLog call = new ConferencePhoneCallLog      (new Date(System.currentTimeMillis()),      60,      ConferencePhoneCallLog.STATUS_NORMAL,      id1,      id2,      "A call note");  PhoneCallLogID id3 = new PhoneCallLogID("5551002");  id3.setName("Brain Drain");  call.addParticipant(id3);  PhoneCallLogID id4 = new PhoneCallLogID("5551003");  id4.setName("Happy Clappy");  call.addParticipant(id4);  for ( int el = 0; el < call.numberOfParticipants(); el++ )  {    if (call.getParticipantAt(el).getName() == null)      // problem!!!  }}

Top

ConferencePhoneCallLog.getParticipantAt()

Description

Retrieve call participant by index position

Syntax

PhoneCallLogID getParticipantAt(int index)

Parameters

Index of the participant to retrieve, from 0 to numberOfParticipants()-1

Returns

Participant at index position if valid

Example

// from the addParticipantAt() example  for ( int el = 0; el < call.numberOfParticipants(); el++ )  {    if (call.getParticipantAt(el).getName() == null)      // problem!!!  }

Top

ConferencePhoneCallLog.numberOfParticipants()

Description

Retrieves the number of conference call participants

Syntax

int numberOfParticipants()

Parameters

None

Returns

Number of participants

Example

// from the addParticipantAt() examplefor ( int el = 0; el < call.numberOfParticipants(); el++ ){  if (call.getParticipantAt(el).getName() == null)    // problem!!!}

Top

ConferencePhoneCallLog.removeParticipantAt()

Description

Removes call participant by index position providing there are more than two participants in the call.

Syntax

void removeParticipantAt(int index)

Parameters

Index of the participant to retrieve, from 0 to numberOfParticipants()-1

Returns

Nothing

Example

private void removeCaller() {  PhoneCallLogID id1 = new PhoneCallLogID("5551000");  PhoneCallLogID id2 = new PhoneCallLogID("5551001");  PhoneCallLogID id3 = new PhoneCallLogID("5551002");  ConferencePhoneCallLog call = new ConferencePhoneCallLog(      new Date(System.currentTimeMillis()),      60,      CallLog.STATUS_NORMAL,      id1,      id2,      "Notes on call");  call.addParticipant(id3);  call.removeParticipantAt(1);}

Top

ConferencePhoneCallLog.setParticipantAt()

Description

Set call participant at index position

Syntax

void setParticipant(int index, PhoneCallLogID participant)

Parameters

Index of the participant to change

New call participant

Returns

Nothing

Example

private void setAt() {  PhoneCallLogID id1 = new PhoneCallLogID("5551000");  PhoneCallLogID id2 = new PhoneCallLogID("5551001");  PhoneCallLogID id3 = new PhoneCallLogID("5551002");  ConferencePhoneCallLog call = new ConferencePhoneCallLog(      new Date(System.currentTimeMillis()),      60,      CallLog.STATUS_NORMAL,      id1,      id2,      "Notes on call");  call.setParticipantAt(1, id3);}

Top

The PhoneCallLogID Class
net.rim.blackberry.api.phone.phonelogs. PhoneCallLogID

This represents the caller identification information associated with a telephone call log. This is the information that shows up as the caller in the messages list, and when a log is opened for viewing.

Constructor

PhoneCallLogID(String number)

PhoneCallLogID.getAddressBookFormattedNumber()

Description

Retrieves the formatted phone number from the address book for the caller ID

Syntax

String getAddressBookFormattedNumber()

Parameters

None

Returns

The formatted telephone number from the Address Book if possible, else an empty String

Example

private void mySnippet() {  PhoneCallLogID theID = new PhoneCallLogID("5551000");  theID.setName("Adam Bede");  String name   = theID.getName();  String number = theID.getNumber();  String telNo  = theID.getAddressBookFormattedNumber();}

Top

PhoneCallLogID.getName()

Description

Retrieves the name in the Address Book associated with the caller ID, or null if Address Book entry not found.

Syntax

String getName()

Parameters

None

Returns

The caller ID name, or null

Example

private void mySnippet() {  PhoneCallLogID theID = new PhoneCallLogID("5551000");  theID.setName("Adam Bede");  String name   = theID.getName();  String number = theID.getNumber();  String telNo  = theID.getAddressBookFormattedNumber();}

Top

PhoneCallLogID.getNumber()

Description

Retrieves the original telephone number given to this object when it was created. The telephone number returned may be formatted differently than the associated Address Book entry.

Syntax

String getNumber()

Parameters

None

Returns

Original telephone number provided to this object's constructor

Example

private void mySnippet() {  PhoneCallLogID theID = new PhoneCallLogID("5551000");  theID.setName(&quotAdam Bede");  String name   = theID.getName();  String number = theID.getNumber();  String telNo  = theID.getAddressBookFormattedNumber();}

Top

PhoneCallLogID.setName()

Description

Sets, or changes, the name for the caller ID within the Address Book

Syntax

void setName(String name)

Parameters

New name for the caller ID

Returns

Nothing

Example

private void mySnippet() {  PhoneCallLogID theID = new PhoneCallLogID("5551000");  theID.setName("Adam Bede");  String name   = theID.getName();  String number = theID.getNumber();  String telNo  = theID.getAddressBookFormattedNumber();}

Top

Invoke
net.rim.blackberry.api.invoke

The Invoke class provides developers with the ability to invoke standard BlackBerry applications including the Address Book, Calendar, Memo Pad, Messages, Tasks and Telephone. Arguments can be set prior to invocation by using the *Arguments methods.

To follow are details related to setting up PhoneArguments

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

Constructors

PhoneArguments()
  • Creates a new PhoneArgument instance where the Phone application opens in the default view (recent call list).
PhoneArguments(String actionArg, String dialStringArg)
  • Creates a new PhoneArgument instance with a dialing string.
  • Pass ARG_CALL as the first argument to open the Phone application and dial the provided dial string. Otherwise pass null.
  • In additional to traditional "phone number characters" that you use to compose a phone number (e.g. +1-519-888-7465), you can also specify more precise dialing behaviour:
Character(s) Description
Comma (,) Pause for 2 seconds
Exclamation (!) Prompt the user for input as follows.
  • Dial the rest of the dialing string to the next comma or exclamation mark
  • Advance to the next comma or exclamation mark in the dialing string
  • Cancel the call
‘#’ and ‘*’ Generate "pound" and "star" DTMF codes
‘0’ - ‘9’ Generate numeric DTMF codes

Example

private void makeCall() {  PhoneArguments args = new PhoneArguments(PhoneArguments.ARG_CALL,
"5551000,9876");  Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, args);}

Top

In closing ...

The following is a quote from Watson as he describes the moment Bell discovered the mechanism for transmitting speech using an electric current on June 2, 1875:

"That undulatory had passed through the connecting wire to the distant receiver which, fortunately, was a mechanism that could transform the current back into an extremely faint echo of the sound of the vibrating spring that had generated it, but what was still more fortunate, the right man had that mechanism at his ear during that fleeting moment, and instantly recognized the transcendent importance of that faint sound thus electrically transmitted. The shout I heard and his excited rush into my room were the result of that recognition. The speaking telephone was born at that moment...All the experimenting that followed that discovery, up to the time the telephone was put into practical use, was largely a matter of working out the details."

A year or so later, Bell tried to sell his patent to The Telegraph Company (later Western Union) for $100,000 and was turned down. According to an internal memo, they felt that the idea of setting up a telephone network was idiotic, they couldn't understand why anyone would want to use a telephone, believed that the technology could never be improved enough to work over distance, felt that Bell was too much of a novice to be taken seriously, and stated that his invention was nothing more than a toy.

Western Union's memo did make sense at the time. They had working telegraph technology and decent market share, they knew that Bell's patent was being disputed by Elisha Gray and saw legitimate limitations in the technology.

Bell was proven the winner six years later when his company assumed a controlling interest in Western Union and also Western Electric, which was a company formed by Elisha Gray after he lost his patent fight with Bell.

It took 76 years of technical evolution before the first working mobile telephone was introduced. Even then, technology was far too primitive to bring mobile communications into the mainstream.

Cell phone network topology was developed in 1947, but could not be tested because the technology needed to implement the network did not yet exist, and the frequencies needed were not available.

Cellular trials did not begin until 1978 and FCC licenses were not issued until 1982. The first commercial cellular system was opened by Illinois Bell in 1983. Even then, it took several years before cell phone technology and networks improved enough to start to gain popularity.

Research In Motion entered into the cell phone marketplace at the right time. It took a few years to prepare for their entry, then took a couple more years to refine their technology to cover multiple carriers, networks and continents. With the release of BlackBerry JDE v4.0, they have closed the circle by providing software engineers with the ability to capitalize on their lead in cell phone technology. I hope this article helps you to fully understand and utilize the technology.

Please email your comments, suggestions and editorial submissions to mail

Related Links