Phone

Phone Object


Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.phone.Phone.activeCalls Y Y Y      Y
blackberry.phone.Phone.addPhoneListener Y Y Y      Y
blackberry.phone.Phone.inActiveCall Y Y Y      Y
CB_CALL_INITIATED Y Y Y      Y
CB_CALL_WAITING Y Y Y      Y
CB_CALL_INCOMING Y Y Y      Y
CB_CALL_ANSWERED Y Y Y      Y
CB_CALL_CONNECTED Y Y Y      Y
CB_CALL_CONFERENCECALL_ESTABLISHED Y Y Y      Y
CB_CONFERENCECALL_DISCONNECTED Y Y Y      Y
CB_CALL_DISCONNECTED Y Y Y      Y
CB_CALL_DIRECTCONNECT_CONNECTED Y Y Y      Y
CB_CALL_DIRECTCONNECT_DISCONNECTED Y Y Y      Y
CB_CALL_ENDED_BYUSER Y Y Y      Y
CB_CALL_FAILED Y Y Y      Y
CB_CALL_RESUMED Y Y Y      Y
CB_CALL_HELD Y Y Y      Y
CB_CALL_ADDED Y Y Y      Y
CB_CALL_REMOVED Y Y Y      Y
CALL_ERROR_SUBSCRIBER_BUSY Y Y Y      Y
CALL_ERROR_CONGESTION Y Y Y      Y
CALL_ERROR_RADIO_PATH_UNAVAILABLE Y Y Y      Y
CALL_ERROR_NUMBER_UNOBTAINABLE Y Y Y      Y
CALL_ERROR_AUTHORIZATION_FAILURE Y Y Y      Y
CALL_ERROR_EMERGENCY_CALLS_ONLY Y Y Y      Y
CALL_ERROR_HOLD_ERROR Y Y Y      Y
CALL_ERROR_OUTGOING_CALLS_BARRED Y Y Y      Y
CALL_ERROR_GENERAL Y Y Y      Y
CALL_ERROR_MAINTENANCE_REQUIRED Y Y Y      Y
CALL_ERROR_SERVICE_NOT_AVAILABLE Y Y Y      Y
CALL_ERROR_DUE_TO_FADING Y Y Y      Y
CALL_ERROR_LOST_DUE_TO_FADING Y Y Y      Y
CALL_ERROR_TRY_AGAIN Y Y Y      Y
CALL_ERROR_FDN_MISMATCH Y Y Y      Y
CALL_ERROR_CONNECTION_DENIED_BY_NETWORK Y Y Y      Y
CALL_ERROR_NUMBER_NOT_IN_SERVICE Y Y Y      Y
CALL_ERROR_PLEASE_TRY_LATER Y Y Y      Y
CALL_ERROR_SERVICE_CONFLICT Y Y Y      Y
CALL_ERROR_SYSTEM_BUSY_TRY_LATER Y Y Y      Y
CALL_ERROR_USER_BUSY_IN_PRIVATE Y Y Y      Y
CALL_ERROR_USER_BUSY_IN_DATA Y Y Y      Y
CALL_ERROR_USER_NOT_AUTHORIZED Y Y Y      Y
CALL_ERROR_USER_NOT_AVAILABLE Y Y Y      Y
CALL_ERROR_USER_UNKNOWN Y Y Y      Y
CALL_ERROR_USER_NOT_REACHABLE Y Y Y      Y
CALL_ERROR_INCOMING_CALL_BARRED Y Y Y      Y
CALL_ERROR_CALL_REPLACED_BY_STK Y Y Y      Y
CALL_ERROR_STK_CALL_NOT_ALLOWED Y Y Y      Y

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.phone.Phone" /> Y Y Y      Y

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.


Constants

Number CB_CALL_INITIATED
Number CB_CALL_WAITING
Number CB_CALL_INCOMING
Number CB_CALL_ANSWERED
Number CB_CALL_CONNECTED
Number CB_CALL_CONFERENCECALL_ESTABLISHED
Number CB_CONFERENCECALL_DISCONNECTED
Number CB_CALL_DISCONNECTED
Number CB_CALL_DIRECTCONNECT_CONNECTED
Number CB_CALL_DIRECTCONNECT_DISCONNECTED
Number CB_CALL_ENDED_BYUSER
Number CB_CALL_FAILED
Number CB_CALL_RESUMED
Number CB_CALL_HELD
Number CB_CALL_ADDED
Number CB_CALL_REMOVED
Number CALL_ERROR_SUBSCRIBER_BUSY
Number CALL_ERROR_CONGESTION
Number CALL_ERROR_RADIO_PATH_UNAVAILABLE
Number CALL_ERROR_NUMBER_UNOBTAINABLE
Number CALL_ERROR_AUTHORIZATION_FAILURE
Number CALL_ERROR_EMERGENCY_CALLS_ONLY
Number CALL_ERROR_HOLD_ERROR
Number CALL_ERROR_OUTGOING_CALLS_BARRED
Number CALL_ERROR_GENERAL
Number CALL_ERROR_MAINTENANCE_REQUIRED
Number CALL_ERROR_SERVICE_NOT_AVAILABLE
Number CALL_ERROR_DUE_TO_FADING
Number CALL_ERROR_LOST_DUE_TO_FADING
Number CALL_ERROR_TRY_AGAIN
Number CALL_ERROR_FDN_MISMATCH
Number CALL_ERROR_CONNECTION_DENIED_BY_NETWORK
Number CALL_ERROR_NUMBER_NOT_IN_SERVICE
Number CALL_ERROR_PLEASE_TRY_LATER
Number CALL_ERROR_SERVICE_CONFLICT
Number CALL_ERROR_SYSTEM_BUSY_TRY_LATER
Number CALL_ERROR_USER_BUSY_IN_PRIVATE
Number CALL_ERROR_USER_BUSY_IN_DATA
Number CALL_ERROR_USER_NOT_AUTHORIZED
Number CALL_ERROR_USER_NOT_AVAILABLE
Number CALL_ERROR_USER_UNKNOWN
Number CALL_ERROR_USER_NOT_REACHABLE
Number CALL_ERROR_INCOMING_CALL_BARRED
Number CALL_ERROR_CALL_REPLACED_BY_STK
Number CALL_ERROR_STK_CALL_NOT_ALLOWED

Functions

static blackberry.phone.Phone.Call[] blackberry.phone.Phone.activeCalls ()


Request all of the current active calls

Active calls are tracked when the application is running. When launched, only the current active call might be retrieved.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Return:

Returns an array of current active calls



Code Example:
<script type="text/javascript">
  // Retrieve an array of active calls and display the details of the call at index specified
  var res = blackberry.phone.Phone.activeCalls();
  if (res == null || res.length == 0) {
    alert("There are no active calls");
  }
  else {
    alert("There are " + res.length + " active calls");
    var index = 0;
    displayCallDetails(res[index]);
  }

  function displayCallDetails(call) {
    alert(("Is OnHold: " + call.isOnHold() + "\n") +
    ("Is Outgoing: " + call.outgoing + "\n") +
    ("Recipient name: " + call.recipientName + "\n") +
    ("Recipient number: " + call.recipientNumber + "\n"));
  }
</script>

static Boolean blackberry.phone.Phone.addPhoneListener (onPhoneEvent: function(callId : Number, [reason: Number]), [eventType : Number])


Registers PhoneListener of different type events

To subscribe to PhoneListener, a callback and an eventType (one of enumerated PhoneListener event types) should be specified.

When subscribing a different callback with the same eventType, the new callback will overwrite the previous one. To unsubscribe from a phone call event, pass null as a callback parameter, along with proper eventType.

To unsubscribe from ALL events, pass null. All invoked callback functions will receive a 'callid' of type 'int' as a parameter, which is the ID of the Call. A callback registered with eventType 'CB_CALL_FAILED', in addition to the 'callid' parameter, will get code as a second parameter describing the reason for the failure. It would be equal to one of CALL_ERROR_* constants.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
onPhoneEvent This callback function is triggered when a phone event is triggered.

callId: ID for the resumed call.
reason: CALL_ERROR_* code describing the reason for the failure when callback for CB_CALL_FAILED is triggered
eventType One of constants defining phone call event type.

Return:

Returns true if the listener was successfully assigned



Code Example:
<script type="text/javascript">
  // Adding three listeners differ by their type.
  addListenerByType(callEndedByUserCB, blackberry.phone.Phone.CB_CALL_ENDED_BYUSER);
  addListenerByType(callDisconnectedCB, blackberry.phone.Phone.CB_CALL_DISCONNECTED);
  addListenerByType(callConnectedCB, blackberry.phone.Phone.CB_CALL_CONNECTED);

  // Removing one of the previously added listeners
  addListenerByType(null, blackberry.phone.Phone.CB_CALL_CONNECTED);

  function addListenerByType(callback, type) {
    var res = blackberry.phone.Phone.addPhoneListener(callback, type);
    if (callback != null) {
      alert("Registered for phone listener type " + type + " : " + res);
    }
    else {
      alert("Unregistered from phone listener type " + type + " : " + res);
    }
  }

  function callEndedByUserCB(id) {
    alert("Call ended by user!");
  }

  function callDisconnectedCB(id) {
    alert("The id of diconnected call is: " + id);
  }

  function callConnectedCB(id) {
    alert("Call is connected!");
  }
</script>

static Boolean blackberry.phone.Phone.inActiveCall ()


Determines whether or not the phone is currently in an active call


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Return:

Returns true if the phone is currently in an active call



Code Example:
<script type="text/javascript">
  // Check if in active call
  var res = blackberry.phone.Phone.inActiveCall();
  alert("Currently in active call? " + res);
</script>

Constants

static Number CB_CALL_INITIATED = 0


Invoked when a call has been initiated by the device (outbound).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_WAITING = 1


Invoked when a call is waiting.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_INCOMING = 2


Invoked when a new call is arriving.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_ANSWERED = 3


Invoked when the user answers a call (user driven).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_CONNECTED = 4


Invoked when the network indicates a connected event (network driven).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_CONFERENCECALL_ESTABLISHED = 5


Invoked when a conference call has been established.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CONFERENCECALL_DISCONNECTED = 6


Invoked when a conference call is terminated (all members disconnected).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_DISCONNECTED = 7


Invoked when a call is disconnected.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_DIRECTCONNECT_CONNECTED = 8


Invoked when a direct-connect call is connected.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_DIRECTCONNECT_DISCONNECTED = 9


Invoked when a direct-connect call is disconnected.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_ENDED_BYUSER = 10


Invoked when the user ends the call.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_FAILED = 11


Invoked when a call fails.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_RESUMED = 12


Invoked when a call goes from 'held' to 'resumed' state.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_HELD = 13


Invoked when a call goes into the 'held' state.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_ADDED = 14


Invoked when a call gets added to a conference call


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CB_CALL_REMOVED = 15


Invoked when a call gets removed from a conference call.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_SUBSCRIBER_BUSY = 1


Subscriber busy.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_CONGESTION = 2


Congestion.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_RADIO_PATH_UNAVAILABLE = 3


Radio path unavailable.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_NUMBER_UNOBTAINABLE = 4


Number unobtainable.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_AUTHORIZATION_FAILURE = 5


Authorization failure.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_EMERGENCY_CALLS_ONLY = 6


Emergency calls only.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_HOLD_ERROR = 7


Hold error.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_OUTGOING_CALLS_BARRED = 8


Outgoing call barred.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_GENERAL = 9


General call error.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_MAINTENANCE_REQUIRED = 10


Maintenance required.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_SERVICE_NOT_AVAILABLE = 11


Service not available.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_DUE_TO_FADING = 12


Call failed because of signal fading.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_LOST_DUE_TO_FADING = 13


Call lost because of signal fading.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_TRY_AGAIN = 14


Call failed, please try again.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_FDN_MISMATCH = 15


Fixed dialing number mismatch.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_CONNECTION_DENIED_BY_NETWORK = 16


Connection denied by network.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_NUMBER_NOT_IN_SERVICE = 17


Number not in service (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_PLEASE_TRY_LATER = 18


Please try call later (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_SERVICE_CONFLICT = 19


Service conflict TI (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_SYSTEM_BUSY_TRY_LATER = 20


System busy, try later (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_USER_BUSY_IN_PRIVATE = 21


User busy in private (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_USER_BUSY_IN_DATA = 22


User busy in data (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_USER_NOT_AUTHORIZED = 23


User not authorized (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_USER_NOT_AVAILABLE = 24


User not available (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_USER_UNKNOWN = 25


User unknown (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_USER_NOT_REACHABLE = 26


User not reachable (IDEN specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_INCOMING_CALL_BARRED = 27


Incoming call barred.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_CALL_REPLACED_BY_STK = 28


Call replaced by STK (GSM SIM specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number CALL_ERROR_STK_CALL_NOT_ALLOWED = 29


Call blocked by STK error (GSM SIM specific).


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:09 GMT-0500 (EST)