BlackBerry extension APIs

JavaScript Reference

Search This Document

Download PDF

Object	Description	Availability
`blackberry`	Provides network information for a BlackBerry device.	3.8 or later
`blackberry.launch`	Provides access to other BlackBerry applications on the device.	5.0 or later
`blackberry.location`	Provides access to the GPS location information for the BlackBerry device.	4.1 or later

Object: blackberry

Availability

BlackBerry Device Software version 4.0 or later

The blackberry object is a property of the Window object. It provides information about the network on which the BlackBerry device is running, and the global position of the BlackBerry device.

blackberry properties

Property name	Type	Description	Status	Availability
`location`	`blackberry.location`	Returns a pointer to the `blackberry.location` object. This property is available for BlackBerry Device Software Version 4.1 or later.	read only	4.1 or later
`network`	String	Returns the wireless network on which the BlackBerry device is communicating. The value may be one of: `3GPP` `CDMA` `iDEN` `Wi-Fi` Multiple networks may be supported on a single BlackBerry device. If multiple networks are supported, they are returned as a comma-separated list. For example: `3GPP,Wi-Fi`	read only	4.0 or later

Property name

Type

Description

Status

Availability

location

blackberry.location

Returns a pointer to the blackberry.location object.

This property is available for BlackBerry Device Software Version 4.1 or later.

read only

4.1 or later

network

String

Returns the wireless network on which the BlackBerry device is communicating. The value may be one of:

3GPP
CDMA
iDEN
Wi-Fi

Multiple networks may be supported on a single BlackBerry device. If multiple networks are supported, they are returned as a comma-separated list. For example:

3GPP,Wi-Fi

read only

4.0 or later

Object: blackberry.launch

Availability

BlackBerry Device Software 5.0 or later

The blackberry.launch object provides methods that lets you access core and add-on BlackBerry applications through JavaScript. Depending on the application, you can either launch the application or open the application and create a new item, such as a calendar entry or a task, and prepopulate any of the entry fields. Although the methods of the blackberry.launch object can open and create new items for an application, changes are not made to the application without confirmation from the user. For example, if you use the blackberry.launch object to make a phone call to a specific phone number, the user is prompted to confirm whether the user wants to proceed with the call before the number is dialed. Similarly, if you create a new item for any application, the user must save the item before it is added to that application.

Parameters for the blackberry.launch methods are provided in the form of a single JSON object. For example, to open BlackBerry Maps and display a set of coordinates, you could use the blackberry.launch.newMap() method as follows:

blackberry.launch.newMap({"latitude":4328915, "longitude":-8032480});

When a JSON object is identified as the parameter of a method, it is required. However, the members contained within the JSON object are all optional. For example, you can specify an empty JSON object as the parameter to a method, as long as the JSON object (identified by the braces) is present. For example:

blackberry.launch.newMap({});

blackberry.launch methods

Method name	Description	Availability
`launchCamera()`	Opens the Camera application.	5.0 or later
`launchVideoRecorder()`	Opens the Video Camera application.	5.0 or later
`launchVoicemail()`	Opens the Phone application to call the voice mail account that is associated with the BlackBerry device.	5.0 or later
`newAppointment()`	Creates a new appointment in the Calendar application.	5.0 or later
`newContact()`	Adds a new contact to the Contacts list.	5.0 or later
`newMap()`	Opens the BlackBerry Maps application and displays the specified location.	5.0 or later
`newMemo()`	Creates a new memo in the Memo application.	5.0 or later
`newPhoneCall()`	Opens the phone application to call a specific phone number.	5.0 or later
`newSMS()`	Creates a new SMS text message.	5.0 or later
`newTask()`	Creates a new task in the Tasks application.	5.0 or later

Method: blackberry.launch.launchCamera()

Availability

BlackBerry Device Software 5.0 or later

The launchCamera() method permits you to open the camera application on the BlackBerry device.

Syntax

blackberry.launch.launchCamera()

Parameters

None.

Return values

None.

Code sample: Opening the camera application on the BlackBerry device

<html>
    <body>
        <div id="camera" onClick="blackberry.launch.launchCamera()">Click here to start 
                the camera application on your BlackBerry device!</div>
    </body>
</html>

Method: blackberry.launch.launchVideoRecorder()

Availability

BlackBerry Device Software 5.0 or later

The launchVideoRecorder() method opens the video recorder on the BlackBerry device.

Syntax

blackberry.launch.launchVideoRecorder()

Parameters

None.

Return values

None.

Code sample: Opening the video recorder application

<html>
    <body>
        <div id="video" onClick="blackberry.launch.launchVideoRecorder()">Click here to 
                launch the video recorder on your BlackBerry device!</div>
    </body>
</html>

Method: blackberry.launch.launchVoicemail()

Availability

BlackBerry Device Software 5.0 or later

The launchVoicemail() method permits you to call the voice mail account that is associated with a BlackBerry device. Before the call is placed, the phone application prompts the user to confirm whether they want to proceed with the call.

Syntax

blackberry.launch.launchVoicemail()

Parameters

None.

Return values

None.

Code sample: Calling the BlackBerry device user's voice mail using JavaScript

<html>
    <body>
        <div id="voicemail" onClick="blackberry.launch.launchVoicemail()">Click here to check your messages.</div>
    </body>
</html>

Method: blackberry.launch.newAppointment()

Availability

BlackBerry Device Software 5.0 or later

The newAppointment() method creates a new appointment in the calendar application. The user must save the appointment before it is saved to the calendar.

Syntax

blackberry.launch.newAppointment({ summary, location, allDay, start, end, freeBusy, note })

JSON object members

Member	Type	Description
`summary`	String	Briefly summarizes the reason for the appointment. This value is used to identify this appointment in the calendar.
`location`	String	Specifies the location of the appointment.
`allDay`	Boolean	When true, indicates whether the appointment should be scheduled for the whole day. An all-day event is considered an entire work day, from 9:00 AM to 5:00 PM.
`start`	Date	Specifies the start time of the appointment.
`end`	Date	Specifies the end time of the appointment.
`freeBusy`	integer	Specifies how the time is marked in the user's calendar. You can specify one of the following values: 0: free 1: busy 2: tentative 3: out of office
`note`	String	Specifies text that is included as a part of the appointment.

Return values

None.

Exceptions

None.

Code sample: Creating a new appointment for the calendar application

// Define the start and end times as JavaScript Date objects
var startTime = new Date(2010,10,10,2);
var endTime = new Date(2010,0,1,3,29);

// Create the JSON object that defines all the appointment 
// information as name-value pairs 
var appointmentInfo = {
    "summary":"Meet new VP"
    "location":"Conference room 2"
    "allDay":false
    "start":startTime
    "end":endTime
    "freeBusy":1
    "note":"Refreshments will be served."
};

// Create a new appointment with the new JSON object as a parameter
blackberry.launch.newAppointment(appointmentInfo);

Method: blackberry.launch.newContact()

Availability

BlackBerry Device Software 5.0 or later

The newContact() method creates a contact in the BlackBerry device user's contact list. The user must save the new contact before it is added to the contact list.

Syntax

blackberry.launch.newContact({ title, firstName, lastName, 
        company, jobTitle, email, workPhone, workPhone2, homePhone, 
        homePhone2, mobilePhone, pagerPhone, faxPhone, otherPhone, 
        pin, workAddress, homeAddress, birthday, anniversary, 
        webpage, user1, user2, user3, user4, note })

JSON object members

Member	Type	Description
`title`	String	Specifies the contact's title, such as Mr, Mrs, or Dr.
`firstName`, `lastName`	String	Specify the contact's first name and last name.
`company`	integer	Specifies the organization that the contact belongs to.
`jobTitle`	String	Specifies a job title for the contact.
`email`	array	Specifies an array of email addresses for the contact. The array contains a comma-separated list of strings, each representing an email address. The contents of the array are enclosed in brackets. For example: `["email1@company1.com", "email2@company2.com"]`
`workPhone`, `workPhone2`, `homePhone`, `homePhone2`, `mobilePhone`, `pagerPhone`, `faxPhone`, `otherPhone`	String	Specify assorted phone numbers for the contact.
`pin`	String	Specifies a BlackBerry device PIN for the contact.
`workAddress`, `homeAddress`	`Address`	Specify various addresses for the contact, represented by an `Address` JSON object.
`birthday`, `anniversary`	Date	Specify important dates for the contact, represented by a JavaScript Date object.
`webpage`	String	Specifies a web page for the contact.
`user1`, `user2`, `user3`, `user4`, `note`	String	Specify additional information for the contact.

Return values

None.

Exceptions

None.

Code sample: Creating a new contact

var workAddress = {
    "address1":"295 Phillip Street",
    "city":"Waterloo",
    "country":"Canada",
    "stateProvince":"ON",
    "zipPostal":"N2L3WE"
};
var bday = new Date(1978,3,22);

var contactInfo={
    "title":"Ms"
    "firstName":"Karen"
    "lastName":"Moser"
    "email":[ "too_cool@internet.com", "KM_2@work.com" ]
    "pin":"2100000A"
    "workAddress":workAddress
    "birthDay":bday
};
blackberry.launch.newContact(contactInfo);

Method: blackberry.launch.newMap()

Availability

BlackBerry Device Software5.0 or later

The newMap() method opens BlackBerry Maps and displays a specified location on the map. You can specify a location using one of three following ways:

specify the latitude and longitude
specify an address
specify a location document

Syntax

blackberry.launch.newMap({ latitude, longitude })

blackberry.launch.newMap({ address })

blackberry.launch.newMap({ locationDocument })

JSON object members

Member	Type	Description
`latitude`	double	Specifies the latitude in decimal degrees to five decimal places. A positive value indicates a northern latitude; a negative value indicates a southern latitude. For example, to indicate a latitude of 43°N, specify a value of 43. To indicate a latitude of 42.5°S, specify a value of -42.5
`longitude`	double	Specifies the longitude in decimal degrees to five decimal places. A positive value indicates an eastern longitiude; a negative value indicates a western longitude. For example, to indicate a longitude of 80°W, specify a value of -80.
`address`	`Address`	Specifies address information, represented by an `Address` JSON object.
`locationDocument`	String	Specifies an XML location document. This XML structure is specific to BlackBerry Maps.

Return values

None.

Exceptions

None.

Code sample: Displaying a set of geographic coordinates in BlackBerry Maps

blackberry.launch.newMap({
        "latitude":43.46518, 
    				"longitude":-80.52237
});

var workAddress = {
    "address1":"295 Phillip Street",
    "city":"Waterloo",
    "country":"Canada",
    "stateProvince":"ON",
    "zipPostal":"N2L3WE"
};

blackberry.launch.newMap({"address":workAddress});

blackberry.launch.newMap({
    "locationDocument":"<lbs id=\"Waterloo\">
         <location x=\"-8052237\" y=\"4346518\" label=\"Waterloo, ON\" description=\"Waterloo\" zoom=\"10\" \/>
    <\/lbs>" 
});

Method: blackberry.launch.newMemo()

Availability

BlackBerry Device Software 5.0 or later

The newMemo() opens the memo application and creates a new memo item.

Syntax

blackberry.launch.newMemo({ title, note })

JSON object members

Member	Type	Description
`title`	String	Specifies the title for the memo. This value is used to identify this memo in the list of memo items in the memo application.
`note`	String	Specifies the memo text.

Return values

None.

Code sample: Creating a new memo

blackberry.launch.newMemo({ "title":"Note to self", "note":"The rain in spain falls mainly on the plain" });

Method: blackberry.launch.newSMS()

Availability

BlackBerry Device Software 5.0 or later

The newSMS() method creates a new SMS text message that a user can send to a specified phone number.

This method does not send the SMS text message. The user must send the SMS text message manually.

Syntax

blackberry.launch.newSMS({ number, text })

JSON object members

Member	Type	Description
`number`	String	The number to send the SMS text message to. The number is specified as a string and must be enclosed by quotation marks.
`text`	String	The text in the SMS text message to send to the specified number.

Return values

None.

Exceptions

None.

Code sample: Sending an SMS message

blackberry.launch.newSMS({ "number":"5198887465", "text":"This is a very important message!" });

Method: blackberry.launch.newPhoneCall()

Availability

BlackBerry Device Software 5.0 or later

The newPhoneCall() method opens the phone application to call a specified phone number.

Syntax

blackberry.launch.newPhoneCall({ dialString, smartDialing })

JSON object members

Member	Type	Description
`dialString`	String	Specifies the phone number to call. The phone number is specified as a string and must be enclosed by quotation marks.
`smartDialing`	Boolean	When `true`, indicates that the phone application should apply the Smart Dialing options that the BlackBerry device user specified in the Phone options. Smart dialing permits the user to configure a default country code and area code for phone numbers. The phone application prepends these values automatically when it dials a phone number.

Return values

None.

Exceptions

None.

Code sample: Making a phone call

<html>
    <body>
        <div id="phone" onClick="blackberry.launch.newPhoneCall({ 
                              "dialString":"15198887465", 
                              "smartDialing":false })">
            <p>Click here to call now!</p>
        </div>
    </body>
</html>

Method: blackberry.launch.newTask()

Availability

BlackBerry Device Software 5.0 or later

The newTask() method creates a new task in the tasks application.

Syntax

blackberry.launch.newTask({ summary, status, priority, due, note })

JSON object members

Member	Type	Description
`summary`	String	Briefly summarizes the purpose of the task. This value is used to identify this task in the tasks application.
`status`	integer	Specifies the current status of the task. This parameter can have one of the following values: 0: Not started 1: In progress 2: Completed 3: Waiting 4: Deferred
`priority`	integer	Specifies the priority of the task. This parameter can have one of the following values: 0: High 1: Normal 2: Low
`due`	Date	Specifies a JavaScript Date object that represents the due date of the task.
`note`	String	Specifies a detailed description of the task.

Return values

None.

Exceptions

None.

Code sample: Creating a new task

// set the task completion date for one week from today 
var currentDate = new Date();
var DateInMilliseconds = currentDate.getTime();
var completeDate = DateInMilliseconds + 604 800 000;

// Create a JSON object that specifies the task properties
var taskProperties = {
    "summary":"Create new business proposal",
    "status":0,
    "priority":0,
    "due":completeDate,
    "note":"Complete this proposal on time!!"
};

// create a new task with the new JSON object as a parameter
blackberry.launch.newTask(taskProperties);

JSON Object: Address

Availability

BlackBerry Device Software 5.0 or later

The Address object is a JSON object that contains address information used by the methods of the blackberry.launch object.

Syntax

{ address1, address2, city, stateProvince, country, zipPostal }

JSON object members

Member	Type	Description
`address1`	String	Specifies the street address.
`address2`	String	Specifies additional address information.
`city`	String	Specifies the city that the address is located in.
`stateProvince`	String	Specifies the state or province that the address is located in.
`country`	String	Specifies the country that the address is located in.
`zipPostal`	String	Specifies the zip code or postal code of the address.

Object: blackberry.location

Availability

BlackBerry Device Software version 4.1 or later

The blackberry.location object is a property of the blackberry object. It provides access to the GPS location of the BlackBerry device. The GPS location refers to the geographical co-ordinates, latitude and longitude, of the BlackBerry device.

blackberry.location properties

Property name	Type	Description	Status	Availability
`GPSSupported`	boolean	When true, this property indicates that GPS positioning is supported by the BlackBerry device.	read only	4.1 or later
`latitude`	double	Returns the current latitude, in degrees, of the BlackBerry device. Positive values indicate northern latitude, negative values indicate southern latitude. To ensure that the most accurate co-ordinate is returned, you should register a listener using `blackberry.location.onLocationUpdate()` and acquire the location information within the callback.	read only	4.1 or later
`longitude`	double	Returns the current longitude, in degrees, of the BlackBerry device. Positive values indicate eastern longitude, negative values indicate western longitude. To ensure that the most accurate co-ordinate is returned, you should register a listener using `blackberry.location.onLocationUpdate()` and read acquire the location information within the callback.	read only	4.1 or later
`timestamp`	unsigned long	Returns time (in milliseconds since epoch) at which the `blackberry.location` object was updated. This property is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.	read only	4.6 or later

blackberry.location methods

Method name	Description	Availability
`onLocationUpdate()`	Registers a callback method that is called when the location is updated using `blackberry.location.refreshLocation()`.	4.1 or later
`refreshLocation()`	Requests an update of the location of the BlackBerry device.	4.1 or later
`removeLocationUpdate()`	Removes a previously registered callback method.	4.6 or later
`setAidMode()`	Specifies which method the BlackBerry device will use to obtain the GPS location.	4.1 or later

Method: blackberry.location.onLocationUpdate()

Availability

BlackBerry Device Software version 4.1 or later

The onLocationUpdate() method registers a listener that evaluates a string or calls a function whenever the BlackBerry device receives updated location information.

On BlackBerry devices running versions of BlackBerry Device Software earlier than version 4.6, this method must be passed as a string that is evaluated each time the location is refreshed. On BlackBerry devices running BlackBerry Device Software version 4.6 or later, you can pass a string, or use the method to register a callback function.

Once onlocationUpdate() has been invoked, the callback occurs whenever there is an update to the location information. This can be as frequent as once every several seconds. If you have passed the method a function, you can cancel the callback using blackberry.location.removeLocationUpdate(). If you have passed a string, the callback cannot be removed.

Syntax

blackberry.location.onLocationUpdate( callbackFunction | callbackString )

Parameters

Parameter	Type	Description
`callbackFunction`	Function	A JavaScript function. For BlackBerry devices running versions of the BlackBerry Device Software that are earlier than version 4.6, you must specify the callback as a string.
`callbackString`	String	A string to be evaluated when the location information is updated.

Parameter

Type

Description

callbackFunction

Function

A JavaScript function.

For BlackBerry devices running versions of the BlackBerry Device Software that are earlier than version 4.6, you must specify the callback as a string.

callbackString

String

A string to be evaluated when the location information is updated.

Return values

None.

Exceptions

None.

Method: blackberry.location.refreshLocation()

Availability

BlackBerry Device Software version 4.1 or later

The refreshLocation() method requests an update of the location of the BlackBerry device.

This method is asynchronous, so the script continues regardless of whether updated location information has been received. To ensure that location information is updated before reading it, you should first register a listener using blackberry.location.onLocationUpdate() that reads blackberry.location.latitude and blackberry.location.longitude, and then call refreshLocation() afterwards.

Syntax

blackberry.location.refreshLocation()

Parameters

None.

Return values

Returns true if the GPS location of the BlackBerry device is successfully updated; otherwise, returns false.

Exceptions

None.

Method: blackberry.location.removeLocationUpdate()

Availability

BlackBerry Device Software version 4.6 or later

The removeLocationUpdate() method removes a previously registered callback method.

This method is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.

Syntax

blackberry.location.removeLocationUpdate( callbackFunction )

Parameters

Parameter	Type	Description
`callbackFunction`	Function	A JavaScript function previously registered by `blackberry.location.onLocationUpdate()`.

Return values

None.

Exceptions

None.

Method: blackberry.location.setAidMode()

Availability

BlackBerry Device Software version 4.1 or later

The setAidMode() method specifies which method the BlackBerry device will use to obtain the GPS location.

The device can obtain location information in one of three ways.

Aid Mode	Value	Description
Cellsite	0	This method uses the GPS location of the active cellsite tower to provide first order GPS information. It provides the least accurate location information; however, it is the fastest location mode. This location method requires network connectivity and carrier support.
Assisted	1	This method uses the network to provide ephemeris satellite data to the device chip. It provides the GPS location faster than the autonomous mode and more accurately than the cellsite mode. This location method requires network connectivity and carrier support.
Autonomous	2	This method uses the GPS chip on the BlackBerry device without assistance from the network. The autonomous mode provides the first GPS location in the slowest amount of time.

Aid Mode

Value

Description

Cellsite

This method uses the GPS location of the active cellsite tower to provide first order GPS information. It provides the least accurate location information; however, it is the fastest location mode.

This location method requires network connectivity and carrier support.

Assisted

This method uses the network to provide ephemeris satellite data to the device chip. It provides the GPS location faster than the autonomous mode and more accurately than the cellsite mode.

This location method requires network connectivity and carrier support.

Autonomous

This method uses the GPS chip on the BlackBerry device without assistance from the network. The autonomous mode provides the first GPS location in the slowest amount of time.

Syntax

blackberry.location.setAidMode( aidMode )

Parameters

Parameter	Type	Description
`aidMode`	int	The method used to obtain the GPS location. The value for this parameter may be one of: `0` — Cellsite `1` — Assisted `2` — Autonomous

Parameter

Type

Description

aidMode

int

The method used to obtain the GPS location. The value for this parameter may be one of:

0 — Cellsite
1 — Assisted
2 — Autonomous

Return values

None.

Next topic: Canvas 2D rendering context API

Previous topic: Supported JavaScript APIs

Was this information helpful? Send us your comments.

Global Navigation

JavaScript Reference

Local Navigation