Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - DEVICE APPLICATIONS INTEGRATION - DEVELOPMENT... Quick setup guide

BlackBerry Java Development
Environment
Version 4.6.0
BlackBerry Device Applications Integration Guide

BlackBerry Java Development Environment Version 4.6.0 BlackBerry Device Applications Integration Guide
Last modified: 29 August 2008
Part number: 20595761
At the time of publication, this documentation is based on the BlackBerry Java Development Environment Version 4.6.0.
Send us your comments on product documentation: https://www.blackberry.com/DocsFeedback.
©2008 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType® and related trademarks, names,
and logos are the property of Research In Motion Limited and are registered and/or used as trademarks in the U.S., Canada, and countries
around the world.
Bluetooth is a trademark of Bluetooth SIG. Java and JavaScript are trademarks of Sun Microsystems, Inc. Microsoft, ActiveX, Internet Explorer,
and Windows are trademarks of Microsoft Corporation. iCal is a trademark of Apple Computer, Inc. vCard is a trademark of the Internet Mail
Consortium. Plazmic is a trademark of Plazmic Inc. Wi-Fi and 802.11, 802.11a, 802.11b, 802.11g are trademarks of the Wi-Fi Alliance. All other
brands, product names, company names, trademarks and service marks are the properties of their respective owners.
The BlackBerry device and/or associated software are protected by copyright, international treaties and various patents, including one or
more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460; D416,256. Other patents
are registered or pending in various countries around the world. Visit www.rim.com/patents.shtml for a list of RIM (as hereinafter defined)
patents.
This document is provided “as is” and Research In Motion Limited and its affiliated companies (“RIM”) assume no responsibility for any
typographical, technical or other inaccuracies in this document. In order to protect RIM proprietary and confidential information and/or trade
secrets, this document may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change
information that is contained in this document; however, RIM makes no commitment to provide any such changes, updates, enhancements or
other additions to this document to you in a timely manner or at all. RIM MAKES NO REPRESENTATIONS, WARRANTIES, CONDITIONS OR
COVENANTS, EITHER EXPRESS OR IMPLIED (INCLUDING WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED WARRANTIES OR
CONDITIONS OF FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, MERCHANTABILITY, DURABILITY, TITLE, OR RELATED TO
THE PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE REFERENCED HEREIN OR PERFORMANCE OF ANY SERVICES
REFERENCED HEREIN). IN CONNECTION WITH YOUR USE OF THIS DOCUMENTATION, NEITHER RIM NOR ITS RESPECTIVE DIRECTORS,
OFFICERS, EMPLOYEES OR CONSULTANTS SHALL BE LIABLE TO YOU FOR ANY DAMAGES WHATSOEVER BE THEY DIRECT, ECONOMIC,
COMMERCIAL, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR INDIRECT DAMAGES, EVEN IF RIM HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES, INCLUDING WITHOUT LIMITATION, LOSS OF BUSINESS REVENUE OR EARNINGS, LOST DATA,
DAMAGES CAUSED BY DELAYS, LOST PROFITS, OR A FAILURE TO REALIZE EXPECTED SAVINGS.
This document might contain references to third party sources of information, hardware or software, products or services and/or third party
web sites (collectively the “Third-Party Information”). RIM does not control, and is not responsible for, any Third-Party Information, including,
without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any
other aspect of Third-Party Information. The inclusion of Third-Party Information in this document does not imply endorsement by RIM of the
Third Party Information or the third party in any way. Installation and use of Third Party Information with RIM's products and services may
require one or more patent, trademark or copyright licenses in order to avoid infringement of the intellectual property rights of others. Any
dealings with Third Party Information, including, without limitation, compliance with applicable licenses and terms and conditions, are solely
between you and the third party. You are solely responsible for determining whether such third party licenses are required and are
responsible for acquiring any such licenses relating to Third Party Information. To the extent that such intellectual property licenses may be
required, RIM expressly recommends that you do not install or use Third Party Information until all such applicable licenses have been
acquired by you or on your behalf. Your use of Third Party Information shall be governed by and subject to you agreeing to the terms of the
Third Party Information licenses. Any Third Party Information that is provided with RIM's products and services is provided "as is". RIM makes
no representation, warranty or guarantee whatsoever in relation to the Third Party Information and RIM assumes no liability whatsoever in
relation to the Third Party Information even if RIM has been advised of the possibility of such damages or can anticipate such damages.

Published in Canada
Research In Motion Limited
295 Phillip Street
Waterloo, ON N2L 3W8
Canada
Research In Motion UK Limited
Centrum House, 36 Station Road
Egham, Surrey TW20 9LF
United Kingdom

Contents
1Adding custom menu items to applications .................................................................................................... 8
Adding menu items to BlackBerry Java Applications.................................................................................. 8
Create a menu item................................................................................................................................... 8
Register a menu item................................................................................................................................ 9
2Integrating with BlackBerry applications ....................................................................................................... 11
Invoke BlackBerry applications ......................................................................................................................11
3Using the message list .......................................................................................................................................13
Create new messages......................................................................................................................................13
Work with a message.......................................................................................................................................15
Open a message .......................................................................................................................................16
Retrieve the body of a message without an attachment.................................................................... 17
Retrieve the body of a message with an attachment..........................................................................17
Code sample: Retrieve the body of a message ....................................................................................18
Notify an application that an email message is about to be sent....................................................20
Notify an application that an MMS message is about to be sent ....................................................20
Notify an application that an SMS message is about to be sent .....................................................20
Send a message ........................................................................................................................................21
Reply to a message.................................................................................................................................. 22
Forward a message.................................................................................................................................. 23
Work with folders ............................................................................................................................................ 23
Working with attachments ............................................................................................................................ 25
Create an attachment handler .............................................................................................................. 25
Retrieve attachments.............................................................................................................................. 25
Send a message with an attachment ...................................................................................................26
4Using PIM applications ..................................................................................................................................... 27
Using the calendar ......................................................................................................................................... 27
Start the calendar from your BlackBerry Java Application ............................................................... 27
Use the calendar...................................................................................................................................... 28
Notify an application when a list of events changes..........................................................................31
Notify an application when the default list of events on a BlackBerry device changes ...............31

Retrieve multiple lists of events ............................................................................................................ 32
Using the address book ................................................................................................................................. 32
Open the address book from your BlackBerry Java Application ...................................................... 32
Use contacts............................................................................................................................................. 32
Notify an application when a list of contacts changes......................................................................38
Using tasks.......................................................................................................................................................39
Start the task application from your BlackBerry Java Application ..................................................39
Use tasks...................................................................................................................................................40
Notify an application when a list of tasks changes ...........................................................................43
Code samples...................................................................................................................................................43
Code sample: Creating new recurring appointments........................................................................ 43
Code sample: Displaying a screen that lets BlackBerry device users add new contacts.............45
Code sample: Using tasks ......................................................................................................................48
5Using the phone application .............................................................................................................................51
Start the phone application from your BlackBerry Java Application.......................................................51
Use phone call functionality ..........................................................................................................................51
Add DTMF tones to the send queue ..................................................................................................... 52
BlackBerry DTMF tones........................................................................................................52
Listen for phone events.................................................................................................................................. 53
Access and use call logs................................................................................................................................. 53
Code sample ....................................................................................................................................................54
Code sample: Calculating the time spent on the phone by a participant ......................................54
6Using the BlackBerry Browser ......................................................................................................................... 57
Display content in the BlackBerry Browser ................................................................................................ 57
Display content in a BlackBerry Browser field ........................................................................................... 57
Code sample ....................................................................................................................................................60
Code sample: Using the BlackBerry Browser......................................................................................60

1
Adding custom menu items to applications
Adding menu items to BlackBerry Java Applications
The Application Menu Item API, in the net.rim.blackberry.api.menuitem package, lets you add menu items
to BlackBerry® Java® Applications. The ApplicationMenuItemRepository class lets you add or remove menu
items from BlackBerry Java Applications.
Create a menu item
Adding menu items to BlackBerry Java Applications
Task Steps
Define a menu item. > Extend the abstract ApplicationMenuItem class.
public class SampleMenuItem extends ApplicationMenuItem { ... }
Specify the position of the menu
item in the menu.
A higher number means that the menu item appears lower in the menu.
>InvokeApplicationMenuItem()
SampleMenuItem() {
super(20);
}
Specify the menu item text. > Implement toString().
public String toString() {
return "Open the Contacts Demo application";
}
Specify the behaviour of the menu
item.
> Implement run().
public Object run(Object context) {
Contact c = (Contact)context; // An error occurs if this does not work.
if ( c != null ) {
new ContactsDemo().enterEventDispatcher();
} else {
throw new IllegalStateException( "Context is null, expected a Contact
instance");
}
Dialog.alert("Viewing a message in the messaging view");
return null;
}

9
1: Adding menu items to BlackBerry Java Applications
Register a menu item
Task Steps
Retrieve the BlackBerry® MDS Java
Application menu item repository.
>InvokeApplicationMenuItemRepository.getInstance().
ApplicationMenuItemRepository repository =
ApplicationMenuItemRepository.getInstance();
Create your BlackBerry Java
Application menu item.
> Invoke the constructor.
ContactsDemoMenuItem contactsDemoMenuItem = new ContactsDemoMenuItem();
Add the menu item to the repository. >InvokeApplicationMenuItemRepository.addMenuItem().
repository.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD
_VIEW, contactsDemoMenuItem);
Add the menu item to BlackBerry®
Maps.
>InvokeApplicationMenuItemRepository.addMenuItem()using the MENUITEM_MAPS
field.
repository.addMenuItem(ApplicationMenuItemRepository.MENUITEM_MAPS,
contactsDemoMenuItem);

10
BlackBerry Device Applications Integration Guide