Phone

- BlackBerry OS 5.0+
- Ripple Emulator

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

API Summary

activeCalls

---

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

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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.

Returns

Returns an array of current active calls

Code Example(s)

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

addPhoneListener

---

static Boolean addPhoneListener(onPhoneEvent : function, [eventType: Number])

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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.

Returns

Returns true if the listener was successfully assigned

Parameter	Type	Description
onPhoneEvent	function(callId : Number, [reason: Number])	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	Number Optional	One of constants defining phone call event type.

Code Example(s)

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

inActiveCall

---

static Boolean inActiveCall()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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

Returns

Returns true if the phone is currently in an active call

Code Example(s)

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

Constants:

---

Property	Type	Description	Supported Platform(s)
CB_CALL_INITIATED default: 0	Number	Invoked when a call has been initiated by the device (outbound).	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_WAITING default: 1	Number	Invoked when a call is waiting.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_INCOMING default: 2	Number	Invoked when a new call is arriving.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_ANSWERED default: 3	Number	Invoked when the user answers a call (user driven).	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_CONNECTED default: 4	Number	Invoked when the network indicates a connected event (network driven).	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_CONFERENCECALL_ESTABLISHED default: 5	Number	Invoked when a conference call has been established.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CONFERENCECALL_DISCONNECTED default: 6	Number	Invoked when a conference call is terminated (all members disconnected).	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_DISCONNECTED default: 7	Number	Invoked when a call is disconnected.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_DIRECTCONNECT_CONNECTED default: 8	Number	Invoked when a direct-connect call is connected.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_DIRECTCONNECT_DISCONNECTED default: 9	Number	Invoked when a direct-connect call is disconnected.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_ENDED_BYUSER default: 10	Number	Invoked when the user ends the call.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_FAILED default: 11	Number	Invoked when a call fails.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_RESUMED default: 12	Number	Invoked when a call goes from 'held' to 'resumed' state.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_HELD default: 13	Number	Invoked when a call goes into the 'held' state.	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_ADDED default: 14	Number	Invoked when a call gets added to a conference call	- BlackBerry OS 5.0+  - Ripple Emulator
CB_CALL_REMOVED default: 15	Number	Invoked when a call gets removed from a conference call.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_SUBSCRIBER_BUSY default: 1	Number	Subscriber busy.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_CONGESTION default: 2	Number	Congestion.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_RADIO_PATH_UNAVAILABLE default: 3	Number	Radio path unavailable.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_NUMBER_UNOBTAINABLE default: 4	Number	Number unobtainable.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_AUTHORIZATION_FAILURE default: 5	Number	Authorization failure.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_EMERGENCY_CALLS_ONLY default: 6	Number	Emergency calls only.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_HOLD_ERROR default: 7	Number	Hold error.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_OUTGOING_CALLS_BARRED default: 8	Number	Outgoing call barred.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_GENERAL default: 9	Number	General call error.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_MAINTENANCE_REQUIRED default: 10	Number	Maintenance required.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_SERVICE_NOT_AVAILABLE default: 11	Number	Service not available.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_DUE_TO_FADING default: 12	Number	Call failed because of signal fading.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_LOST_DUE_TO_FADING default: 13	Number	Call lost because of signal fading.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_TRY_AGAIN default: 14	Number	Call failed, please try again.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_FDN_MISMATCH default: 15	Number	Fixed dialing number mismatch.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_CONNECTION_DENIED_BY_NETWORK default: 16	Number	Connection denied by network.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_NUMBER_NOT_IN_SERVICE default: 17	Number	Number not in service (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_PLEASE_TRY_LATER default: 18	Number	Please try call later (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_SERVICE_CONFLICT default: 19	Number	Service conflict TI (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_SYSTEM_BUSY_TRY_LATER default: 20	Number	System busy, try later (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_USER_BUSY_IN_PRIVATE default: 21	Number	User busy in private (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_USER_BUSY_IN_DATA default: 22	Number	User busy in data (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_USER_NOT_AUTHORIZED default: 23	Number	User not authorized (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_USER_NOT_AVAILABLE default: 24	Number	User not available (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_USER_UNKNOWN default: 25	Number	User unknown (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_USER_NOT_REACHABLE default: 26	Number	User not reachable (IDEN specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_INCOMING_CALL_BARRED default: 27	Number	Incoming call barred.	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_CALL_REPLACED_BY_STK default: 28	Number	Call replaced by STK (GSM SIM specific).	- BlackBerry OS 5.0+  - Ripple Emulator
CALL_ERROR_STK_CALL_NOT_ALLOWED default: 29	Number	Call blocked by STK error (GSM SIM specific).	- BlackBerry OS 5.0+  - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:19 GMT-0500 (EST)