JDE 5.0 IntegrationGuide-Beta

8/6/2019 JDE 5.0 IntegrationGuide-Beta

1/86

BlackBerry Java Application

IntegrationVersion: 5.0

Development Guide


2/86

Published: 2010-04-06SWD-761936-0406015514-001


3/86

Contents1 Integrating with BlackBerry Device Software applications.................................................................................................. 5

Invoke a BlackBerry Device Software application....................................................................................................................... 5

2 Message list.................................................................................................................................................................................. 6

Create a new blank SMS text message........................................................................................................................................ 6

Create a new populated text message......................................................................................................................................... 6

Create a new blank MMS message............................................................................................................................................... 7Create a new blank email message.............................................................................................................................................. 7

Create a new populated email message...................................................................................................................................... 7

Create a new blank PIN message................................................................................................................................................. 8

Create a new populated PIN message......................................................................................................................................... 8

Receive a message notification..................................................................................................................................................... 8

Add a listener to the message store............................................................................................................................................. 9

Add a listener to the message store for batch updates.............................................................................................................. 10Add a listener to a folder................................................................................................................................................................ 10

Retrieve the total count of unread email messages in all folders in the store........................................................................ 10

Open a message............................................................................................................................................................................. 11

Retrieving the body of an email message.................................................................................................................................... 12

Retrieve the plain text and HTML content in the body of an email message using a recursive method.................... 12

Retrieve the plain text content of an email message......................................................................................................... 15

Retrieve the HTML content of an email message............................................................................................................... 16

Notify a BlackBerry device application that an email message is about to be sent............................................................... 18

Notify a BlackBerry device application that an MMS message is about to be sent................................................................ 19

Notify a BlackBerry device application that an SMS message is about to be sent................................................................. 20

Send a message.............................................................................................................................................................................. 20

Reply to a message......................................................................................................................................................................... 22

Forward a message......................................................................................................................................................................... 23

Work with message folders............................................................................................................................................................ 24

3 Attachments................................................................................................................................................................................. 26

Create an attachment handler...................................................................................................................................................... 26

Retrieve the contents of an attachment...................................................................................................................................... 27

Retrieve information about an attachment................................................................................................................................. 27

Send a message with an attachment........................................................................................................................................... 27


4/86

Download attachments automatically.......................................................................................................................................... 28

4 Calendar........................................................................................................................................................................................ 30

Open the calendar.......................................................................................................................................................................... 30

View or change a calendar entry.................................................................................................................................................. 30

Open a new populated calendar entry......................................................................................................................................... 31

Update calendar entry information.............................................................................................................................................. 31

Retrieve calendar entry information............................................................................................................................................. 34

Export a calendar entry.................................................................................................................................................................. 35Import a calendar entry.................................................................................................................................................................. 35

Retrieve multiple lists of calendar entries.................................................................................................................................... 36

Notify a BlackBerry device application when a list of calendar entries changes.................................................................... 36

Notify a BlackBerry device application when the default list of calendar entries changes................................................... 37

5 Contact list............................................................................................................................................... .................................... 38

Multiple contact lists support........................................................................................................................................................ 38Open the contacts application...................................................................................................................................................... 38

Open the contacts application by using contact data............................................................................................................... 39

Open the contacts application with a specific contact list........................................................................................................ 40

Create a contact and assign it to a contact list........................................................................................................................... 41

Retrieve contact information......................................................................................................................................................... 42

Retrieve a contact list UID............................................................................................................................................................. 43

Export a contact.............................................................................................................................................................................. 44

Import a contact.............................................................................................................................................................................. 45

Delete a contact.............................................................................................................................................................................. 45

Notify an application when a contact list changes..................................................................................................................... 46

Linking third-party contacts with contacts in the contacts application................................................................................... 48

Link a contact.......................................................................................................................................................................... 48

Remove a link.......................................................................................................................................................................... 49

Creating menu items for linked contacts............................................................................................................................ 50

Create menu items for linked contacts................................................................................................................................ 51

Create a custom field for linked contacts............................................................................................................................ 52

6 Task list................................................................................................................................................... ...................................... 54

View or change a task.................................................................................................................................................................... 54

Create a new blank task................................................................................................................................................................. 54


5/86

Create a new populated task......................................................................................................................................................... 54

Open a task list............................................................................................................................................................................... 55Create a task.................................................................................................................................................................................... 55

Add task information...................................................................................................................................................................... 56

Change task information................................................................................................................................................................ 57

Save a task....................................................................................................................................................................................... 57

Retrieve task information............................................................................................................................................................... 57

Export a task.................................................................................................................................................................................... 58

Import a task.................................................................................................................................................................................... 59

Delete a task.................................................................................................................................................................................... 59

Close the task list............................................................................................................................................................................ 60

Notify a BlackBerry device application when a list of tasks changes....................................................................................... 60

7 Phone............................................................................................................................................................................................. 61

Making a call from a BlackBerry device application................................................................................................................... 61

Make a call from a BlackBerry device application (single-line environment)......................................................................... 61

Make a call from a BlackBerry device application (multi-line environment)........................................................................... 61

Add DTMF tones to the send queue............................................................................................................................................. 62

BlackBerry DTMF tones.................................................................................................................................................................. 62

Listen for and handle phone events............................................................................................................................................. 63

Listen for and handle multi-line events....................................................................................................................................... 63

Retrieve call information by using call logs................................................................................................................................. 64

Retrieve a call participant.............................................................................................................................................................. 65

Retrieve call information................................................................................................................................................................ 65

Retrieve the phone number of a BlackBerry device.................................................................................................................... 65

Retrieve a call by call ID................................................................................................................................................................. 66

Displaying content on a phone screen......................................................................................................................................... 66

Display content on a phone screen.............................................................................................................................................. 67

8 BlackBerry Browser..................................................................................................................................................................... 68

Retrieve a BlackBerry Browser session......................................................................................................................................... 68

Retrieve a non-default BlackBerry Browser session................................................................................................................... 68

Request a web page........................................................................................................................................................................ 68

Enhanced support for web content in BlackBerry device applications.................................................................................... 68

Display HTML content in a browser field............................................................................................................................ 69

Display HTML content from a web page in a browser field.............................................................................................. 70


6/86

Display HTML content from a resource in your application.............................................................................................. 71

Configure a browser field...................................................................................................................................................... 72Send form data to a web address in a browser field.......................................................................................................... 73

9 Menu items................................................................................................................................................................................... 75

Adding menu items to BlackBerry Device Software applications............................................................................................. 75

Create and register a menu item.................................................................................................................................................. 75

10 Glossary......................................................................................................................................................................................... 77

11 Provide feedback........................................................................................................................................................ ................. 79

12 Document revision history......................................................................................................................................................... 80

13 Legal notice.................................................................................................................................................................................. 82


7/86

Integrating with BlackBerry Device Software applications 1This section describes how to invoke a BlackBerry Device Software application, such as the contacts application, the phone

application, and the media application.

For more information about integrating your application with BlackBerry Device Software applications, see the Application

Integration category overview in the API reference for the BlackBerry Java Development Environment.

Invoke a BlackBerry Device Software applicationYou can create BlackBerry device applications that invoke BlackBerry Device Software applications such as the messagesapplication, the phone application, and the media application. When your application invokes a BlackBerry Device Softwareapplication, the application can make the BlackBerry Device Software application perform an action or display information.

1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.CalendarArguments;import net.rim.blackberry.api.invoke.Invoke;

import net.rim.blackberry.api.invoke.MapsArguments;import net.rim.blackberry.api.invoke.MessageArguments;import net.rim.blackberry.api.invoke.PhoneArguments;

2. Invoke the Invoke.invokeApplication() method and use the appropriate parameters. For example:

To start the messages application and create a new blank SMS message, invoke theInvoke.invokeApplication

() and use the following parameters:Invoke.APP_TYPE_MESSAGES and aMessageArguments object that uses

the ARG_NEW_SMS field.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,new MessageArguments( MessageArguments.ARG_NEW_SMS) );

To start the calendar, invokeInvoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments).

To start the phone application, invokeInvoke.invokeApplication(APP_TYPE_PHONE,PhoneArguments) .

To start BlackBerry Maps and display the default map view, invokeInvoke.invokeApplication() and provide

as parameters Invoke.APP_TYPE_MAPS and a new MapsArguments object.

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments() );

For more information about using the net.rim.blackberry.api.invoke.Invoke class, see the API reference for theBlackBerry Java Development Environment.

Development Guide Integrating with BlackBerry Device Software applications

5


8/86

Message list 2This section describes how to use the messaging capabilities of the BlackBerry device.

For more information, see the Messaging category overview in the API reference for the BlackBerry Java Development

Environment.

Create a new blank SMS text message1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;import net.rim.blackberry.api.invoke.MessageArguments;

2. Invoke Invoke.invokeApplication(). Use the following parameters: the APP_TYPE_MESSAGES constant

parameter and a new MessageArguments object that uses the ARG_NEW_SMS field.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,

new MessageArguments( MessageArguments.ARG_NEW_SMS));

Create a new populated text messageUse the API items in the javax.wireless.messaging package (JSR 120).


import javax.microedition.io.Connector;

import javax.wireless.messaging.MessageConnection;import javax.wireless.messaging.TextMessage;import net.rim.blackberry.api.invoke.Invoke;import net.rim.blackberry.api.invoke.MessageArguments;

2. Create and populate a newTextMessage object.

MessageConnection mc = (MessageConnection)Connector.open("sms://");TextMessage m = (TextMessage)mc.newMessage( MessageConnection.TEXT_MESSAGE );m.setAddress("sms://5558888");

m.setPayloadText("An SMS message for you");3. Invoke Invoke.invokeApplication() with the following parameters:

APP_TYPE_MESSAGES: a constant parameter

MessageArguments: a new MessageArguments object that uses the new TextMessage object.

Invoke.invokeApplication( Invoke.APP_TYPE_MESSAGES, new MessageArguments(m) );

Development Guide Message list

6


9/86

Create a new blank MMS message1. Import the required classes and interfaces.


2. Invoke Invoke.invokeApplication() using the APP_TYPE_MESSAGES constant parameter and a new

MessageArguments object that uses the ARG_NEW_MMS field.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,new MessageArguments( MessageArguments.ARG_NEW_MMS));

Create a new blank email message1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;

import net.rim.blackberry.api.invoke.MessageArguments;


MessageArguments object that uses the ARG_NEW field.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,new MessageArguments( MessageArguments.ARG_NEW));

Create a new populated email message1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;import net.rim.blackberry.api.invoke.MessageArguments;import net.rim.blackberry.api.mail.Address;import net.rim.blackberry.api.mail.Message;

2. Create and populate a new email Message object.

Message m = new Message();Address a = new Address("[email protected]", "Ming Li");Address[] addresses = {a};m.addRecipients(net.rim.blackberry.api.mail.Message.RecipientType.TO, addresses);m.setContent("A message for you...");m.setSubject("Email for you");

3. Invoke Invoke.invokeApplication()with the following parameters:

APP_TYPE_MESSAGES

Development Guide Create a new blank MMS message

7


10/86

a MessageArguments object that uses the new Message object.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES, new MessageArguments(m));

Create a new blank PIN message1. Import the required classes and interfaces.



MessageArguments object that uses the ARG_NEW_PIN field.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,new MessageArguments( MessageArguments.ARG_NEW_PIN));

Create a new populated PIN message1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;import net.rim.blackberry.api.invoke.MessageArguments;import net.rim.blackberry.api.mail.Address;import net.rim.blackberry.api.mail.Message;import net.rim.blackberry.api.mail.PINAddress;

2. Create and populate a newPINmessage.

Message m = new Message();PINAddress pa = new PINAddress("ABCDEF99", "Mark Chapters");Address[] addresses = {pa};m.addRecipients( net.rim.blackberry.api.mail.Message.RecipientType.TO,

addresses );m.setContent("A message for you...");m.setSubject("PIN message for you");

3. Invoke Invoke.invokeApplication() with the following parameters:

APP_TYPE_MESSAGES

a MessageArguments object that uses the new PINmessage.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES, new MessageArguments(m));

Receive a message notification1. Import the required classes and interfaces.

Development Guide Create a new blank PIN message

8


11/86

import net.rim.blackberry.api.mail.event.FolderListener;

import net.rim.blackberry.api.mail.event.StoreListener;import net.rim.device.api.system.ControlledAccessException;

2. Implement the FolderListener and StoreListener interfaces.

public class MailTest implements FolderListener, StoreListener { ... }

3. Check for a ControlledAccessException if your application accesses an object that you do not have permission to

access.

Add a listener to the message store1. Import the required classes and interfaces.

import net.rim.blackberry.api.mail.NoSuchServiceException;import net.rim.blackberry.api.mail.Session;import net.rim.blackberry.api.mail.Store;

2. Create a try-catch block to manage a NoSuchServiceException.

try{}catch (NoSuchServiceException e){

System.out.println(e.toString());}

3. Within the try-catch block, invoke Session.waitForDefaultSession().getStore() to retrieve the Store

object.

try{

Store store = Session.waitForDefaultSession().getStore();}catch (NoSuchServiceException e){


4. After the try-catch block, invoke store.addStoreListener() to add a StoreListener instance to the Store

object.

store.addStoreListener(this);

Development Guide Add a listener to the message store

9


12/86

Add a listener to the message store for batch updates1. Import the required classes and interfaces.

import net.rim.blackberry.api.mail.event.StoreListener;import net.rim.blackberry.api.mail.Store;

2. Implement the StoreListener interface.

void batchOperation(StoreEvent e)

{// Perform action when messages added or removed in batch operation.

}

Add a listener to a folder1. Import the required classes and interfaces.

import net.rim.blackberry.api.mail.event.FolderListener;import net.rim.blackberry.api.mail.Folder;import net.rim.blackberry.api.mail.Store;

2. Implement FolderListener.messagesAdded() and FolderListener.messagesRemoved().

void messagesAdded(FolderEvent e){

// Perform processing on added messages.}void messagesRemoved(FolderEvent e)

{// Perform processing on removed messages.

}

3. Retrieve the Folder object for which you want to receive new message notifications.

Folder[] folders = store.list(Folder.INBOX);Folder inbox = folders[0];

4. Register the class that implementsFolderListener with the folder.

inbox.addFolderListener(this);

Retrieve the total count of unread email messages in all folders in the store1. Import the required class.

import net.rim.blackberry.api.mail.Store;

Development Guide Add a listener to the message store for batch updates

10


13/86

2. Invoke Store.getUnreadMessageCount().

int numUnread = store.getUnreadMessageCount();

Open a message1. Import the required classes and interfaces.

import java.util.Date;import net.rim.blackberry.api.mail.Address;

import net.rim.blackberry.api.mail.Folder;import net.rim.blackberry.api.mail.Message;import net.rim.blackberry.api.mail.Session;import net.rim.blackberry.api.mail.Store;

2. Invoke Session.waitForDefaultSession.getStore() to retrieve the message store.

Store store = Session.waitForDefaultSession.getStore();

3. Invoke Store.getFolder() to retrieve the folder that contains the message.

Folder folder = Store.getFolder("SampleFolder");

4. Invoke folder.getMessages() to retrieve the message objects and store the message objects in a Message array.

Iterate through the array and retrieve information, such as the sender and subject, to display to the BlackBerry device user.

Message[] msgs = folder.getMessages();

5. When a user selects a message from the list, invoke methods on theMessage object to retrieve the appropriate fields and

body contents to display to the user.

Message msg = msgs[0]; // Retrieve the first messageAddress[] recipients = msg.getRecipients(Message.RecipientType.TO);Date sent = msg.getSentDate();Address from = msg.getFrom();String subject = msg.getSubject();Object o = msg.getContent();

// Verify that the message is not multipartif ( o instanceof String ){

String body = (String)o;}

//...

6. Invoke Message.getBodyText() on a message to retrieve the plain text contents as a String. If the message does

not contain plain text, the method returns null.

Development Guide Open a message

11


14/86

Retrieving the body of an email messageAn email message can contain plain text, HTML, or both. The content and the order of the content in the email message can vary.

A BlackBerry device application can use the MimeBodyPart class to retrieve the HTML content, or use the

TextBodyPart class to retrieve the plain text content. You can use a MultiPart object to retrieve objects from both the

MimeBodyPart class and the TextBodyPart class.

For example, you might retrieve the content of an email message to translate the content into a different language.

Support for text and HTML was introduced in BlackBerry Device Software 4.5 for BlackBerry devices associated with BlackBerry

Enterprise Server 4.1 Service Pack 6 (4.1.6) or the BlackBerry Internet Service 2.5.

Retrieve the plain text and HTML content in the body of an email message using a recursivemethodCreate a recursive method to retrieve all the parts of the body of an email message including plain text and HTML.


import net.rim.blackberry.api.mail.MimeBodyPart;import net.rim.blackberry.api.mail.Multipart;import net.rim.blackberry.api.mail.SupportedAttachmentPart;import net.rim.blackberry.api.mail.TextBodyPart;import net.rim.blackberry.api.mail.UnsupportedAttachmentPart;

2. Create the method signature for the recursive method.void findEmailBody(Object obj) {...}

3. Create local variables that indicate if the BlackBerry Attachment Service supports the message attachment type.

boolean _hasSupportedAttachment;boolean _hasUnsupportedAttachment;

4. Initialize the local variables.

_hasSupportedAttachment = false;_hasUnsupportedAttachment = false;

5. If the method parameter is a Multipart object, the object has multiple BodyPart objects. On each BodyPart object,

invoke the recursive method that searches through the body of an email message.

if(obj instanceof Multipart){

_Multipart mp = (Multipart)obj;

//Extract all of the parts within the Multipart message.

Development Guide Retrieving the body of an email message

12

D l t G id R t i i th b d f il


15/86

for(int count=0; count < mp.getCount(); ++count){

findEmailBody(mp.getBodyPart(count));}

}

6. If the BodyPart object is a TextBodyPart, retrieve the plain text body of the message.

else if (obj instanceof TextBodyPart){

//This message only has a text body.TextBodyPart tbp = (TextBodyPart) obj;

readEmailBody(tbp);}

7. Check if the BodyPart object is a MimeBodyPart.

else if (obj instanceof MimeBodyPart) {...}

8. If the BodyPart object is a MimeBodyPart, perform the following actions:

a. Cast the BodyPart object as a MimeBodyPart.

MimeBodyPart mbp = (MimeBodyPart) obj;

b. If the MimeBodyPart object does not contain attachments, retrieve the body of the message using the

MimeBodyPart object as a parameter.

if (mbp.getContentType().indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1){

readEmailBody(mbp);}

c. If the MimeBodyPart object does contain attachments, invoke a method that retrieves the body of the message.

else if(mbp.getContentType().equals(ContentType.TYPE_MULTIPART_MIXED_STRING) ||

mbp.getContentType().equals(ContentType.TYPE_MULTIPART_ALTERNATIVE_STRING)){

findEmailBody(mbp.getContent());}

9. If the BodyPart is an attachment that the BlackBerry Attachment Service supports, change the appropriate local variable

to true.

else if (obj instanceof SupportedAttachmentPart){

_hasSupportedAttachment = true;}

10. If the BodyPart is an attachment that the BlackBerry Attachment Service does not support, change the appropriate local

variable to true.


13



16/86

else if (obj instanceof UnsupportedAttachmentPart){

_hasUnsupportedAttachment = true;}

Code sample: Retrieving the content of an email message

private void findEmailBody(Object obj){

//Reset the attachment flags._hasSupportedAttachment = false;

_hasUnsupportedAttachment = false;

if(obj instanceof Multipart){

Multipart mp = (Multipart)obj;

for(int count=0; count < mp.getCount(); ++count){findEmailBody(mp.getBodyPart(count));

}

}else if (obj instanceof TextBodyPart){

TextBodyPart tbp = (TextBodyPart) obj;readEmailBody(tbp);

}

else if (obj instanceof MimeBodyPart){

MimeBodyPart mbp = (MimeBodyPart)obj;if (mbp.getContentType().indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1){readEmailBody(mbp);

}}

else if (mbp.getContentType().equals(ContentType.TYPE_MULTIPART_MIXED_STRING) ||mbp.getContentType().equals(ContentType.TYPE_MULTIPART_ALTERNATIVE_STRING)){

//The message has attachments or we are at the top level of the message.//Extract all of the parts within the MimeBodyPart message.findEmailBody(mbp.getContent());

}

else if (obj instanceof SupportedAttachmentPart){

_hasSupportedAttachment = true;}


14



17/86

else if (obj instanceof UnsupportedAttachmentPart){

_hasUnsupportedAttachment = true;}

}

Retrieve the plain text content of an email messageIn the following task, an exception may be thrown when you invoke the Transport.more() method.


import net.rim.blackberry.api.mail.BodyPart;import net.rim.blackberry.api.mail.TextBodyPart;import net.rim.blackberry.api.mail.Transport;import net.rim.device.api.ui.component.Dialog;

2. Create a method that takes a TextBodyPart object as a parameter.

void readEmailBody(TextBodyPart tbp);

3. Cast the value thatTextBodyPart.getContent() returns as a String to get the plain text part of the body of themessage.

_plainTextMessage = (String)tbp.getContent();

4. Invoke TextBodyPart.hasMore() and TextBodyPart.moreRequestSent() to identify if more of the

TextBodyPart object is available on the server.

if (tbp.hasMore() && !tbp.moreRequestSent()){

5. If more data is available for the TextBodyPart object, invoke Transport.more() to retrieve the rest of the

TextBodyPart object.

Transport.more((BodyPart)tbp, true);

Code sample: Retrieving the plain text content of an email message

private void readEmailBody(TextBodyPart tbp){

_plainTextMessage = (String)tbp.getContent();

if (tbp.hasMore() && !tbp.moreRequestSent()){

try{

Transport.more((BodyPart)tbp, true);}catch (Exception ex){


15



18/86

Dialog.alert("Exception: " + ex.toString());}

}}

Retrieve the HTML content of an email messageIn the following task, an exception may be thrown when you invoke the Transport.more() method.


import net.rim.blackberry.api.mail.BodyPart;import net.rim.blackberry.api.mail.MimeBodyPart;import net.rim.blackberry.api.mail.Transport;import net.rim.device.api.ui.component.Dialog;

2. Create a method that takes a MimeBodyPart object as a parameter.

void readEmailBody(MimeBodyPart mbp){

3. Invoke MimeBodyPart.getContent() and MimeBodyPart.getContentType() to retrieve the content of theMimeBodyPart object.

Object obj = mbp.getContent();String mimeType = mbp.getContentType();

4. Create a String variable to hold the String representation of the MimeBodyPart object.

String body = null;

5. If the BlackBerry device can convert the HTML body of a message to a String, the MimeBodyPart object will be aString. Cast the MimeBodyPart object as a String and assign it to the String representation of the body part of

the message.

if (obj instanceof String){

body = (String)obj;}

6. If the BlackBerry device cannot convert the HTML body of a message to aString, the MimeBodyPart object will be a

byte array. Create a new instance ofString using as a parameter the MimeBodyPart object cast as a byte array. Assignthe String to the String representation of the body part of the message.

else if (obj instanceof byte[]){

body = new String((byte[])obj);}

p g y g

16



19/86

7. Check to see if the String representation of the content of the MimeBodyPart object contains

ContentType.TYPE_TEXT_PLAIN_STRING to determine if the MimeBodyPart object is the plain text body partof the message.

if (mimeType.indexOf(ContentType.TYPE_TEXT_PLAIN_STRING) != -1){

8. InvokeMimeBodyPart.hasMore() andMimeBodyPart.moreRequestSent() to determine if all of the text body

part is present in the MimeBodyPart object.

if (mbp.hasMore() && !mbp.moreRequestSent())

{

9. If more data is available for the MimeBodyPart object, invoke Transport.more() to retrieve the rest of the data for

the MimeBodyPart object.

Transport.more((BodyPart)mbp, true);

10. Check to see if the String representation of the content of the MimeBodyPart object contains

ContentType.TYPE_TEXT_HTML_STRING to detemine if the MimeBodyPart object is the HTML body part of the

message.else if (mimeType.indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1){

11. Invoke MimeBodyPart.hasMore() and MimeBodyPart.moreRequestSent() to determine if all of the HTML

body part is present in the MimeBodyPart object.

if (mbp.hasMore() && !mbp.moreRequestSent()){

12. If more data is available for the MimeBodyPart object, invoke Transport.more() to retrieve the rest of theMimeBodyPart object.

Transport.more((BodyPart)mbp, true);

Code sample: Retrieving the HTML content of an email message

private void readEmailBody(MimeBodyPart mbp){

//Extract the content of the message.Object obj = mbp.getContent();String mimeType = mbp.getContentType();String body = null;

if (obj instanceof String){

body = (String)body;}else if (obj instanceof byte[]){

17

Development Guide Notify a BlackBerry device application that an email message is about to be sent


20/86

body = new String((byte[])obj);}

if (mimeType.indexOf(ContentType.TYPE_TEXT_PLAIN_STRING) != -1){

_plainTextMessage = body;

//Determine if all of the text body part is present.if (mbp.hasMore() && !mbp.moreRequestSent()){

try{

Transport.more((BodyPart)mbp, true);}catch (Exception ex){


}}

else if (mimeType.indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1)

{_htmlMessage = body;

//Determine if all of the HTML body part is present.if (mbp.hasMore() && !mbp.moreRequestSent()){

try{

Transport.more((BodyPart)mbp, true);}

catch (Exception ex){


}}

}

Notify a BlackBerry device application that an email message is about to besent1. Import the required classes and interfaces.

18


21/86

Development Guide Notify a BlackBerry device application that an SMS message is about to be sent


22/86

Notify a BlackBerry device application that an SMS message is about to besent1. Import the required classes and interfaces.

import net.rim.blackberry.api.sms.SendListener;import net.rim.blackberry.api.sms.SMS;

2. Create a class that implements the SendListener interface.

public class smsSendListener implements SendListener{...}

3. Create an instance of the class that implements the SendListener interface.

smsSendListener smsSL = new smsSendListener();

4. Add a SendListener.

SMS.addSendListener(smsSL);

Send a message1. Import the required classes and interfaces.

import net.rim.blackberry.api.mail.Address;import net.rim.blackberry.api.mail.AddressException;import net.rim.blackberry.api.mail.Folder;import net.rim.blackberry.api.mail.Message;

import net.rim.blackberry.api.mail.MessagingException;import net.rim.blackberry.api.mail.Session;import net.rim.blackberry.api.mail.Store;import net.rim.blackberry.api.mail.Transport;

2. Declare a Message object.

Message msg;

3. Specify a folder in which to save a copy of the sent message.

Store store = Session.getDefaultInstance().getStore();Folder[] folders = store.list(Folder.SENT);Folder sentfolder = folders[0];msg = new Message(sentfolder);

4. Create an array ofAddress objects.

Address toList[] = new Address[1];

5. In a try block, add each address to the array.

20

Development Guide Send a message


23/86

try{

toList[0]= new Address("[email protected]", "Ming Li");}

6. In a catch block, manage a AddressException, which is thrown if an address is invalid.

catch(AddressException e){


7. Invoke Message.addRecipients() and provide the type of recipient (TO, CC, or BCC) and the array of addresses toadd as parameters to the method.

8. If the message has multiple types of recipients, invoke Message.addRecipients() once for each recipient type.

msg.addRecipients(Message.RecipientType.TO, toList);

9. Invoke Message.setFrom(Address).

Address from = new Address("[email protected]", "Ming Li");msg.setFrom(from);

10. Invoke Message.setSubject(String).

msg.setSubject("Test Message");

11. Invoke Message.setContent(String). (Typically, the BlackBerry device application retrieves content from text

that a BlackBerry device user types in a field.)

try{

msg.setContent("This is a test message.");

}catch(MessagingException e){

System.out.println(e.getMessage());}

12. Invoke Session.getTransport() and store the returned object in a variable of type Transport. The

Transport object represents the messaging transport protocol.

Transport trans = Session.getTransport();

13. Invoke Transport.send(Message) to send the message.

try{

trans.send(msg);}catch(MessagingException e)

21

Development Guide Reply to a message


24/86

{System.out.println(e.getMessage());

}

Reply to a message1. Import the required classes and interfaces.

import net.rim.blackberry.api.mail.Folder;import net.rim.blackberry.api.mail.Message;

import net.rim.blackberry.api.mail.Session;import net.rim.blackberry.api.mail.Store;import net.rim.blackberry.api.mail.Transport;




3. Invoke Session.waitForDefaultSession().getStore() to retrieve the Store object.

Store store = Session.waitForDefaultSession().getStore();

4. Invoke Store.list(INBOX) to retrieve all the folders in the INBOX folder. Store the folders in a Folder array.

Folder[] folders = store.list(INBOX);

5. Specify a specific array element to retrieve the inbox folder.

Folder inbox = folders[0];

6. Invoke Folder.getMessages() to retrieve the messages in the inbox folder. Store the messages in a Message array.

Message[] messages = inbox.getMessages();

7. Invoke Message.reply(Boolean) and specifytrue to reply to all message recipients or false to reply to only the

sender.

if( messages.length > 0 ){

Message msg = messages[0];}Message reply = msg.reply(true);

8. Invoke Transport.send(Message) to send the reply.

try{

trans.send(reply);}catch(MessagingException e)

22

Development Guide Forward a message


25/86

{System.out.println(e.getMessage());

}

Forward a message1. Import the required classes and interfaces.

import net.rim.blackberry.api.mail.Address;import net.rim.blackberry.api.mail.Message;

import net.rim.blackberry.api.mail.MessagingException;import net.rim.blackberry.api.mail.Session;import net.rim.blackberry.api.mail.Transport;

2. InvokeMessage.forward() on an existingMessageobject. The subject line of a forwarded message is set automatically

to FW:original_subject.

Message fwdmsg = msg.forward();

3. Create an array of addresses.

Address toList[] = new Address[1];

4. Add a new Address object to the array.

toList[0]= new Address("[email protected]", "Ming Li");

5. Invoke Message.addRecipients(int, Address[]) to add recipients to the Message.

fwdmsg.addRecipients(Message.RecipientType.TO, toList);

6. Invoke Message,setContent(String) to set the content of the message that appears before the original message.

try{

fwdmsg.setContent("This is a forwarded message.");}catch(MessagingException e){


7. Invoke Session.getTransport() and store the returned object in a variable of type Transport. TheTransport object represents the messaging transport protocol.


8. Invoke Transport.send(Message).

try{

trans.send(fwdmsg);}

23

Development Guide Work with message folders


26/86

catch(MessagingException e){


Work with message folders1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;

import net.rim.blackberry.api.invoke.MessageArguments;import net.rim.blackberry.api.mail.Folder;import net.rim.blackberry.api.mail.FolderNotFoundException;import net.rim.blackberry.api.mail.Message;import net.rim.blackberry.api.mail.Session;import net.rim.blackberry.api.mail.Store;

2. Retrieve the store.

Store store = Session.waitForDefaultSession().getStore();

3. Complete any of the following actions:

Task Steps

Open a folder view a. Retrieve a list of folders.

Store store = null;store =Session.waitForDefaultSession().getStore();

Folder[] folders = store.list();

b. InvokeInvoke.invokeApplication() to view a folder from the list.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,new MessageArguments( folders[0]));

List the folders in a mailbox store Invoke Store.list().

Folder[] folders = store.list();

Retrieve an array of folders by type Invoke Store.list(int) and provide as a parameter the folder type.

Folder[] folders = store.list(INBOX);Folder inbox = folders[0];

Retrieve an array of folders through a

searchInvoke Store.findFolder(String).

Folder[] folders = store.findFolder("Inbox");

24

Development Guide Work with message folders


27/86

Task Steps

Retrieve a folder by its name a. Invoke Store.getFolder(String) and provide as a parameter the

absolute path to the folder.

Folder folder =store.getFolder("Mailbox - Yan Wang/Inbox/

Projects");

b. Create code to manage a FolderNotFoundException exception if

the folder does not exist.

Retrieve a folder by its ID a. Invoke Folder.getID() to retrieve the folder ID.

b. Invoke Store.getFolder() with the ID as a parameter.

Folder[] folders = store.list();long id = folders[0].getId();Folder f2 = store.getFolder(id);

File a message Invoke Folder.appendMessage(Message) on a Folder object.

Message msg = new Message();// populate the messageFolder folder = store.getFolder("Inbox");folder.appendMessage(msg);

25

Development Guide Attachments


28/86

Attachments 3You can use the Mail API in the net.rim.blackberry.api.mail package to manage attachments in incoming email

messages and include attachments in outgoing email messages on a BlackBerry device. An attachment is represented as a

separate BodyPart object on a Multipart message.

Create an attachment handlerYou can use the AttachmentHandler interface to manage an attachment to an email message that appears in the messagelist on the BlackBerry device.

Note: The BlackBerry Attachment Service receives all attachments first. Third-party attachment handlers cannot override thisdefault behavior. For more information about the BlackBerry Attachment Service, see the BlackBerry Enterprise ServerAdministration Guide.


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

import net.rim.device.api.ui.container.*;import net.rim.device.api.ui.component.*;

2. Implement the AttachmentHandler interface to create a custom attachment handler.

public class AttachTest implements AttachmentHandler {...}

3. Implement the supports(String) method, to specify the content type of the attachment supported by your handler.

public boolean supports(String contentType){

return (contentType.toLowerCase().indexOf("contenttype") != -1 ? true : false);}

4. Implement the menuString() method, to specify the text of the menu item that displays when a user selects an

attachment.

public String menuString(){

return "Custom Attachment Viewer";}

5. Implement the run() method to specify what should happen when a user clicks the menu item. In the following code

sample, a new screen uses theRichTextField class to display aString representation of the content of the attachment.

public void run(Message m, SupportedAttachmentPart p){

MainScreen view = new MainScreen();view.setTitle("Attachment Viewer");view.add(new RichTextField(new String((byte[])p.getContent())));

}

26

Development Guide Retrieve the contents of an attachment


29/86

6. Invoke AttachmentHandlerManager.addAttachmentHandler(), to register the attachment handler with the

manager. Note that the attachment name must be prefixed with "x-rimdevice" for the attachment to be sent and stored on

the BlackBerry device.

AttachmentHandlerManager m = AttachmentHandlerManager.getInstance();CustomAttachmentHandler ah = new CustomAttachmentHandler();m.addAttachmentHandler(ah);

Retrieve the contents of an attachment1. Import the net.rim.blackberry.api.mail.SupportedAttachmentPart class.

2. Invoke SupportedAttachmentPart.getContent().

String s = new String((byte[])p.getContent());

Retrieve information about an attachment1. Import the net.rim.blackberry.api.mail.SupportedAttachmentPart class.2. Invoke the methods of the SupportedAttachmentPart class. The SupportedAttachmentPart class represents

an attachment with a corresponding viewer on the BlackBerry device. The UnsupportedAttachmentPart class

represents an attachment that does not have a viewer on the BlackBerry device.

Send a message with an attachment1. Import the required classes and interfaces.

import net.rim.blackberry.api.mail.Message;import net.rim.blackberry.api.mail.MessagingException;import net.rim.blackberry.api.mail.Multipart;import net.rim.blackberry.api.mail.Session;import net.rim.blackberry.api.mail.SupportedAttachmentPart;import net.rim.blackberry.api.mail.Transport;

2. Create a new Multipart object to create a multipart message.

byte[] data = new byte[256];MultiPart multipart = new MultiPart();

3. Create a SupportedAttachmentPart object, designating the Multipart object as its parent, to create each

component of the screen.

SupportedAttachmentPart attach = new SupportedAttachmentPart( multipart,"application/x-example", "filename", data);

27

Development Guide Download attachments automatically


30/86

4. Invoke MultiPart.addBodyPart(SupportedAttachmentPart) to add each supportedAttachmentPart

object to the multipart object.

multipart.addBodyPart(attach);

5. Invoke Message.setContent(Multipart) and provide as a parameter the Multipart object to set the content

of the attachment.

msg.setContent(multipart);




7. Invoke Transport.send(Message).

try{

trans.send(msg);}catch(MessagingException e){


Download attachments automaticallyWhen a message arrives in the messages application on the BlackBerry device with an attachment, you can automaticallydownload the attachment and store it on the BlackBerry device.

Before downloading attachments, the AttachmentDownloadManager class validates the attachment.AttachmentDownloadManager throws exceptions if any of the following conditions occur.

the application attempts to invoke the download while a download is already in progress

the application attempts to download zero length files.

the size of the attachment is larder than permitted by the application IT policy or service books

attachments are encrypted

there is not enough space available on the BlackBerry device or SD card

The AttachmentDownloadManager.download() method performs verification during the download process. Ifverification errors are found, the method throws an exception. For a list of possible verification errors, see the API reference forthe BlackBerry Java Development Environment.

Note: The BlackBerry Attachment Service receives all attachments first. Third-party attachment handlers cannot override thisdefault behavior. For more information about the BlackBerry Attachment Service, see the BlackBerry Enterprise ServerAdministration Guide.


28

Development Guide Download attachments automatically


31/86

import java.io.IOException;import net.rim.blackberry.api.mail.*;

2. Implement the DownloadProgressListener interface. Create an instance of the

AttachmentDownloadManager class.

public class AutoAttachTest implements DownloadProgressListener{

AttachmentDownloadManager _adm = new AttachmentDownloadManager();

3. Use the methods available in AttachmentDownloadManager to determine information about the attachment.

public String fileSize = getFileSize(BodyPart bodyPart);public String fileName = getFileName(BodyPart bodyPart);public String fileType = getFileContentType(BodyPart bodyPart);public String filePath = getDownloadedFileName(BodyPart bodyPart);

4. Invoke AttachmentDownloadManager.download(), to download the attachment.

_adm.download(bodyParts, null, this);

5. Override the DownloadProgressListener callback methods, to provide updates about the status of the download of

the attachment.

private void downloadCancelled(String msg){

BodyPart bodyPart = (BodyPart) element;_screen.displayProgress("Failed to download " + _adm.getFileName(bodyPart));

}private void downloadCompleted(Object element){

BodyPart bodyPart = (BodyPart) element;_screen.displayProgress(_adm.getFileName(bodyPart) + " downloaded.");

}public void updateProgress(Object element, int current, int total){}

29

Development Guide Calendar


32/86

Calendar 4Open the calendar1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.CalendarArguments;import net.rim.blackberry.api.invoke.Invoke;import net.rim.device.api.system.ControlledAccessException;

2. Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments).

3. Check for aControlledAccessException if your application does not have permission to access the application that

it invokes.

View or change a calendar entry1. Import the required classes and interfaces.

import java.util.Enumeration;import javax.microedition.pim.PIM;import javax.microedition.pim.Event;import javax.microedition.pim.EventList;import net.rim.blackberry.api.invoke.CalendarArguments;import net.rim.blackberry.api.invoke.Invoke;import net.rim.device.api.system.ControlledAccessException;

2. Retrieve an Event from the list of events.

Event e = null;EventList el =(EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_WRITE );

Enumeration events = el.items();e = (Event)events.nextElement();

3. Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments) using the

CalendarArguments object created using the ARG_VIEW_DEFAULT field and the retrieved Event.

Invoke.invokeApplication( Invoke.APP_TYPE_CALENDAR, new CalendarArguments( CalendarArguments.ARG_VIEW_DEFAULT, e ) );


it invokes.

30

Development Guide Open a new populated calendar entry


33/86

Open a new populated calendar entry1. Import the required classes and interfaces.

import javax.microedition.pim.PIM;import javax.microedition.pim.Event;import javax.microedition.pim.EventList;import net.rim.blackberry.api.invoke.CalendarArguments;import net.rim.blackberry.api.invoke.Invoke;import net.rim.device.api.system.ControlledAccessException;

2. Create a new Event using an EventList object.

EventList el = (EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST,PIM.READ_WRITE );Event e = el.createEvent();

3. Add information to the Event object.

e.addString( Event.SUMMARY, 0, "Go For A Walk" );e.addString( Event.LOCATION, 0, "The Park" );

long start = System.currentTimeMillis() + 8640000;e.addDate( Event.START, 0, start );e.addDate( Event.END, 0, start + 72000000 );

4. Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments) using the

CalendarArguments object created using the ARG_NEW field and the Event.

Invoke.invokeApplication( Invoke.APP_TYPE_CALENDAR, new CalendarArguments( CalendarArguments.ARG_NEW, e ) );

Update calendar entry information1. Import the required classes and interfaces.

import java.util.Date;import javax.microedition.pim.Event;import javax.microedition.pim.EventList;import javax.microedition.pim.PIM;

import javax.microedition.pim.RepeatRule;2. Invoke openPIMList() to open a list of calendar entries. Provide the following as parameters: the type of list to open

(PIM.EVENT_LIST) and the mode in which to open the list:

READ_WRITE

READ_ONLY

WRITE_ONLY

31

Development Guide Update calendar entry information


34/86

EventList eventList = null;try

{eventList = (EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST,PIM.READ_WRITE);

}catch (PimException e){

// Handle exception.}

3. To update calendar information, perform any of the following tasks:

Task Steps

Create an appointment Invoke createEvent() on an event list.

Event event = eventList.createEvent();

Add appointment information Invoke Event.isSupportedField(int) to verify that an item supports

a field.

if (event.isSupportedField(Event.SUMMARY)){event.addString(Event.SUMMARY, Event.ATTR_NONE,"Meet with customer");

}

if (event.isSupportedField(Event.LOCATION)){event.addString(Event.LOCATION, Event.ATTR_NONE,"Conference Center");

}

Date start = new Date(System.currentTimeMillis() +8640000);

if (event.isSupportedField(Event.START)){event.addDate(Event.START, Event.ATTR_NONE,start);

}

if (event.isSupportedField(Event.END)){event.addDate(Event.END, Event.ATTR_NONE, start +

72000000);}

if (event.isSupportedField(Event.ALARM))

32

Development Guide Update calendar entry information


35/86

Task Steps

{if (event.countValues(Event.ALARM) > 0){event.removeValue(Event.ALARM,0);event.setInt(Event.ALARM, 0, Event.ATTR_NONE,396000);

}}

Create a recurring appointment a. Create aRepeatRule object. TheRepeatRule class defines fields for

the properties and values that you can set, such as COUNT,FREQUENCY, and INTERVAL.

b. Invoke RepeatRule.getFields() to retrieve an array of supported

fields.

c. Invoke RepeatRule.setInt(int, int) or

RepeatRule.setDate(int, int,int, long) on a new

RepeatRule object to define a recurring pattern.

RepeatRule recurring = new RepeatRule();recurring.setInt(RepeatRule.FREQUENCY,RepeatRule.MONTHLY);

recurring.setInt(RepeatRule.DAY_IN_MONTH, 14);

d. Invoke Event.setRepeat(RepeatRule) on an event to assign a

recurrence pattern to an appointment.

EventList eventList =(EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);

Event event = eventList.createEvent();event.setRepeat(recurring);

Change appointment information a. Invoke the appropriate set method, such as setString() to replace

an existing value with a new one.

b. Invoke Event.countValues() to determine if a value is already setfor the field.

c. Use the corresponding set method, such as setString() to change

an existing value.

33

Development Guide Retrieve calendar entry information


36/86

Task Steps

if (event.countValues(Event.LOCATION) > 0){event.setString(Event.LOCATION, 0,Event.ATTR_NONE, "Board Room");

}

Save an appointment a. Before you save the appointment, to identify appointment fields that have

changed since the appointment was last saved, invoke

Event.isModified().

b. Invoke Event.commit().

if(event.isModified()){event.commit();

}

Retrieve calendar entry information1. Import the required classes and interfaces.

javax.microedition.pim.Eventjavax.microedition.pim.EventListjavax.microedition.pim.PIM

2. Invoke EventList.items() to retrieve an enumeration of appointments.

EventList eventList =(EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_ONLY);

Enumeration e = eventList.items();

3. Invoke PIMItem.getFields() to retrieve an array of IDs of fields that have data for a particular task. Invoke

PIMItem.getString() to retrieve the field values.

while (e.hasMoreElements()){

Event event = (Event)e.nextElement();int[] fieldIds = event.getFields();

int id;for(int index = 0; index < fieldIds.length; ++index){

id = fieldIds[index];if(e.getPIMList().getFieldDataType(id) == STRING){

for(int j=0; j < event.countValues(id); ++j){

String value = event.getString(id, j);

34

Development Guide Export a calendar entry


37/86

System.out.println(event.getFieldLable(id) + "=" + value);}

}}}

Export a calendar entry1. Import the required classes and interfaces.

import java.io.ByteArrayOutputStream;

import java.util.Enumeration;import javax.microedition.pim.Event;import javax.microedition.pim.EventList;import javax.microedition.pim.PIM;

2. Invoke PIM.supportedSerialFormats() specifying the list type (PIM.EVENT_LIST), to retrieve a string array

of supported serial formats.

String[] dataFormats = PIM.supportedSerialFormats(PIM.EVENT_LIST);

3. Use an output stream writer to export calendar entries from the BlackBerry device to a supported serial format, such as iCal.4. Invoke toSerialFormat() to write an item in serial format. The encparameter specifies the character encoding to use

when writing to the output stream. Supported character encodings include UTF8, ISO-8859-1, and UTF-16BE. This

parameter cannot be null.

EventList eventList =(EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_ONLY );

ByteArrayOutputStream bytestream = new ByteArrayOutputStream();Enumeration e = eventList.items();

while (e.hasMoreElements()){Event event = (Event)e.nextElement();PIM.getInstance().toSerialFormat(event, bytestream, "UTF8", dataFormats[0]);

}

Import a calendar entry1. Import the required classes and interfaces.

import java.io.ByteArrayInputStream;import java.io.ByteArrayOutputStream;import javax.microedition.pim.Event;import javax.microedition.pim.EventList;import javax.microedition.pim.PIM;

2. Invoke PIM.getInstance().fromSerialFormat() to return an array ofPIMItem objects.

3. Invoke EventList.importEvent() to add a new calendar entry.

35

Development Guide Retrieve multiple lists of calendar entries


38/86

// Convert an existing entry into a iCal and then// import the iCal as a new entry

String[] dataFormats = PIM.supportedSerialFormats();

// Write entry to iCalByteArrayOutputStream os = new ByteArrayOutputStream();PIM.getInstance().toSerialFormat(event, os, "UTF8", dataFormats[0]);

// Import entry from iCalByteArrayInputStream is = new ByteArrayInputStream(os.toByteArray());PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");EventList eventList =

(EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);Event event2 = eventList.importEvent((Event)pi[0]);

Retrieve multiple lists of calendar entriesThe first element in the array of lists is the default list.

1. Import the javax.microedition.pim.PIM class.

2. Invoke PIM.listPIMLists(int pimListType).

String[] allLists = PIM.listPIMLists(PIM.EVENT_LIST);

Notify a BlackBerry device application when a list of calendar entrieschanges1. Import the required classes and interfaces.

import javax.microedition.pim.EventList;import javax.microedition.pim.PIM;import net.rim.blackberry.api.pdap.BlackBerryPIMList;import net.rim.blackberry.api.pdap.PIMListListener;

2. Implement the PIMListListener interface.

public class MyEventListListener implements PIMListListener {...}

3. Invoke BlackBerryPIMList.addListener() to register to receive notifications of changes to a list of calendar

entries.

BlackBerryPIMList eventList = (BlackBerryPIMList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);eventList.addListener(new MyEventListListener());

36

Development Guide Notify a BlackBerry device application when the default list of calendar entries changes


39/86

Notify a BlackBerry device application when the default list of calendarentries changesWhen an update occurs to the list of services on a BlackBerry device, the list of PIM databases on a device may change. Thisaction may result in the creation of a new default list of calendar entries.


import javax.microedition.pim.PIM;

import net.rim.blackberry.api.pdap.BlackBerryPIM;import net.rim.blackberry.api.pdap.ListChangeListener;

2. Implement the ListChangeListener interface.

public class MyListChangeListener implements ListChangeListener {...}

3. Invoke BlackBerryPIM.addListChangeListener() to register to receive notifications of changes to a default

PIM list.

ListChangeListener listener = new MyListChangeListener();((BlackBerryPIM) PIM.getInstance()).addListChangeListener(listener);

4. To have the application always use the defaultPIMList, store a reference to the desired PIMList and design the

ListChangeListener.defaultListChanged() method to update the reference when the default list changes.

37

Development Guide Contact list


40/86

Contact list 5You can use an instance of the ContactList class or BlackBerryContactList class in your application to add and view

contact information in the contacts application on the BlackBerry device. You can create Contact or

BlackBerryContact objects to store information for individual contacts such as the name, phone number, email address,

and street address.

Your application can perform tasks such as adding, deleting, and changing contact list entries.

Multiple contact lists supportSupport for multiple contact lists is available in BlackBerry Java Development Environment 5.0 or later. Each contact list has

a system-assigned contact list name and a UID that you can use to retrieve the list. You can change the contact list name by

using the BlackBerry Desktop Manager to change the name of the service that is associated with the contact list name. You

cannot change the UID.

When deciding how you want to open a contact list, you should consider persistence on the BlackBerry device. If your application

requires the contact list name to persist across OS updates, use the UID to open the contact list. If your application requires thecontact list name to persist only across BlackBerry device restarts, you can use the contact list name. Because a contact list name

can change, you can register a listener for name change events by invoking BlackBerryPIM.addListChangeListener

(ListChangeListener listener).

You can retrieve the names of the contact lists that are installed on a BlackBerry device by invoking PIM.listPIMLists

(int pimListType) and passing in PIM.CONTACT_LIST as pimListType. The String array that is returned provides

the system-assigned names for the contact lists on the device. The contact list name that is at index 0 of the returned

String array is the default contact list. You can retrieve the UID of a contact list on a BlackBerry device by invokingBlackBerryPIMList.getPIMListUID().

You can open a contact list by its name by invoking PIM.openPIMList(int pimListType, int mode, String

name). You can open a contact list by its UID by invoking BlackBerryPIM.openPIMList(int pimListType, int

mode, long uid). You can open a list that combines multiple contact lists on a device by invoking one of the

BlackBerryPIM.openUnifiedPIMList() methods.

Open the contacts applicationYou can open the contacts application on the BlackBerry device by using the Invoke.invokeApplication() method,and passing in the relevant arguments.


38

Development Guide Open the contacts application by using contact data


41/86

import net.rim.blackberry.api.invoke.Invoke;import net.rim.blackberry.api.invoke.AddressBookArguments;

import net.rim.device.api.system.ControlledAccessException;

2. Invoke Invoke.invokeApplication(APP_TYPE_ADDRESSBOOK, AddressBookArguments).

AddressBookArguments abArg = new AddressBookArguments();Invoke.invokeApplication(Invoke.APP_TYPE_ADDRESSBOOK, abArg);


it invokes.

Open the contacts application by using contact dataYou can open the contacts application on a BlackBerry device and display a contact by using theInvoke.invokeApplication() method, and passing in contact data as a parameter of an AddressBookArgumentsobject.


import net.rim.blackberry.api.invoke.AddressBookArguments;

import net.rim.blackberry.api.invoke.Invoke;import net.rim.blackberry.api.pdap.BlackBerryContact;import net.rim.blackberry.api.pdap.BlackBerryContactList;import net.rim.device.api.system.ControlledAccessException;import javax.microedition.pim.PIM;import javax.microedition.pim.PIMException;

2. Invoke PIM.getInstance() to retrieve a PIM instance, and invoke PIM.openPIMList(int, int) to open the

default contact list, passing in as parameters the type of list to open (PIM.CONTACT_LIST) and the access mode with

which to open the list (PIM.READ_WRITE, PIM.READ_ONLY, orPIM.WRITE_ONLY). To open a named contact list, youcan instead invoke PIM.openPIMList(int, int, String).

BlackBerryContactList contactList = (BlackBerryContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);

3. Invoke BlackBerryContactList.getByUID(String uid) to retrieve a contact from the contact list.

BlackBerryContact contact = contactList.getByUID("1XKIOD898");

4. Create an instance of the AddressBookArguments class, passing in a Contact object as a parameter.

AddressBookArguments abArg = new AddressBookArguments("ARG_VIEW", contact);

5. Invoke Invoke.invokeApplication(APP_TYPE_ADDRESSBOOK, AddressBookArguments) and use the

AddressBookArguments object for the contact.

Invoke.invokeApplication(Invoke.APP_TYPE_ADDRESSBOOK, abArg);

6. Check forPIMException, and check forControlledAccessException if your application does not have permission

to access the application that it invokes.

39

Development Guide Open the contacts application with a specific contact list


42/86

Open the contacts application with a specific contact listYou can open the contacts application on a BlackBerry device and display a specific contact list by invoking theBlackBerryContactList.choose() method.


import net.rim.blackberry.api.pdap.BlackBerryContact;import net.rim.blackberry.api.pdap.BlackBerryContactGroup;import net.rim.blackberry.api.pdap.BlackBerryContactList;

import net.rim.blackberry.api.pdap.BlackBerryPIM;import net.rim.blackberry.api.pdap.BlackBerryPIMList;import net.rim.device.api.system.ControlledAccessException;import javax.microedition.pim.PIM;import javax.microedition.pim.PIMException;import javax.microedition.pim.PIMItem;

2. Invoke PIM.listPIMLists(int pimListType) to return an array ofString objects. The returned array provides

the system-assigned names, one for each PIM list of the specified type. The default list of the specified type is returned at

index 0 of the array.

String[] lists = PIM.listPIMLists(PIM.CONTACT_LIST);

3. Iterate over the array that is returned fromPIM.listPIMLists() to search for the system-assigned name for the

contact list that you want to display.

4. Invoke BlackBerryPIMList.getPIMListUID() to return the UID for contact list.

long uid = cl.getPIMListUID();

5. Invoke PIM.getInstance() to retrieve a PIM instance, and invoke PIM.openPIMList(int, int, long) to open

the contact list, passing in as parameters the type of list to open (PIM.CONTACT_LIST), the access mode with which toopen the list (PIM.READ_WRITE, PIM.READ_ONLY, or PIM.WRITE_ONLY), and the UID.

BlackBerryContactList list = (BlackBerryContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, uid);

6. Invoke BlackBerryContactList.choose() to return a BlackBerryContact or a

BlackBerryContactGroupPIMItem.

PIMItem item = list.choose();

if (item instanceof BlackBerryContact){

BlackBerryContact contact = (BlackBerryContact) item;int values = contact.countValues(BlackBerryContact.EMAIL);String email = contact.getString(BlackBerryContact.EMAIL, 0);System.out.println("Email is: " + email);

}else if (item instanceof BlackBerryContactGroup)

40

Development Guide Create a contact and assign it to a contact list


43/86

{...}



Create a contact and assign it to a contact listYou can create a contact and assign it to either the default contact list or another contact list on a BlackBerry device.


import net.rim.blackberry.api.pdap.BlackBerryContact;import net.rim.blackberry.api.pdap.BlackBerryContactList;import net.rim.blackberry.api.pdap.BlackBerryPIMList;import net.rim.device.api.system.ControlledAccessException;import javax.microedition.pim.PIM;import javax.microedition.pim.PIMList;import javax.microedition.pim.PIMException;import javax.microedition.pim.ContactList;

2. To add the new contact to the default contact list, invoke PIM.openPIMList(int, int) to open the default contact

list instance, passing in as parameters the type of list to open (PIM.CONTACT_LIST) and the PIM.READ_WRITE access

mode. Proceed to step 4.


3. To add the new contact to a contact list that is not the default contact list, perform the following actions:

a. Invoke PIM.listPIMLists(int), passing in as the parameter the type of list (PIM.CONTACT_LIST), to return

an array ofString objects. The returned array provides the system-assigned names for each contact list. The default

contact list is returned at index 0 of the array.

String[] lists = PIM.listPIMLists(PIM.CONTACT_LIST);

b. Iterate over the array thatPIM.listPIMLists() returns to search for the system-assigned name for the contact

list that you want to open.

c. Invoke PIM.openPIMList(int, int, String) to open the contact list instance, passing in as parameters the

type of list to open (PIM.CONTACT_LIST), the PIM.READ_WRITE access mode, and the contact list name.BlackBerryContactList contactList = (BlackBerryContactList)

PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, name);

4. Invoke ContactList.createContact() to add the new contact to the contact list.

BlackBerryContact contact = contactList.createContact();

41

Development Guide Retrieve contact information


44/86

5. Invoke one or more of the following methods to add information for the new contact. For more information about

PIMItem methods, see the API reference for the BlackBerry Java Development Environment.

addString()

addStringArray()

addDate()

addInt()

addBoolean()

addBinary()

6. Invoke the following methods to verify that the information meets the size requirements and type requirements for the

specified contact field. Invoke ContactList.isSupportedField(int) to verify that the item supports the field type.

Invoke ContactList.isSupportedAttribute(int, int) to verify that the field supports the specified

attribute.

Invoke PIMList.maxValues(int field) to verify the number of values that the field supports.

7. Invoke Contact.commit() to commit the changes.

if(contact.isModified())

{contact.commit();

}



Retrieve contact informationYou can retrieve information from a contact list on a BlackBerry device by invoking one of the PIMList.items() methods.These methods return an enumeration of all the contacts in a specific contact list. You can invoke theBlackBerryContactList.items() methods to return contact groups.


import net.rim.blackberry.api.pdap.BlackBerryContact;import net.rim.blackberry.api.pdap.BlackBerryContactList;import net.rim.blackberry.api.pdap.BlackBerryPIMList;

import java.util.Enumeration;import javax.microedition.pim.PIM;import javax.microedition.pim.PIMException;import javax.microedition.pim.PIMItem;

2. Invoke PIM.getInstance() to retrieve a PIM instance, and invoke PIM.openPIMList() to open a contact list

instance, passing in as parameters the type of list to open (PIM.CONTACT_LIST), the access mode with which to open

the list (PIM.READ_WRITE, PIM.READ_ONLY, orPIM.WRITE_ONLY), and the name if you are not opening the default

contact list.

42

Development Guide Retrieve a contact list UID


45/86


3. Invoke PIMList.items() to retrieve an enumeration of items in a contact list.

Enumeration _enum = contactList.items();

4. Invoke one of the PIMItem getter methods to retrieve contact information.

To retrieve an array of fields that contain the data for a specified contact, invokePIMItem.getFields().

To retrieve a String that represents the value for a specified contact field, invoke PIMItem.getString(int

field, int index).

To retrieve a date that represents the value for a specified contact field, invokePIMItem.getDate(int field, intindex).

while (_enum.hasMoreElements()){

BlackBerryContact c = (BlackBerryContact)_enum.nextElement();int[] fieldIds = c.getFields();int id;for(int index = 0; index < fieldIds.length; ++index){

id = fieldIds[index];if(c.getPIMList().getFieldDataType(id) == BlackBerryContact.STRING){

for(int j=0; j < c.countValues(id); ++j){

String value = c.getString(id, j);System.out.println(c.getPIMList().getFieldLabel(id) + "="+ value);

}}

}}

Retrieve a contact list UIDYou can open a contact list on a BlackBerry device by specifying a system-assigned name or a UID. The UID is associated witha BlackBerry Enterprise Server account and persists across all BlackBerry device changes, including OS updates. You can openthe contact list by its UID by invoking BlackBerryPIM.openPIMList(int pimListType, int mode, long uid).


import net.rim.blackberry.api.pdap.BlackBerryContactList;import net.rim.blackberry.api.pdap.BlackBerryPIMList;import javax.microedition.pim.PIM;import javax.microedition.pim.PIMException;import javax.microedition.pim.PIMItem;

2. Access the contact list that you want to work with.

43

Development Guide Export a contact


46/86

3. Invoke BlackBerryPIMList.getPIMListUID() to retrieve the UID of the contact list.

long uid = list.getPIMListUID();

Export a contactYou can export contact information from a contact list on a BlackBerry device to an output stream. The export process convertsa PIM item to a stream of bytes that another application can import. You can export PIM data to a supported serial format byinvoking PIM.toSerialFormat(PIMItem, OutputStream, String, String), and passing in as arguments thePIMItem, the OutputStream to which the serialized PIMItem is written, the character encoding format to use when writing

to the output stream, and the supported serial format to convert to, such as vCard.


import java.io.UnsupportedEncodingException;import java.util.Enumeration;import javax.microedit

JDE 5.0 IntegrationGuide-Beta

Documents

Transcript of JDE 5.0 IntegrationGuide-Beta