JDE 5.0 IntegrationGuide-Beta

BlackBerry Java Application
Integration
Version: 5.0
Development Guide
Published: 2010-04-06
SWD-761936-0406015514-001
Contents
1 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............................................................................................................................................... 7
Create 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.............................................................................................................. 10
Add 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
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.................................................................................................................................................................. 35
Import 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........................................................................................................................................................ 38
Open 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
Create a new populated task......................................................................................................................................................... 54
Open a task list............................................................................................................................................................................... 55
Create 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
Display HTML content from a resource in your application.............................................................................................. 71
Configure a browser field...................................................................................................................................................... 72
Send 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
Development Guide Integrating with BlackBerry Device Software applications
Integrating with BlackBerry Device Software applications 1

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

You can create BlackBerry® device applications that invoke BlackBerry Device Software applications such as the messages
application, the phone application, and the media application. When your application invokes a BlackBerry Device Software
application, 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 the Invoke.invokeApplication
() and use the following parameters: Invoke.APP_TYPE_MESSAGES and a MessageArguments object that uses
the ARG_NEW_SMS field.
Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,
new MessageArguments( MessageArguments.ARG_NEW_SMS) );
• To start the calendar, invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments).
• To start the phone application, invoke Invoke.invokeApplication(APP_TYPE_PHONE,PhoneArguments).
• To start BlackBerry® Maps and display the default map view, invoke Invoke.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 the
BlackBerry® Java® Development Environment.
5
Development Guide Message list
Message list 2
This 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 message

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.
new MessageArguments( MessageArguments.ARG_NEW_SMS));
Create a new populated text message

Use 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;
2. Create and populate a new TextMessage 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) );
6
Development Guide Create a new blank MMS message
Create a new blank MMS message

2. Invoke Invoke.invokeApplication() using the APP_TYPE_MESSAGES constant parameter and a new
MessageArguments object that uses the ARG_NEW_MMS field.
new MessageArguments( MessageArguments.ARG_NEW_MMS));
Create a new blank email message

MessageArguments object that uses the ARG_NEW field.
new MessageArguments( MessageArguments.ARG_NEW));
Create a new populated email message

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
7
Development Guide Create a new blank PIN message
• a MessageArguments object that uses the new Message object.

Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES, new MessageArguments(m));
Create a new blank PIN message

MessageArguments object that uses the ARG_NEW_PIN field.
new MessageArguments( MessageArguments.ARG_NEW_PIN));
Create a new populated PIN message

import net.rim.blackberry.api.mail.PINAddress;
2. Create and populate a new PIN message.
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 PIN message.
Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES, new MessageArguments(m));
Receive a message notification

8
Development Guide Add a listener to the message store
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 store

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();
}
{
}
4. After the try-catch block, invoke store.addStoreListener() to add a StoreListener instance to the Store
object.
store.addStoreListener(this);
9
Development Guide Add a listener to the message store for batch updates
Add a listener to the message store for batch updates

import net.rim.blackberry.api.mail.event.StoreListener;
2. Implement the StoreListener interface.
void batchOperation(StoreEvent e)
{
// Perform action when messages added or removed in batch operation.
}
Add a listener to a folder

import net.rim.blackberry.api.mail.event.FolderListener;
import net.rim.blackberry.api.mail.Folder;
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 implements FolderListener with the folder.
inbox.addFolderListener(this);
Retrieve the total count of unread email messages in all folders in the store
1. Import the required class.
10
Development Guide Open a message
2. Invoke Store.getUnreadMessageCount().
int numUnread = store.getUnreadMessageCount();
Open a message
import java.util.Date;
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 the Message object to retrieve the appropriate fields and
body contents to display to the user.
Message msg = msgs[0]; // Retrieve the first message
Address[] 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 multipart

if ( 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.
11
Development Guide Retrieving the body of an email message
Retrieving the body of an email message

An 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 recursive
method
Create 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.
12
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
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
else if (obj instanceof UnsupportedAttachmentPart)

{
_hasUnsupportedAttachment = true;
}
}
Retrieve the plain text content of an email message

In 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 that TextBodyPart.getContent() returns as a String to get the plain text part of the body of the
message.
_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
Dialog.alert("Exception: " + ex.toString());

}
}
}
Retrieve the HTML content of an email message

In 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.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 the
MimeBodyPart 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 a
String. 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 a String, the MimeBodyPart object will be a
byte array. Create a new instance of String using as a parameter the MimeBodyPart object cast as a byte array. Assign
the String to the String representation of the body part of the message.
else if (obj instanceof byte[])
{
body = new String((byte[])obj);
}
16
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 part
of the message.
if (mimeType.indexOf(ContentType.TYPE_TEXT_PLAIN_STRING) != -1)
{
8. Invoke MimeBodyPart.hasMore() and MimeBodyPart.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.
{
12. If more data is available for the MimeBodyPart object, invoke Transport.more() to retrieve the rest of the
MimeBodyPart object.
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
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.

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

{
_htmlMessage = body;
//Determine if all of the HTML body part is present.

{
try
{
}
{
}
}
}
}
Notify a BlackBerry device application that an email message is about to be

sent
18
Development Guide Notify a BlackBerry device application that an MMS message is about to be sent
import net.rim.blackberry.api.mail.NoSuchServiceException;
import net.rim.blackberry.api.mail.SendListener;
2. Implement the SendListener interface.
public class MailSendListener implements SendListener{...}
3. Create an instance of the class that implements the SendListener interface.
MailSendListener mailSL = new mailSendListener();
4. In a try block, invoke Session.waitForDefaultSession().getStore() to retrieve the Store object.
try
{
}
5. In a catch block, manage a NoSuchServiceException.
{
}
6. Invoke Store.addSendListener(MailSendListener) to add a SendListener instance.
store.addSendListener(mailSL);
Notify a BlackBerry device application that an MMS message is about to be

sent
import net.rim.blackberry.api.mms.SendListener;
import net.rim.blackberry.api.mms.MMS;
2. Implement the SendListener interface.
public class MMSSendListener implements SendListener{...}
MMSSendListener mmsSL = new mmsSendListener();
4. Add a SendListener instance.
MMS.addSendListener(mmsSL);
19
Development Guide Notify a BlackBerry device application that an SMS message is about to be sent
Notify a BlackBerry device application that an SMS message is about to be

sent
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{...}
smsSendListener smsSL = new smsSendListener();
4. Add a SendListener.
SMS.addSendListener(smsSL);
Send a message
import net.rim.blackberry.api.mail.AddressException;
import net.rim.blackberry.api.mail.MessagingException;
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 of Address objects.
Address toList[] = new Address[1];
5. In a try block, add each address to the array.
20
Development Guide Send a message
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 to
add 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);
}
21
Development Guide Reply to a message
{
}
Reply to a message
3. Invoke Session.waitForDefaultSession().getStore() to retrieve the Store object.
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.
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 specify true 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);
}
22
Development Guide Forward a message
{
}
Forward a message
2. Invoke Message.forward() on an existing Message object. 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.");
}
{
}
8. Invoke Transport.send(Message).
try
{
trans.send(fwdmsg);
}
23
Development Guide Work with message folders
{
}
Work with message folders

import net.rim.blackberry.api.mail.FolderNotFoundException;
2. Retrieve the store.
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. Invoke Invoke.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().
Retrieve an array of folders by type Invoke Store.list(int) and provide as a parameter the folder type.
Folder[] folders = store.list(INBOX);
Retrieve an array of folders through a Invoke Store.findFolder(String).
search Folder[] folders = store.findFolder("Inbox");
24
Development Guide Work with message folders
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.
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 message
Folder folder = store.getFolder("Inbox");
folder.appendMessage(msg);
25
Development Guide Attachments
Attachments 3
You 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 handler

You can use the AttachmentHandler interface to manage an attachment to an email message that appears in the message
list on the BlackBerry® device.
Note: The BlackBerry® Attachment Service receives all attachments first. Third-party attachment handlers cannot override this
default behavior. For more information about the BlackBerry Attachment Service, see the BlackBerry Enterprise Server
Administration 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 the RichTextField class to display a String 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
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 attachment

1. Import the net.rim.blackberry.api.mail.SupportedAttachmentPart class.
2. Invoke SupportedAttachmentPart.getContent().
String s = new String((byte[])p.getContent());
Retrieve information about an attachment

1. 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 attachment

import net.rim.blackberry.api.mail.Multipart;
import net.rim.blackberry.api.mail.SupportedAttachmentPart;
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
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);
}
{
}
Download attachments automatically

When a message arrives in the messages application on the BlackBerry® device with an attachment, you can automatically
download 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. If
verification errors are found, the method throws an exception. For a list of possible verification errors, see the API reference for
the BlackBerry® Java® Development Environment.
Note: The BlackBerry® Attachment Service receives all attachments first. Third-party attachment handlers cannot override this
default behavior. For more information about the BlackBerry Attachment Service, see the BlackBerry Enterprise Server
Administration Guide.
28
Development Guide Download attachments automatically
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
Calendar 4
Open the calendar

2. Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments).
3. Check for a ControlledAccessException if your application does not have permission to access the application that
it invokes.
View or change a calendar entry

import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.Event;
import javax.microedition.pim.EventList;
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
Open a new populated calendar entry

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 information

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
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
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 a RepeatRule object. The RepeatRule 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 set
for the field.
c. Use the corresponding set method, such as setString() to change
an existing value.
33
Development Guide Retrieve calendar entry information
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 information

javax.microedition.pim.Event
javax.microedition.pim.EventList
javax.microedition.pim.PIM
2. Invoke EventList.items() to retrieve an enumeration of appointments.
(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
System.out.println(event.getFieldLable(id) + "=" + value);

}
}
}
}
Export a calendar entry

import java.io.ByteArrayOutputStream;
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 enc parameter 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)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_ONLY );
ByteArrayOutputStream bytestream = new ByteArrayOutputStream();
Enumeration e = eventList.items();
{
Event event = (Event)e.nextElement();
PIM.getInstance().toSerialFormat(event, bytestream, "UTF8", dataFormats[0]);
}
Import a calendar entry

import java.io.ByteArrayInputStream;
2. Invoke PIM.getInstance().fromSerialFormat() to return an array of PIMItem objects.
3. Invoke EventList.importEvent() to add a new calendar entry.
35
Development Guide Retrieve multiple lists of calendar entries
// Convert an existing entry into a iCal and then

// import the iCal as a new entry
String[] dataFormats = PIM.supportedSerialFormats();
// Write entry to iCal

ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(event, os, "UTF8", dataFormats[0]);
// Import entry from iCal

ByteArrayInputStream is = new ByteArrayInputStream(os.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
(EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
Event event2 = eventList.importEvent((Event)pi[0]);
Retrieve multiple lists of calendar entries

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

changes
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
Notify a BlackBerry device application when the default list of calendar

entries changes
When an update occurs to the list of services on a BlackBerry® device, the list of PIM databases on a device may change. This
action may result in the creation of a new default list of calendar entries.

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 default PIMList, 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
Contact list 5
You 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 support

Support 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 the
contact 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 invoking
BlackBerryPIMList.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 application

You 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
import net.rim.blackberry.api.invoke.AddressBookArguments;
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 data

You can open the contacts application on a BlackBerry® device and display a contact by using the
Invoke.invokeApplication() method, and passing in contact data as a parameter of an AddressBookArguments
object.

import net.rim.blackberry.api.invoke.AddressBookArguments;
import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.pdap.BlackBerryContactList;
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, or PIM.WRITE_ONLY). To open a named contact list, you
can 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 for PIMException, and check for ControlledAccessException 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
Open the contacts application with a specific contact list

You can open the contacts application on a BlackBerry® device and display a specific contact list by invoking the
BlackBerryContactList.choose() method.

import net.rim.blackberry.api.pdap.BlackBerryContactGroup;
import net.rim.blackberry.api.pdap.BlackBerryPIM;
import javax.microedition.pim.PIMItem;
2. Invoke PIM.listPIMLists(int pimListType) to return an array of String 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 from PIM.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 to
open 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
BlackBerryContactGroup PIMItem.
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
{
...
}
Create a contact and assign it to a contact list

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

import javax.microedition.pim.PIMList;
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 of String 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.
b. Iterate over the array that PIM.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.
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
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 information

You 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 the
BlackBerryContactList.items() methods to return contact groups.

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, or PIM.WRITE_ONLY), and the name if you are not opening the default
contact list.
42
Development Guide Retrieve a contact list UID

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, invoke PIMItem.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, invoke PIMItem.getDate(int field, int
index).
while (_enum.hasMoreElements())
{
BlackBerryContact c = (BlackBerryContact)_enum.nextElement();
int[] fieldIds = c.getFields();
int id;
{
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 UID

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

2. Access the contact list that you want to work with.
43
Development Guide Export a contact
3. Invoke BlackBerryPIMList.getPIMListUID() to retrieve the UID of the contact list.

long uid = list.getPIMListUID();
Export a contact
You can export contact information from a contact list on a BlackBerry® device to an output stream. The export process converts
a PIM item to a stream of bytes that another application can import. You can export PIM data to a supported serial format by
invoking PIM.toSerialFormat(PIMItem, OutputStream, String, String), and passing in as arguments the
PIMItem, 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 javax.microedition.pim.Contact;
2. Invoke PIM.supportedSerialFormats() and specify the list type (PIM.CONTACT_LIST) to retrieve a string array
of the supported serial formats.
ContactList contactList = (ContactList)
String[] dataFormats = PIM.getInstance().supportedSerialFormats(PIM.CONTACT_LIST);
3. Invoke PIM.getInstance().toSerialFormat(item, stream, enc, dataFormat)to write an item to a
supported serial format. Use the enc parameter to specify the character encoding format to use when writing to the output
stream. Supported character encoding formats include UTF8, ISO-8859-1, and UTF-16BE. If the enc parameter is null, the
method uses UTF-8.
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
Enumeration e = contactList.items();
{
try
{
Contact c = (Contact)e.nextElement();
PIM.getInstance().toSerialFormat(c, byteStream, "UTF8", dataFormats[0]);
}
catch (UnsupportedEncodingException ex)
{
System.out.println(ex.toString());
}
}
44
Development Guide Import a contact
Import a contact
You can import contact information from a compatible input stream to a contact list on a BlackBerry® device. You can import
contact information by invoking fromSerialFormat(InputStream, String), and passing in as arguments the
InputStream from which the PIMItem is written and the character encoding format to use. Supported character encoding
formats include UTF8, ISO-8859-1, and UTF-16BE.
2. Invoke PIM.getInstance().fromSerialFormat() to return an array of PIM items.
ByteArrayInputStream istream =
new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(istream, "UTF8");
3. Open a contact list and invoke ContactList.importContact() to create a new contact by using a PIM item.
ContactList contactList = (ContactList)
Contact contact2 = contactList.importContact((Contact) pi[0]);
contact2.commit();
Delete a contact
You can delete a contact from the default contact list or another contact list on a BlackBerry® device.

2. To delete a contact from 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 access mode with which to
open the list (PIM.READ_WRITE, PIM.READ_ONLY, or PIM.WRITE_ONLY). Proceed to step 4.
45
Development Guide Notify an application when a contact list changes
3. To delete a contact from a contact list that is not the default contact list, perform the following actions:
a. Invoke listPIMLists(int pimListType) to return an array of String objects. The returned array provides
the system-assigned name for each contact list. The default contact list is returned at index 0 of the array.
list that you want to delete.
type of list to open (PIM.CONTACT_LIST), the access mode with which to open the list (PIM.READ_WRITE,
PIM.READ_ONLY, or PIM.WRITE_ONLY), and the contact list name.
4. Invoke BlackBerryContactList.removeContact() to delete the contact from the contact list.

contactList.removeContact(contact);
Notify an application when a contact list changes

You can register your application to receive notification of changes to the contact lists on a BlackBerry® device by implementing
the PIMListListener interface. The PIMListListener interface provides the following methods:
• itemAdded(PIMItem item), which is invoked when an item is added to a contact list
• itemUpdated(PIMItem oldItem, PIMItem newItem), which is invoked when an item changes
• itemRemoved(PIMItem item), which is invoked when an item is deleted from a contact list
import net.rim.blackberry.api.pdap.BlackBerrryContact;
2. To receive change notifications for 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 access mode with
which to open the list (PIM.READ_WRITE, PIM.READ_ONLY, or PIM.WRITE_ONLY). Proceed to step 4.
3. To receive change notifications for a contact list that is not the default contact list, perform the following actions:
46
Development Guide Notify an application when a contact list changes
a. Invoke listPIMLists(int), passing in as the parameter the type of list to open (PIM.CONTACT_LIST), to
return an array of String objects. The returned array provides the system-assigned name for each contact list. The
default contact list is returned at index 0 of the array.
list that you want to receive change notifications for.
type of list to open (PIM.CONTACT_LIST), the access mode with which to open the list (PIM.READ_WRITE,
PIM.READ_ONLY, or PIM.WRITE_ONLY), and the contact list name.
4. Invoke BlackBerryPIMList.addListener() to register a listener for the contact list.

(BlackBerryPIMList) contactList.addListener(new PIMListListener());
5. Override the PIMListListener.itemAdded(), PIMListListener.itemUpdated(), and
PIMListListener.itemRemoved() methods to configure the notification behavior.
public void itemAdded(PIMItem item)
{
System.out.println("ITEM ADDED: " +
(BlackBerryContact) item.getString(BlackBerryContact.UID, 0));
}
public void itemUpdated(PIMItem oldItem, PIMItem newItem)

{
System.out.println("ITEM UPDATED: " + (BlackBerryContact)
oldItem.getString(BlackBerryContact.UID, 0) + " to " +
(BlackBerryContact) newItem.getString(Contact.UID, 0));
}
public void itemRemoved(PIMItem item)

{
System.out.println("ITEM REMOVED: " +
(BlackBerryContact) item.getString(BlackBerryContact.UID, 0));
}
47
Development Guide Linking third-party contacts with contacts in the contacts application
Linking third-party contacts with contacts in the contacts application

You can allow BlackBerry® device users to link contact data in your BlackBerry® Java® Application with contacts in the contacts
application on the BlackBerry device by using the Contact Linking API in the
net.rim.blackberry.api.pdap.contactlinking package. For example, you can allow users to link a contact in your
CRM application with a contact in the contacts application.
A contact in a third-party application can be linked with only one contact in the contacts application. However, a contact in the
contacts application can be linked with contacts in multiple third-party applications. When a user tries to link a contact in your
application with a contact in the contacts application, you can use the Contact Linking API to perform some tasks automatically,
such as searching for a matching contact and checking whether the contact is already linked.
You can create menu items that appear in the contacts application when a user views a contact in the contacts application that
is linked with one of your contacts. The menu items can perform any action you want. For example, you can allow a user to add
notes in the contacts application about the contact in your application.
When you link a contact in your application with a contact in the contacts application, you can add a custom field to the contacts
application. You can use that custom field to display information about your contact.
To download a sample application that demonstrates how to use the Contact Linking API, visit www.blackberry.com/go/
contactlinkingsample. For more information about the Contact Linking API, see the API reference for the BlackBerry® Java®
Development Environment.
Link a contact
You can link a contact in your application with a contact in the contacts application on the BlackBerry® device. You can decide
how to interact with the BlackBerry device user when you link a contact. The steps that follow describe one possible approach.
Before you begin:
• Create the contacts in your application by creating and instantiating a class that implements the LinkableContact
interface.
• Define a class that implements AddressBookFieldFactory and register the class with your application. For more
information, see Create a custom field for linked contacts.

import net.rim.blackberry.api.pdap.*;
import net.rim.blackberry.api.pdap.contactlinking.*;
import javax.microedition.pim.*;
2. Check to see whether there is a contact in the contacts application (a BlackBerryContact object) that is a linking
candidate for your contact. The LinkedContactUtilities.getContactLinkCandidate() method returns a
BlackBerryContact if it finds a contact in the contacts application that has the same email address or phone number
as the LinkableContact that is passed to it. If there is no matching contact, the method returns null.
48
BlackBerryContact bbContact =
LinkedContactUtilities.getContactLinkCandidate(linkableContact);
3. If a match is found, link your contact with the BlackBerryContact.
bbContact = LinkedContactUtilities.linkContact(bbContact, linkableContact);
4. If a match is not found, have the user select a contact in the contacts application to link to the selected contact.
BlackBerryContactList contacts = null;
try
{
contacts = (BlackBerryContactList) PIM.getInstance().
openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
}
catch(PIMException e)
{
ContactLinkingDemo.errorDialog("Couldn't open contacts list.");
return;
}
Object choice = contacts.choose();

if(choice instanceof BlackBerryContact)
{
bbContact = (BlackBerryContact)choice;
}
5. Check to see whether the selected contact in the contacts application is already linked to a contact in your application.
LinkedContactUtilities.isContactLinked(bbContact,
linkableContact.getApplicationID())
6. If the selected contact in the contacts application is not already linked, link it to the contact in your application.
bbContact = LinkedContactUtilities.linkContact(bbContact, linkableContact);
Code sample: Linking a contact

To see an example of this approach to linking a contact, see linkContact() in the sample application for contact linking. To
download the sample application, visit www.blackberry.com/go/contactlinkingsample.
Remove a link
You can remove a link between a contact in your application and a contact in the contacts application on the BlackBerry® device.

2. Retrieve the contact in the contacts application that is linked to your contact.
49
BlackBerryContact contact =
LinkedContactUtilities.getLinkedContact(linkableContact);
3. Remove the link between the contacts.
LinkedContactUtilities.unlinkContact(contact, linkableContact.getApplicationID());
Code sample: Removing a link

private void unlinkContact(LinkableContact linkableContact)
{
BlackBerryContact contact =
LinkedContactUtilities.getLinkedContact(linkableContact);
if(contact != null)
{
LinkedContactUtilities.unlinkContact(contact,
linkableContact.getApplicationID());
}
}
Creating menu items for linked contacts

You can create menu items that are available in the contacts application on the BlackBerry® device when a user views a contact
that is linked with a contact in your application by invoking LinkedContactUtilities.registerMenuItems(). You
must assign menu items to an application group by using the LinkedContactConstants interface.
Application group Description

COMPOSE_SN_MENU_GROUP social networking applications
COMPOSE_IM_MENU_GROUP instant messaging applications
COMPOSE_OTHER_MENU_GROUP applications that are not social networking applications or instant messaging
applications
If a contact in the contacts application is linked with contacts in multiple third-party applications, the menu items in the contacts
application are grouped with other applications of the same group.
• Social networking menu items are grouped under the Social Networking menu item.
• Instant messaging menu items are grouped under the Instant Messaging menu item.
• Menu items from other types of applications are grouped under the Contact Using menu item.
The menu items from the third-party applications with linked contacts are integrated with the menu for the contacts application.
50
Situation Result
A group contains one application with linked The menu item for the application appears in the menu in the contacts
contacts. The application contains one menu application.
item.
A group contains one application with linked The application's name appears in the menu. Selecting the name displays a
contacts. The application contains multiple dialog box that contains a button for each menu item.
menu items.
A group contains multiple applications with The group menu item (such as Social Networking) appears in the menu.
linked contacts. Selecting the group menu item displays a dialog box with a button for each
application with linked contacts in the group.
Create menu items for linked contacts

You can create menu items that are available in the contacts application on the BlackBerry® device when a user views a contact
that is linked with a contact in your application.

import net.rim.blackberry.api.menuitem.ApplicationMenuItem;
import net.rim.blackberry.api.pdap.contactlinking.LinkedContactConstants;
import net.rim.blackberry.api.pdap.contactlinking.LinkedContactUtilities;
import net.rim.device.api.system.ApplicationDescriptor;
2. Create a class that extends the ApplicationMenuItem class.
public class LinkedMenuItem extends ApplicationMenuItem {...}
3. Create an application descriptor for your application.
ApplicationDescriptor appdesc = new
ApplicationDescriptor(ApplicationDescriptor.currentApplicationDescriptor(),
"Linking Application", null);
4. Create a variable to store the unique ID of your application.
public static final long APPLICATION_ID = 0x1eredfe71d34760fdL;
5. Create an array with one or more menu item instances.
ApplicationMenuItem[] items = new ApplicationMenuItem[1];
items[0] = new LinkedMenuItem();
6. Invoke LinkedContactUtilities.registerMenuItems() to add the menu items for the linked contact to the
menu. Pass in the array of menu items, the unique ID of your application, the application group, and the application descriptor.
51
LinkedContactUtilities.registerMenuItems(items, APPLICATION_ID,
LinkedContactConstants.COMPOSE_SN_MENU_GROUP, appdesc);
Code sample: Creating menu items for linked contacts

To see an example of creating menu items for linked contacts, see the SampleMenuItem class and main() in the sample
application for contact linking. To download the sample application, visit www.blackberry.com/go/contactlinkingsample.
Create a custom field for linked contacts

You can create a custom field that appears in the contacts application on the BlackBerry® device when a user selects a contact
that is linked with a contact in your application.
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
2. Create a class that implements the AddressBookFieldFactory interface.
public final class SampleAddressBookFieldFactory implements
AddressBookFieldFactory
{
private String _applicationName;
public SampleAddressBookFieldFactory(String appName)

{
_applicationName = appName;
}
}
3. In the class you created in the previous step, implement AddressBookFieldFactory.createAddressBookField
(), which defines the field that you want to add to the contacts application.
public Field createAddressBookField(final String contactID)
{
LinkableContact user = ContactListScreen.getUserForID(contactID);
if(user == null)
{
return null;
}
return new BasicEditField(_applicationName + ": ",
user.getString(LinkableContact.NAME),
BasicEditField.DEFAULT_MAXCHARS,
Field.USE_ALL_WIDTH | Field.READONLY);
}
4. Create a variable to store the unique ID of your application.
public static final long APPLICATION_ID = 0x819417e94b6ca3b7L;
52
5. Instantiate the AddressBookFieldFactory and register it with your application.

AddressBookFieldFactory factory = new SampleAddressBookFieldFactory("Sample App");
LinkedContactUtilities.registerAddressBookFieldFactory(factory, APPLICATION_ID);
When a user selects a contact in the contacts application that is linked with a contact in your application, the field that you
defined in step 3 appears on the screen of the BlackBerry device.
Code sample: Creating a custom field for linked contacts

To see an example of creating a custom field, see the SampleAddressBookFieldFactory class and the
ContactLinkingDemo class in the sample application for contact linking. To download the sample application, visit
www.blackberry.com/go/contactlinkingsample.
53
Development Guide Task list
Task list 6
View or change a task

import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;
import net.rim.blackberry.api.invoke.TaskArguments;
2. Create an instance of a ToDoList and store it in an Enumeration.
ToDoList tdl = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
Enumeration todos = tdl.items();
3. Create a ToDo object using an element from the Enumeration.
ToDo todo = (ToDo)todos.nextElement();
4. Invoke Invoke.invokeApplication() using the APP_TYPE_TASKS field, and a new TaskArguments object
created using the ARG_VIEW field and the ToDo object.
Invoke.invokeApplication(Invoke.APP_TYPE_TASKS,
new TaskArguments(TaskArguments.ARG_VIEW, todo));
Create a new blank task

created using the ARG_NEW field.
new TaskArguments( TaskArguments.ARG_NEW));
Create a new populated task

54
Development Guide Open a task list
2. Create an instance of a ToDoList.
ToDoList tdl = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
3. Invoke createToDo() to create a new ToDo object and add information to the new ToDo object.
ToDo todo = tdl.createToDo();
todo.addString(ToDo.SUMMARY, 0, "Walk the Dog");
created using the ARG_NEW field and the new ToDo object.
new TaskArguments( TaskArguments.ARG_NEW, todo));
Open a task list

2. Invoke PIM.openPIMList() and provide as parameters the type of list to open (PIM.TODO_LIST) and the access
mode with which to open the list (READ_WRITE, READ_ONLY, or WRITE_ONLY).
ToDoList todoList = null;
try
{
todoList = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
}
catch (PimException e)
{
// handle exception here
}
Create a task
55
Development Guide Add task information
2. Invoke ToDoList.createToDo()on a task list.
ToDo task = todoList.createToDo();
Add task information

2. Before you set or retrieve a field, verify that the item supports the field by invoking ToDoList.isSupportedField
(int).
3. Invoke PIMList.getFieldDataType(int) to retrieve the field data type.
4. Invoke one of the following methods to set the field data:
• addString()
• addDate()
• addInt()
• addBoolean()
• addBinary()
if (todoList.isSupportedField(ToDo.SUMMARY))
{
task.addString(ToDo.SUMMARY, ToDo.ATTR_NONE, "Create project plan");
}
if (todoList.isSupportedField(ToDo.DUE))
{
Date date = new Date();
task.addDate(ToDo.DUE, ToDo.ATTR_NONE, (date + 17280000));
}
if (todoList.isSupportedField(ToDo.NOTE))
{
task.addString(ToDo.NOTE, ToDo.ATTR_NONE, "Required for meeting");
}
if (todoList.isSupportedField(ToDo.PRIORITY))
{
task.addInt(Todo.PRIORITY, ToDo.ATTR_NONE, 2);
}
56
Development Guide Change task information
Change task information

2. To replace an existing value with a new value, invoke the appropriate set method, such as ToDo.setString().
3. To determine if a value is already set for the field, invoke ToDo.countValues().
if (task.countValues(ToDo.SUMMARY) > 0)
{
task.setString(ToDo.SUMMARY, 0, ToDo.ATTR_NONE, "Review notes");
}
4. Create code to manage a FieldFullException that a method such as addString() throws when a value already
exists.
Save a task
2. Before you commit your changes, invoke isModified() to determine whether any task fields have changed since the
task was last saved.
3. Invoke commit().
if(task.isModified())
{
task.commit();
}
Retrieve task information

2. Invoke ToDoList.items() on the task list to retrieve an enumeration.
57
Development Guide Export a task
ToDoList todoList =
(ToDoList)PIM.getInstance().openToDoList(PIM.TODO_LIST, PIM.READ_ONLY);
Enumeration enum = todoList.items();
3. Invoke ToDo.getFields() to retrieve an array of IDs for fields that have data for a particular ToDo item.
4. Invoke PIMItem.getString() to retrieve the field values.
while (enum.hasMoreElements())
{
ToDo task = (ToDo)enum.nextElement();
int[] fieldIds = task.getFields();
int id;
{
if(task.getPIMList().getFieldDataType(id) == STRING)
{
for(int j=0; j < task.countValues(id); ++j)
{
String value = task.getString(id, j);
System.out.println(task.getFieldLable(id) + "=" + value);
}
}
}
}
Export a task
2. Use an output stream writer to export tasks from the BlackBerry® device to a supported serial format.
3. To retrieve a string array of supported serial formats, invoke PIM.supportedSerialFormats(), and then specify the
list type (PIM.TODO_List).
4. To write an item to a serial format, invoke PIM.getInstance().toSerialFormat. The enc parameter 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.
ToDoList todoList =
(ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, PIM.READ_ONLY);
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
String[] dataFormats = PIM.getInstance().supportedSerialFormats(PIM.TODO_LIST);
Enumeration e = todoList.items();
58
Development Guide Import a task
{
ToDo task = (ToDo)e.nextElement();
PIM.getInstance().toSerialFormat(task, byteStream, "UTF8", dataFormats[0]);
}
Import a task
import java.io.ByteArrayInputStream;
2. Invoke PIM.getInstance().fromSerialFormat() to return an array of PIMItem objects. The enc parameter
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.
3. Invoke ToDoList.importToDo() to create a new task using the PIM items.
String[] dataFormats = PIM.toDoSerialFormats();
// Write task to serial format

ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(task, os, "UTF8", dataFormats[0]);
// Import task from serial format

ByteArrayInputStream is = new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
ToDoList todoList =
(ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, PIM.READ_WRITE);
ToDo task2 = todoList.importToDo((ToDo)pi[0]);
task2.commit();
Delete a task
2. Invoke PIM.getInstance to create a ToDoList object.
ToDoList todoList = (ToDoList)PIM.getInstance().openToDoList(PIM.TODO_LIST,
PIM.READ_ONLY);
59
Development Guide Close the task list
3. Invoke ToDoList.removeToDo() to delete the task.

todoList.removeToDo(task);
Close the task list

2. Invoke ToDoList.close().
3. Create code that manages exceptions.
try
{
todoList.close();
}
catch (PIMException e)
{
// Handle exception
}
Notify a BlackBerry device application when a list of tasks changes

import net.rim.blackberry.api.pdap.BlackBeryPIMList;
2. Implement the PIMListListener interface.
class MyTaskListListener implements PIMListListener {...}
3. Invoke BlackBerryPIMList.addListener() to register to receive notifications of changes to a task list.
BlackBerryPIMList taskList =
(BlackBerryPIMList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
taskList.addListener(new MyTaskListListener());
60
Development Guide Phone
Phone 7
The net.rim.blackberry.api.phone package contains the APIs that you can use to access the phone application on
the BlackBerry® device. You can use this package to make calls, switch between available phone lines, receive notification events,
and change phone options.
Making a call from a BlackBerry device application

BlackBerry® devices can support multiple types of phone lines, including the cellular lines that are provided by a wireless service
provider and work lines that are integrated with an organization's PBX phone system. You can create an application that interacts
with the phone lines that are available on a device. You can verify the types of phone lines that are available, and use a specific
phone line to make an outgoing call.
Make a call from a BlackBerry device application (single-line environment)

import net.rim.blackberry.api.invoke.PhoneArguments;
2. Create an instance of the PhoneArguments class, passing in the ARG_CALL field, and the destination phone number.
PhoneArguments call = new PhoneArguments(PhoneArguments.ARG_CALL, "519-555-0100");
3. Invoke Invoke.invokeApplication() to open the phone application from your application, providing the
APP_TYPE_PHONE field, and the PhoneArguments instance.
Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, call);
4. Check for IllegalArgumentException.
Make a call from a BlackBerry device application (multi-line environment)

import net.rim.blackberry.api.phone.Phone;
import net.rim.device.api.system.RadioException;
2. Invoke initiateCall() to use a specific phone line to make a call. For the destination number, pass in a hard-coded
number or user text. In the following code sample, the application makes a call to the destination number 519-555-0100
and uses the line ID that returns at index 0.
Phone.initiateCall(Phone.getLineIds()[0], "519-555-0100");
61
Development Guide Add DTMF tones to the send queue
Add DTMF tones to the send queue

import net.rim.blackberry.api.phone.PhoneCall;
2. • To add a single DTMF tone to the send queue, invoke PhoneCall.sendDTMFTone().
PhoneCall pc = new PhoneCall();
boolean added = pc.sendDTMFTone('7');
• To add multiple DTMF tones to the send queue, invoke PhoneCall.sendDTMFTones().
PhoneCall ph = new PhoneCall();
boolean added = ph.sendDTMFTones("72");
BlackBerry DTMF tones
Key Low Tone (Hz) High Tone (Hz)

1 697 1209
2 697 1336
3 697 1477
4 770 1209
5 770 1336
6 770 1477
7 852 1209
8 852 1336
9 852 1477
0 941 1209
* 941 1336
# 941 1477
62
Development Guide Listen for and handle phone events
Listen for and handle phone events

You can configure your BlackBerry® device application to listen for and automatically handle various phone events by
implementing the PhoneListener interface. The PhoneListener interface provides a set of callback methods that you
can use to receive notification of phone events.

import net.rim.blackberry.api.phone.*;
2. Create a class that implements the PhoneListener interface.
3. Register the class that implements PhoneListener by invoking addPhoneListener().
Phone.addPhoneListener(this);
4. Handle incoming phone events by using the PhoneListener callback methods. For example, to receive notification that
a call is disconnected, implement the notification in callDisconnected(int); to receive notification that a new call
has arrived, implement the notification in callIncoming(int); and to receive notification that a call is waiting,
implement the notification in callWaiting(int).
For a complete list of PhoneListener callback methods, see the API reference for the BlackBerry® Java® Development
Environment
5. To deregister the PhoneListener, invoke Phone.removePhoneListener().
Phone.removePhoneListener(this);
Listen for and handle multi-line events

For BlackBerry® devices that support multiple phone lines, you can configure your application to listen for and automatically
handle multi-line phone events by using the MultiLineListener class. The MultiLineListener class is a helper class
that implements the PhoneListener interface and provides a set of callback methods that you can use to receive notification
of multi-line phone events.
1. Import the required classes.

import net.rim.blackberry.api.phone.MultiLineListener;
2. Create a class that extends MultiLineListener.
3. Register the class as a PhoneListener by invoking Phone.addPhoneListener().
Phone.addPhoneListener(this);
4. To handle line switching events, perform the following actions:
63
Development Guide Retrieve call information by using call logs
a. Override the MultiLineListener callback methods to notify the application when a line switching event occurs.
This is particularly important when using this feature on devices that operate on CDMA networks, as a delay might
occur when the application switches between phone lines.
public void setPreferredLineFailure(int lineId)
{
_screen.popupMessage("switching failed.");
}
public void setPreferredLineSuccess(int lineId)
{
_screen.popupMessage("Switching succeeded to " +
Phone.getLineNumber(lineId) + " completed." );
}
b. Invoke Phone.setPreferredLine(), passing in the line ID of the phone line to switch to. In the following code
sample, the application selects the line that returns at index 0.
Phone.setPreferredLine( Phone.getLineIds()[0]);
Retrieve call information by using call logs

Call information on a BlackBerry® device is recorded in the call logs which can be accessed from the messages list. The call logs
are stored in call log folders that you can access by using the PhoneLogs.FOLDER_NORMAL_CALLS or
PhoneLogs.FOLDER_MISSED_CALLS constants.
import net.rim.blackberry.api.phone.phonelogs.*;
2. Invoke getInstance() to retrieve an instance of the call log.
PhoneLogs _logs = PhoneLogs.getInstance();
3. Invoke numberOfCalls() to retrieve the total number of calls in a specified call log folder (FOLDER_MISSED_CALLS or
FOLDER_NORMAL_CALLS).
int numberOfCalls =
_logs.numberOfCalls(PhoneLogs.FOLDER_NORMAL_CALLS);
4. Invoke PhoneLogs.callAt() to retrieve call information from a call log, passing in the index for the call log, and the
call log folder.
PhoneCallLog phoneLog =
(PhoneCallLog)_logs.callAt(0,PhoneLogs.FOLDER_NORMAL_CALLS);
5. Invoke PhoneCallLog.getType() to retrieve the call type. The possible return values are
TYPE_MISSED_CALL_OPENED, TYPE_MISSED_CALL_UNOPENED, TYPE_PLACED_CALL, or
TYPE_RECEIVED_CALL.
int phoneType = phoneLog.getType();
64
Development Guide Retrieve a call participant
Retrieve a call participant

You can use the PhoneCallLogID and ConferencePhoneCallLog classes to retrieve a call participant from a the call log.
import net.rim.blackberry.api.phone.phonelogs.*;
2. Invoke PhoneCallLog.getParticipant() or ConferencePhoneCallLog.getParticipantAt() to
retrieve the call particpant information.
PhoneCallLogID participant = myPhoneCallLog.getParticipant();
PhoneCallLogID participant = myConferencePhoneCallLog.getParticipantAt(0);
Retrieve call information

2. Invoke PhoneCall.getElapsedTime() to retrieve the length of time of the current call. Invoke
PhoneCall.getStatus() to retrieve the connection status for the call. Invoke
PhoneCall.getDisplayPhoneNumber() to retrieve the phone number of the call. In the following code sample, a
status message displays on the screen when the phone call has lasted more than 120 seconds.
int threshold = 120;
int elapsedTime = call.getElapsedTime();
int status = call.getStatus();

if ((status == PhoneCall.STATUS_CONNECTED
|| status == PhoneCall.STATUS_CONNECTING)
&& call.isOutGoing() && elapsedTime > threshold)
{
String phoneNumber = call.getDisplayPhoneNumber();
Status.show("Your call to " + call.getDisplayPhoneNumber() + " has lasted more
than " +
(String)threshold + ".");
}
Retrieve the phone number of a BlackBerry device

2. Invoke Phone.getDevicePhoneNumber(), passing in true to return the phone number in its regional format.
65
Development Guide Retrieve a call by call ID
String phNumber = Phone.getDevicePhoneNumber(true);

3. Check for ControlledAccessException to catch instances where your application does not have permission to access
the phone number information.
Retrieve a call by call ID

2. Invoke Phone.getCall(), passing in the call ID of the call to be retrieved.
PhoneCall ph = Phone.getCall(5);
Displaying content on a phone screen

On BlackBerry® devices that are running BlackBerry® Device Software 5.0 or later, you can customize the phone screens to
display information about a caller by using the PhoneScreen class that is provided in the
net.rim.blackberry.api.phone.phonegui package. The device displays the content on the lower part of the phone
screen. For example, for an incoming call from a customer you can display information that is provided by a CRM application.
If the device has multiple applications that can provide information about a caller, the device displays content from an application
for approximately two seconds before displaying content from the next application.
To download a sample application that demonstrates displaying content on the phone screen, visit www.blackberry.com/go/
phonescreensample.
66
Development Guide Display content on a phone screen
Display content on a phone screen

import net.rim.blackberry.api.phone.*;
import net.rim.blackberry.api.phone.phonegui.*;
2. Create a class that extends the AbstractPhoneListener class.
class MyPhoneScreenAction extends AbstractPhoneListener
{
}
3. Override PhoneListener.callIncoming() and PhoneListener.callWaiting(). For each method, add an
instance of the PhoneScreen class, passing in the call ID and your application identifier.
public void callIncoming(int callid)
{
PhoneScreen f = new PhoneScreen(callid, app);
}
public void callWaiting(int callid)
{
PhoneScreen f = new PhoneScreen(callid, app);
}
4. Invoke PhoneScreen.addImage() when the application detects a specified callid.
f.addImage(_images[0]);
5. Invoke PhoneScreen.sendDataToScreen() to display the content in the PhoneScreen object in the incoming
and active phone screens.
f.sendDataToScreen();
6. In the MyPhoneScreenAction class, invoke Phone.addPhoneListener() to register the class that extends
AbstractPhoneListener as a PhoneListener.
Phone.addPhoneListener(new MyPhoneScreenAction(this));
67
Development Guide BlackBerry Browser
BlackBerry Browser 8
Retrieve a BlackBerry Browser session

Retrieving the default session overrides any open sessions on the BlackBerry® device.
1. Import the net.rim.blackberry.api.browser.Browser class.
2. Retrieve the default BrowserSession object by invoking the static method Browser.getDefaultSession().
Retrieve a non-default BlackBerry Browser session

1. Import the net.rim.blackberry.api.browser.Browser class.
2. Invoke Browser.getSession(uid), where uid is the browser's service record UID.
Request a web page

1. Import the net.rim.blackberry.api.browser.BrowserSession class.
2. Invoke BrowserSession.displayPage(String url), specifying the URL that contains the web content.
The following sample creates a menu item that displays a web page in the BlackBerry® Browser.
private MenuItem browserItem =
new MenuItem(_resources.getString(MENUITEM_BROWSER), 110, 12)
{
public void run()
{
BrowserSession visit = Browser.getDefaultSession();
visit.displayPage("http://www.blackberry.com");
}
};
Enhanced support for web content in BlackBerry device applications

In BlackBerry® Java® Development Environment 5.0, the net.rim.device.api.browser.field2 package provides a
new set of APIs you can use to embed web content in BlackBerry device applications.
In earlier versions of the BlackBerry JDE, the net.rim.device.api.browser.field package provided functionality to
add web content to a BlackBerry device application. For more information about using this browser field, see the
BrowserFieldDemo sample application that is provided with the BlackBerry JDE.
68
Development Guide Enhanced support for web content in BlackBerry device applications
The APIs that are new in BlackBerry JDE 5.0 allow you to perform the following actions:
• load and configure the display settings for web content in Field objects in any application
• access the DOM for loaded web content
• control the HTTP handling for connections, SSL, cookies, and caching
• set callback listeners to monitor the loading progress of web pages
You can create applications that include Java objects and methods that can access and invoke JavaScript® code and be accessed
and invoked by JavaScript code by using the APIs in the net.rim.device.api.script package, which is new in BlackBerry
JDE 5.0.
Display HTML content in a browser field

import net.rim.device.api.browser.field2.*;
2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new
class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor,
invoke pushScreen() to display the custom screen for the application. The BrowserFieldDemoScreen class,
described in step 3, represents the custom screen.
public class BrowserFieldDemo extends UiApplication
{
public static void main(String[] args)
{
BrowserFieldDemo app = new BrowserFieldDemo();
app.enterEventDispatcher();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
3. Create the custom screen by extending the MainScreen class.
class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
}
}
4. In the screen constructor, create an instance of the BrowserField class.
69
BrowserField myBrowserField = new BrowserField();

5. In the screen constructor, invoke add() to add the BrowserField object to the screen.
add(myBrowserField);
6. In the screen constructor, invoke BrowserField.displayContent() to specify and display the HTML content.
myBrowserField.displayContent("<html><body><h1>Hello
World!</h1></body></html>", "http://localhost");
Display HTML content from a web page in a browser field

import net.rim.device.api.system.*;
{
{
}
{
}
}
3. Create the framework for the custom screen by extending the MainScreen class.
{
{
}
}
70
6. In the screen constructor, invoke BrowserField.requestContent() to specify the location of the HTML content
and display it.
myBrowserField.requestContent("http://www.blackberry.com");
Display HTML content from a resource in your application

{
{
}
{
}
}
{
{
}
}
71
6. In the screen constructor, invoke BrowserField.requestContent() to specify the location of the resource in your
application and display the HTML content.
myBrowserField.requestContent("local:///test.html");
Note: The BrowserField class does not access resources using a folder structure. The BrowserField class displays the
first resource found that matches the specifed file name.
Configure a browser field

{
{
}
{
}
}
3. Create the framework for the custom screen by extending the MainScreen class.
{
{
}
}
4. In the screen constructor, create an instance of the BrowserFieldConfig class.
BrowserFieldConfig myBrowserFieldConfig = new BrowserFieldConfig();
72
5. In the screen constructor, invoke BrowserFieldConfig.setProperty() to specify a property of the

BrowserField. The first parameter in setProperty() specifies the property, and the second parameter specifies the
value of the property. For example, the following code sample specifies the NAVIGATION_MODE property of a
BrowserField object:
myBrowserFieldConfig.setProperty(BrowserFieldConfig.NAVIGATION_MODE,
BrowserFieldConfig.NAVIGATION_MODE_POINTER);
6. In the screen constructor, create an instance of the BrowserField class that uses the configuration that you defined.
BrowserField browserField = new BrowserField(myBrowserFieldConfig);
Send form data to a web address in a browser field

import net.rim.device.api.io.http.*;
import java.lang.*;
import java.util.*;
{
{
}
{
}
}
{
73
{
}
}
BrowserField browserField = new BrowserField();
add(browserField);
6. In the screen constructor, create a String object that contains the base web address of the web page that you are sending
the form data to.
String baseURL = "http://www.blackberry.com";
7. In the screen constructor, create a String that specifies the form data that your application sends to the web page.
String postData = "fieldname1=value1&fieldname2=value2";
8. In the screen constructor, create a Hashtable object to store the header information for the form data.
Hashtable header = new Hashtable();
9. In the screen constructor, invoke Hashtable.put() to specify the header information for the form data.
header.put("Content-Length", "" + postData.length());
header.put("Content-Type", "application/x-www-form-urlencoded");
10. In the screen constructor, invoke BrowserField.requestContent() to send the form data to the web page and
display the web page.
browserField.requestContent(baseURL, postData.getBytes(), new
HttpHeaders(header));
74
Development Guide Menu items
Menu items 9
Adding menu items to BlackBerry Device Software applications

The Application Menu Item API, in the net.rim.blackberry.api.menuitem package, lets you define menu items to
display in BlackBerry® Device Software applications. The ApplicationMenuItemRepository class lets you add or remove
menu items from BlackBerry Device Software applications.
Create and register a menu item

Extend the ApplicationMenuItem class to define a menu item to display in BlackBerry® Device Software applications.

import java.lang.IllegalStateException;
import net.rim.blackberry.api.menuitem.ApplicationMenuItem;
import net.rim.blackberry.api.menuitem.ApplicationMenuItemRepository;
2. To create and register a menu item, perform the following tasks:
Task Steps
Define a menu item Extend the ApplicationMenuItem class.
public class SampleMenuItem extends
ApplicationMenuItem { ... }
Specify the position of the menu item Construct the ApplicationMenuItem. A higher number in the
in the menu constructor means that the menu item appears lower in the menu.
SampleMenuItem()
{
super(0x350100);
}
Specify the menu item text Implement toString().
public String toString()
{
return "My menu item";
}
Specify the behavior of the menu item Implement run().
75
Development Guide Create and register a menu item
Task Steps
public Object run(Object context)
{
// the menu's action here
return null;
}
Register the menu item Invoke ApplicationMenuItemRepository.addMenuItem().
ApplicationMenuItemRepository amir =
ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(
ApplicationMenuItemRepository.MENUITEM_PHONE,
mySampleMenuItem);
Code sample: Creating and registering a menu item

// Create menu item
int placement = 0x350100;
ApplicationMenuItem ami = new ApplicationMenuItem(placement)
{
public Object run(Object context)
{
// do something
return null;
}
public String toString()

{
return "My menu item";
}
};
// Register menu item to display when user views a contact

ApplicationMenuItemRepository amir = ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW, ami);
For more information, see the Application Integration category overview in the API reference for the BlackBerry® Java®
Development Environment.
76
Development Guide Glossary
Glossary 10
API
application programming interface
BCC
blind carbon copy
CC
carbon copy
CRM
customer relationship management
DTMF
Dual Tone Multiple-frequency
JSR
Java® Specification Request
MIME
Multipurpose Internet Mail Extensions
MEID
Mobile Equipment Identifier
MMS
Multimedia Messaging Service
PIM
personal information management
PIN
personal identification number
SMS
Short Message Service
SVG
Scalable Vector Graphics
UCS
Universal Content Stream
77
Development Guide Glossary
UID
unique identifier
UTF
UCS Transformation Format
78
Development Guide Provide feedback
Provide feedback 11
To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.
79
Development Guide Document revision history
Document revision history 12
Date Description
6 April 2010 Changed the following topics:
• Create a contact and assign it to a contact list

• Create a new populated text message
• Displaying content on a phone screen
• Display content on a phone screen
• Enhanced support for web content in BlackBerry device applications
• Retrieve call information
Deleted the following topic:
• Display content in a BlackBerry Browser field

9 November 2009 Added the following topics:
• Creating menu items for linked contacts

• Create menu items for linked contacts
• Create a custom field for linked contacts
• Download attachments automatically
• Linking third-party contacts with contacts in the contacts application
• Link a contact
• Multiple contact lists support
• Remove a link
• Retrieve a contact list UID
15 September 2009 Added the following topics:
• Displaying content on a phone screen

• Display content on a phone screen
• Listen for and handle multi-line events
• Making a call from a BlackBerry device application
• Make a call from a BlackBerry device application (multi-line environment)
14 August 2009 Added the following topics:
80
Development Guide Document revision history
Date Description
• Configure a browser field
• Display HTML content in a browser field
• Display HTML content from a web page in a browser field
• Display HTML content from a resource in your application
• Enhanced support for web content in BlackBerry device applications
• Send form data to a web address in a browser field
81
Development Guide Legal notice
Legal notice 13
©2010 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType®, SurePress™ and
related trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S.
and countries around the world.
Bluetooth is a trademark of Bluetooth SIG. Java and JavaScript are trademarks of Sun Microsystems, Inc. iCal is a trademark of
Apple Inc. Microsoft, ActiveX, Internet Explorer, and Windows are trademarks of Microsoft Corporation. Mozilla is a trademark
of Mozilla foundation. Plazmic is a trademark of Plazmic Inc. vCard is a trademark of the Internet Mail Consortium. Wi-Fi and
802.11a, 802.11b, 802.11g are trademarks of the Wi-Fi Alliance. All other trademarks are the property of their respective owners.
This documentation including all documentation incorporated by reference herein such as documentation provided or made
available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition,
endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies
("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this
documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may
describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information that
is contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements,
or other additions to this documentation to you in a timely manner or at all.
This documentation might contain references to third-party sources of information, hardware or software, products or services
including components and content such as content protected by copyright and/or third-party web sites (collectively the "Third
Party Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including,
without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency,
links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services
in this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way.
EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,
ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF
DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-
INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING
OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE
OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE
HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS
MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT
PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT
THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM
THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE
FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-
PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED
HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,
82
INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES,
FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF
BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS
ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS,
LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF
SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY
LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER
OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY
FOR NEGLIGENCE OR STRICT LIABILITY.
THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE
CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE,
TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES
OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B)
TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME
SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR
RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.
IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,
AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY
ARISING FROM OR RELATED TO THE DOCUMENTATION.
Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your
airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing
functionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roaming
arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services
may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party
rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses
are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and
Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's
products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions,
endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation
thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate
licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other
agreement with RIM.
Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server, BlackBerry® Desktop
Software, and/or BlackBerry® Device Software.
83
The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto.
NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES
PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.
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
Published in Canada
84

JDE 5.0 IntegrationGuide-Beta

Uploaded by

Copyright:

Available Formats

JDE 5.0 IntegrationGuide-Beta

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JDE 5.0 IntegrationGuide-Beta

Uploaded by

Copyright:

Available Formats

BlackBerry Java Application

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

Integrating with BlackBerry Device Software applications 1

Invoke a BlackBerry Device Software application

Create a new blank SMS text message

Create a new populated text message

Create a new blank MMS message

Create a new blank email message

Create a new populated email message

• a MessageArguments object that uses the new Message object.

Create a new blank PIN message

Create a new populated PIN message

Receive a message notification

Add a listener to the message store

Add a listener to the message store for batch updates

Add a listener to a folder

// Verify that the message is not multipart

Retrieving the body of an email message

1. Import the required classes and interfaces.

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

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

else if (obj instanceof UnsupportedAttachmentPart)

Code sample: Retrieving the content of an email message

if(obj instanceof Multipart)

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

else if (obj instanceof TextBodyPart)

else if (obj instanceof MimeBodyPart)

else if (obj instanceof SupportedAttachmentPart)

else if (obj instanceof UnsupportedAttachmentPart)

Retrieve the plain text content of an email message

1. Import the required classes and interfaces.

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

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

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

Retrieve the HTML content of an email message

1. Import the required classes and interfaces.

Code sample: Retrieving the HTML content of an email message

if (obj instanceof String)

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

//Determine if all of the text body part is present.

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

//Determine if all of the HTML body part is present.

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

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

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

Work with message folders

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

b. Create code to manage a FolderNotFoundException exception if

Create an attachment handler

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

Retrieve the contents of an attachment

Retrieve information about an attachment

Send a message with an attachment

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

Download attachments automatically

Open the calendar

View or change a calendar entry

Open a new populated calendar entry

Update calendar entry information