blackberry messenger sdk development guide 1442041 1114041224 001 1.3 beta us

BlackBerry Messenger SDKVersion: 1.3

Development Guide

Published: 2012-01-10SWD-1442041-0217032440-001

Contents1 Overview of the BlackBerry Messenger SDK.................................................................................................... 3

2 BlackBerry Messenger version dependencies.................................................................................................. 4

3 Key classes of the BlackBerry Messenger platform.......................................................................................... 5

4 Registering your application with the BlackBerry Messenger platform........................................................... 8Register your application with the BlackBerry Messenger platform................................................................ 8

Code sample: Registering your application with the BlackBerry Messenger platform............................. 9Create a subclass of BBMPlatformApplication................................................................................................. 11

5 Interacting with contacts.................................................................................................................................. 12Start a BlackBerry Messenger chat................................................................................................................... 12

Code sample: Starting a BBM Chat............................................................................................................ 12Send a download invitation to a contact.......................................................................................................... 13

Code sample: Sending a download invitation to a contact....................................................................... 14Send a join invitation to a contact.................................................................................................................... 14

Code sample: Sending a join invitation to a contact................................................................................. 15Send a message to a contact............................................................................................................................ 16

Code sample: Sending a message to a contact.......................................................................................... 19Send a file to a contact..................................................................................................................................... 20

Code sample: Sending a file to a contact................................................................................................... 22Display a list of contacts who have installed your application......................................................................... 22

Code sample: Displaying a list of contacts who have installed your application....................................... 23Respond to a contact's changes in your contact list......................................................................................... 24

Code sample: Responding to a contact's changes in your contact list...................................................... 25Send a session invitation to a contact.............................................................................................................. 26

Code sample: Sending a session join invitation to a contact..................................................................... 28Host a public session......................................................................................................................................... 28

Code sample: Hosting a public session...................................................................................................... 30Join a public BlackBerry Messenger session..................................................................................................... 30

Code sample: Joining a public session....................................................................................................... 31Send a message to all participants in a session................................................................................................ 32

Code sample: Sending a message to all participants in a session.............................................................. 33

6 Sharing content with BlackBerry Messenger contacts..................................................................................... 34Sharing content across different versions of BlackBerry Messenger............................................................... 34Share content with a user's BBM contacts....................................................................................................... 34

Notifying a user about a share request when your application is not running................................................ 35

7 Working with the user's profile and profile box............................................................................................... 37User profile....................................................................................................................................................... 37

Retrieve the user's profile......................................................................................................................... 37Update the user's profile........................................................................................................................... 38

User profile box................................................................................................................................................ 40Display the contents of the user's profile box........................................................................................... 40Add an item to the user's profile box........................................................................................................ 42Remove an item from the user's profile box............................................................................................. 43

User profile location......................................................................................................................................... 45Retrieve the user's location....................................................................................................................... 45

8 Defining service listeners.................................................................................................................................. 47Define a channel listener.................................................................................................................................. 47Define a messaging service listener.................................................................................................................. 48Define a context change listener...................................................................................................................... 49Define a session listener................................................................................................................................... 49

9 Managing your application's BlackBerry Messenger settings........................................................................... 53Retrieving version information about your application and the BlackBerry Messenger SDK........................... 53Retrieving application menu items from a BlackBerry device.......................................................................... 54Retrieving the profile box settings for your application................................................................................... 54Retrieving the public connections setting for your application........................................................................ 55Prompting the user to change the BlackBerry Messenger settings for your application................................. 56Obtaining information about how your application is invoked from within BlackBerry Messenger................ 56

10 Troubleshooting................................................................................................................................................ 59Cannot initialize AES-256: Did you install Unlimited Strength Jurisdiction Policy Files?.................................. 59<MDS-CS_MDS>:<ERROR>:<Unknown packet destination: RIM_IM>.............................................................. 59

11 Provide feedback.............................................................................................................................................. 60

12 Legal notice....................................................................................................................................................... 61

Overview of the BlackBerry Messenger SDK 1The BlackBerry Messenger SDK provides APIs that allow you to leverage the social features and functionality of theBlackBerry Messenger platform in your application.

BlackBerry Messenger is an instant messaging program designed to allow BlackBerry device users to communicatewith each other. Since its introduction to the suite of core BlackBerry applications, BBM has quickly become one ofthe most widely used applications on BlackBerry smartphones. Users do not need to sign into or out of BBM. Aslong as their BlackBerry devices are connected to a wireless network, BBM can keep users connected to their BBMcontacts and groups.

The BBM SDK, used in conjunction with the BlackBerry Java SDK , lets you use the same infrastructure upon whichBBM is built to communicate between instances of your application on multiple BlackBerry devices. For example,in a chess game application, a BlackBerry device user could invite a BBM contact to play a game of chess, and themoves could be communicated back and forth using the BBM platform.

Leverage the features of the BBM platform

You can access the same infrastructure that BBM, one of the most successful and widely used mobile socialplatforms, is built upon. With the BBM SDK, you can develop applications that incorporate social features such aspeer-to-peer connections between BlackBerry devices, or integrated chats. There is no need to develop thesesocial features yourself, and no server-side development is required to support them.

The BBM platform provides support for the social aspects of your application, such as tracking which BlackBerrydevices your application is installed on, managing the connections between instances of your application, andproactively discovering the contacts who have already installed the application.

Increase the stickiness of your application

A sticky application is one that users find useful, engaging, and use frequently. When you integrate BBM into yourapplication you can create a community where BlackBerry device users can get together, socialize, andcommunicate. Adding this social aspect can help your application maintain its presence on BlackBerry devices andhelp attract users.

Increase the discoverability of your application

When people like something, they want to share it with others. Because BlackBerry device users can communicatewith any or all of their BBM contacts from within an application, when you create a BBM connected application,you have a built-in advertising system.

Users can not only encourage their contacts to download your application, they can actively invite them to do soby sending an invitation that links directly to the application details page in the BlackBerry App World storefront.

Development Guide Overview of the BlackBerry Messenger SDK

3

BlackBerry Messenger version dependencies 2The following table shows the dependencies between versions of the BlackBerry Messenger SDK, BlackBerryMessenger, and BlackBerry Device Software. You can use this table to determine the minimum version of BBMand BlackBerry Device Software that are required to run your application.

BBM SDK version BBM version BlackBerry Device Software version

1.0 6.0.0 5.0 and later1.2 6.0.1 5.0 and later1.3 6.1.0 5.0 and later

Development Guide BlackBerry Messenger version dependencies

4

Key classes of the BlackBerry Messengerplatform

3

Class Description

BBMPlatformContext The BBMPlatformContext interface checks the access status of yourapplication and allows you to retrieve references to the application'sassociated services (for example, messaging service, contact list service,and UI service).

The BlackBerry Messenger platform returns a BBMPlatformContextinstance when your application registers with the BlackBerry Messengerplatform.

You can receive notifications of changes to the access or registration statusof your application by defining a class that extends theBBMPlatformContextListener class and its methods.

MessagingService The MessagingService class allows you to create aBBMPlatformChannel or BBMPlatformSession instance, invitecontacts to download your application, or send a file to a BlackBerryMessenger contact.

To receive notifications of events related to the messaging service, youmust extend the abstract class, MessagingServiceListener, overrideits callback methods, and invoke theMessagingService.setServiceListener() method.

To retrieve a reference to the MessagingService that is associated withyour application, invokeBBMPlatformContext.getMessagingService().

BBMPlatformChannel The BBMPlatformChannel interface represents a private connectionbetween your application and one or more contacts. If your application iscommunicating with multiple contacts, the contacts are not aware of eachother. Consequently, the contacts can only communicate with yourapplication, not each other.

You can invoke BBMPlatformConnection.setPublic() to set yourchannel to allow connections from contacts not on your BlackBerryMessenger contact list.

To receive notifications of events and changes to the channel, you mustextend the BBMPlatformChannelListener class and override thecallback methods inherited from theBBMPlatformConnectionListener class.

Development Guide Key classes of the BlackBerry Messenger platform

5

Class Description

To create an instance of BBMPlatformChannel, invokeMessagingService.createChannel(), passing in a reference to aBBMPlatformChannelListener instance.

BBMPlatformSession The BBMPlatformSession interface represents connection betweenBlackBerry Messenger contacts. When you create a session connection, anycontact in the session can invite another contact or contacts to join thesession. Each contact in the session is available for data sharing.

You can invoke BBMPlatformConnection.setPublic() to set yoursession to allow connections from contacts not on your BlackBerryMessenger contact list.

To receive notifications of events and changes to the session, you mustextend the BBMPlatformSessionListener class and override itscallback methods and the callback methods inherited from theBBMPlatformConnectionListener class.

To create an instance of BBMPlatformSession, invokeMessagingService.createSession(), passing in a reference to aBBMPlatformSessionListener object to assign the listener.

ContactListService The ContactListService class provides access to those contacts in theuser's BlackBerry Messenger contact list who have the application installed.

To receive notifications of changes to contacts in the contact list, you mustimplement the interface, PresenceListener. PresenceListenercontains one callback method, presenceUpdated(), which is called whenone of the contacts in your contact list updates his or her display picture,display name, personal message, or status.

To retrieve a reference to the ContactListService for your application,invoke BBMPlatformContext.getContactListService().

To assign a PresenceListener to your contact list, invokeContactListService.setListener(PresenceListener).

UIService The UIService class provides methods to add an application specific menuitem to BlackBerry Messenger, access a contact picker that allows the userto choose a contact based on a set that you can define, allow a user to invitecontacts that are not in the user's BlackBerry Messenger contact list toBBM, or start a BlackBerry Messenger chat.

To retrieve a reference to the UIService for your application, invokeBBMPlatformContext.getUIService().


6

Class Description

MenuItemManager The MenuItemManager class provides methods to create, add, remove,and check for a menu item on the BlackBerry Messenger contact list screen.The menu item invites the selected contact to interact with the user usingyour BlackBerry Messenger connected application.

The menu item is only displayed if the selected contact has the applicationinstalled.

If a menu item for your application already exists, when you add a newmenu item, the existing one is overwritten.


7

Registering your application with theBlackBerry Messenger platform

4

Before your application can take advantage of the BlackBerry Messenger platform, you must register it with theBlackBerry Messenger platform. When your application registers with the BlackBerry Messenger platform, theplatform returns a BBMPlatformContext object which you will need when implementing any BlackBerryMessenger functionality in your application.

Register your application with the BlackBerry MessengerplatformBefore you begin: Create a subclass of BBMPlatformApplication.

1. Import the required classes and interfaces.

import net.rim.blackberry.api.bbm.platform.BBMPlatformApplication;import net.rim.blackberry.api.bbm.platform.BBMPlatformContext;import net.rim.blackberry.api.bbm.platform.BBMPlatformContextListener;import net.rim.blackberry.api.bbm.platform.BBMPlatformManager;import net.rim.device.api.ui.container.MainScreen;import net.rim.device.api.ui.UiApplication;

2. Create the application framework by extending the UiApplication class. Inside the new class, declare aninstance of MyBBMAppPlugin as a member variable of the MyBBMPlatformApp class.

public class MyBBMPlatformApp extends UiApplication{ private MyBBMAppPlugin myPlugin; }

3. Create the framework for a custom screen by extending the MainScreen class.

private class MyBBMPlatformScreen extends MainScreen{ MyBBMPlatformScreen() { setTitle("My BBM Platform screen"); }}

4. In the constructor for the MyBBMPlatformApp class, create an instance of your MyBBMAppPlugin class andinvoke pushScreen() to display the screen for the application.

public MyBBMPlatformApp() { myPlugin = new MyBBMAppPlugin(); pushScreen(new MyBBMPlatformScreen());}

Development Guide Registering your application with the BlackBerry Messenger platform

8

5. In the same constructor, call invokeLater(new Runnable()) to add the object to the event queue for yourapplication. In the object's run() method invoke BBMPlatformManager.register() in a try/ctch block toregister your plug-in with the BlackBerry Messenger platform. The register() method returns aBBMPlatformContext object for this application.

invokeLater(new Runnable(){ public void run( { BBMPlatformContext platformContext = null; try { platformContext = BBMPlatformManager.register(myPlugin); } catch (ControlledAccessException e) { // BBM Social Platform has been disabled }

6. Define a context change listener. The code sample in step 7 assumes that your context change listener subclassis named MyBBMPlatformContextChangeListener and that it implements theBBMPlatformContextListener interface.

7. In the run() method, create a new instance of a BBMPlatformContextListener and invokeBBMPlatformContext.setChangeListener() to assign the listener to the BBMPlatformContext.

if (platformContext != null) { MyBBMPlatformContextListener platformContextListener; platformContextListener = new MyBBMPlatformContextListener(); platformContext.setListener(platformContextListener); } } });

8. In your MyBBMPlatformApp class, create a main() method. In main() create an instance of theMyBBMPluginApp class and add it to the event thread of your device to start the application and enable it toreceive events.

public static void main(String[] args){ MyBBMPlatformApp theApp = new MyBBMPlatformApp(); theApp.enterEventDispatcher();}

You have now registered your application with the BlackBerry Messenger platform.

Code sample: Registering your application with the BlackBerry Messengerplatform

Development Guide Register your application with the BlackBerry Messenger platform

9

import net.rim.blackberry.api.bbm.platform.BBMPlatformApplication;import net.rim.blackberry.api.bbm.platform.BBMPlatformContext;import net.rim.blackberry.api.bbm.platform.BBMPlatformContextListener;import net.rim.blackberry.api.bbm.platform.BBMPlatformManager;import net.rim.device.api.ui.UiApplication;import net.rim.device.api.ui.container.MainScreen;

public class MyBBMPlatformApp extends UiApplication{ private MyBBMAppPlugin myPlugin;

public MyBBMPlatformApp() { myPlugin = new MyBBMAppPlugin(); pushScreen(new MyBBMPlatformScreen()); invokeLater(new Runnable() { public void run() { BBMPlatformContext platformContext = null; try { platformContext = BBMPlatformManager.register(myPlugin); } catch (ControlledAccessException e) { // The BBM platform has been disabled } if (platformContext != null) { MyBBMPlatformContextListener platformContextListener; platformContextListener = new MyBBMPlatformContextListener(); platformContext.setListener(platformContextListener); } } } ); }

private class MyBBMPlatformScreen extends MainScreen { MyBBMPlatformScreen() { setTitle("BBM Platform application"); } }

private class MyBBMAppPlugin extends BBMPlatformApplication { public MyBBMAppPlugin() { super( "Insert your UUID here" ); } }

private class MyBBMPlatformContextListener extends BBMPlatformContextListener

Development Guide Register your application with the BlackBerry Messenger platform

10

{ public void accessChanged(boolean isAccessAllowed, int accessErrorCode) { if (!isAccessAllowed) { // You cannot access the BBM platform } }

public void appInvoked(int reason, Object param) { // Code for handling different contexts for invocation } } public static void main(String[] args) { MyBBMPlatformApp theApp = new MyBBMPlatformApp(); theApp.enterEventDispatcher(); }}

Create a subclass of BBMPlatformApplication1. Import the required classes and interfaces.

import net.rim.blackberry.api.bbm.platform.*;

2. Create the application framework by extending the BBMPlatformApplication class. TheBBMPlatformApplication class must be extended by any application that registers with the BlackBerryMessenger platform.

public class MyBBMAppPlugin extends BBMPlatformApplication{ }

3. In the MyBBMAppPlugin class that you just created, create a constructor. If necessary, implement the methodsof the superclass in the MyBBMAppPlugin class.

public MyBBMAppPlugin(){ //Add any initialization code for your application here}

Development Guide Create a subclass of BBMPlatformApplication

11

Interacting with contacts 5

Start a BlackBerry Messenger chatBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the MyBBMChatScreen screen passes in a reference to theapplication's associated BBMPlatformContext object into the screen's contructor.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.service.*;

2. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application'sassociated BBMPlatformContext.

public class MyBBMChatScreen extends MainScreen{ public MyBBMChatScreen(BBMPlatformContext platformContext) {

}}

3. Invoke BBMPlatformContext.getUIService().startBBMChat() to open a chat window. You mustspecify a message as a parameter. This message appears in the reply field of the conversation window. You canspecify a contact to chat with by passing in a parameter. If you do not specify a contact, a contact picker UIcomponent containing all the contacts in the user's BlackBerry Messenger contact list will open automatically.

public class MyBBMChatScreen extends MainScreen{ public MyBBMChatScreen(BBMPlatformContext platformContext) { platformContext.getUIService().startBBMChat("Let's chat"); }}

Code sample: Starting a BBM ChatThe following code sample assumes that the class that displayed the MyBBMChatScreen has passed a referenceto the application's associated BBMPlatformContext object into the MyBBMChatScreen constructor.


public class MyBBMChatScreen extends MainScreen{ public MyBBMChatScreen(BBMPlatformContext platformContext) {

Development Guide Interacting with contacts

12

platformContext.getUIService().startBBMChat("Let's chat!"); }}

Send a download invitation to a contactBefore you begin: Make sure you have completed the task, Register your application with the BlackBerryMessenger pPlatform, and that the class that displays the MyBBMInviteScreen screen passes in a reference tothe application's associated BBMPlatformContext object into the screen's contructor.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.service.*;import net.rim.device.api.ui.component.*;


public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) {

}}

3. In the constructor, retrieve a reference to the messaging service associated with this application's platformcontext.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); }}

4. Invoke MessagingService.sendDownloadInvitation() to invite a contact to download your application.A Contact picker UI component opens for the user to choose a contact to invite.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); messagingService.sendDownloadInvitation(); }}

Development Guide Send a download invitation to a contact

13

Code sample: Sending a download invitation to a contactThe following code sample assumes that the class that displayed the MyBBMInviteScreen has passed areference to the application's associated BBMPlatformContext object into the MyBBMInviteScreenconstructor.


public class MyBBMInviteScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); messagingService.sendDownloadInvitation(); }}

Send a join invitation to a contactBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the screen in the following code sample passes in a referenceto the application's associated BBMPlatformContext object.





}}

3. In the MyBBMInviteScreen constructor, retrieve a reference to the messaging service associated with thisapplication's platform context.


Development Guide Send a join invitation to a contact

14

4. Define a channel listener. The code sample in step 5 assumes that you named the listener class,MyChannelListener.

5. Invoke MessagingService.createChannel() to create a new BBMPlatformChannel, passing in yourchannel listener class.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformChannel channel = messagingService.createChannel(new MyChannelListener()); }}

6. In an if statement that checks whether you created the BBMPlatformChannel successfully, invokeBBMPlatformChannel.sendInvitation() to invite a contact to your application. In the parameters forsendInvitation(), you can specify a message to be displayed when the contact receives the invitation, aparameter that will be passed to the application's main method as args[1], and an expiry time. The followingcode sample passes in the value 0 for expiry time (that is, the invitation never expires). A Contact picker UIcomponent opens for the user to choose a contact to invite.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformChannel channel = messagingService.createChannel(new MyChannelListener()); if (channel != null) { channel.sendInvitation(“Let's play a game”, "Chess App", 0); } }}

After you finish:

You can interact with the contact that you invited to your channel when they accept your invitation.

Code sample: Sending a join invitation to a contactThe following code sample assumes that the class that displayed the MyBBMInviteScreen has passed areference to the application's associated BBMPlatformContext object into the MyBBMScreen constructor.

This code sample also assumes that you have completed the task, Define a channel listener and named thechannel listener class, MyChannelListener.


Development Guide Send a join invitation to a contact

15

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformChannel channel = messagingService.createChannel(new MyChannelListener());

if (channel != null) { channel.sendInvitation(“Let's play a game”, "Chess App", 0); } }}

Send a message to a contactBefore you begin: Complete the task, Register your application with the BlackBerry Messenger platform. Verifythat the class that displays the screen in the following code sample passes in a reference to theBBMPlatformContext object associated with the application.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.io.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.blackberry.api.bbm.platform.service.*;import net.rim.device.api.ui.component.*;


public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) {

}}

3. Declare an instance of BBMPlatformChannel as a member variable of the MyBBMScreen class.

public class MyBBMScreen extends MainScreen{ BBMPlatformChannel _channel;

public MyBBMScreen(BBMPlatformContext platformContext) { }}

Development Guide Send a message to a contact

16

4. In the MyBBMScreen constructor, retrieve an instance of the messaging service.

public MyBBMScreen(BBMPlatformContext platformContext){ MessagingService myMessagingService = platformContext.getMessagingService();}

5. Create a channel passing in an instance of a BBMPlatformChannelListener that you will define in step 9.

public MyBBMScreen(BBMPlatformContext platformContext){ MessagingService myMessagingService = platformContext.getMessagingService();

_channel = messagingService.createChannel(_channelListener);}

6. Invite a contact to your application. In the parameters for sendInvitation(), you can specify a message tobe delivered when the contact receives the invitation, a parameter that will be passed to the application's mainmethod as args[1], and an expiry time. The following code sample passes in the value 0 for expiry time (thatis, the invitation never expires). A Contact picker UI component opens for the user to choose a contact to invite.

public MyBBMScreen(BBMPlatformContext platformContext){ MessagingService messagingService = platformContext.getMessagingService(); _channel = messagingService.createChannel(_channelListener); _channel.sendInvitation("Let's play a game", "Chess App", 0);}

7. In the MyBBMScreen class, define a helper method, onContactJoined(), which theBBMPlatformChannelListener.contactJoined() callback method invokes. Pass in a reference to thecontact who has just joined.

public class MyBBMScreen extends MainScreen{ BBMPlatformChannel _channel;

public MyBBMScreen(BBMPlatformContext platformContext) { //code from steps 5 to 7 } private onContactJoined(BBMPlatformContact contact) {

}}

8. In the onContactJoined() method, create a message, wrap it in a BBMPlatformData object, and, in a try-catch block, send the message. In the following code sample, the message is sent to all contacts who have joinedthe channel, informing that a participant has left the game.

private void onContactLeft(BBMPlatformContact contact){ String goodbyeMsg = contact.getDisplayName() + " has left the game.";


17

BBMPlatformData data = new BBMPlatformData(goodbyeMsg);

try { _channel.sendData(data, _channel.getContactList()); } catch (BBMPlatformException e) { // Error handler code }}

9. In the MyBBMScreen class, define the channel listener, _channelListener, as a private inner class. In thecontactJoined() method, invoke the onContactJoined() method passing in the BBMPlatformContactthat just joined.

public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { //code from steps 4 to 6 }

private void onContactJoined(BBMPlatformContact contact) { //code from step 8 }

private BBMPlatformChannelListener _channelListener = new BBMPlatformChannelListener() { public void contactsInvited(BBMPlatformConnection conn, BBMPlatformContactList contactList) { } public void contactsJoined(BBMPlatformConnection conn, BBMPlatformContactList contacts, String cookie, int type) { }

public void contactDeclined(BBMPlatformConnection conn, BBMPlatformContact contact) { } public void contactLeft(BBMPlatformConnection conn, BBMPlatformContact contact) { onContactLeft(contact); } public void dataReceived(BBMPlatformConnection conn, BBMPlatformContact sender, BBMPlatformData data)


18

{ } } };}

Code sample: Sending a message to a contactThe following code sample assumes that the class that displayed the MyBBMScreen passed a reference to theapplication's associated BBMPlatformContext object into the MyBBMScreen constructor.

import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.io.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.blackberry.api.bbm.platform.service.*;import net.rim.device.api.ui.component.*;

public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); _channel = messagingService.createChannel(_channelListener); _channel.sendInvitation("Let's play a game", "Chess App", 0);

}

private void onContactLeft(BBMPlatformContact contact) { String goodbyeMsg = contact.getDisplayName() + " has left the game."; BBMPlatformData data = new BBMPlatformData(goodbyeMsg);

try { _channel.sendData(data, _channel.getContactList()); } catch (BBMPlatformException e) { // Error handler code } }

private BBMPlatformChannelListener _channelListener = new BBMPlatformChannelListener() { public void contactsInvited(BBMPlatformConnection conn, BBMPlatformContactList contactList ) { } public void contactsJoined(BBMPlatformConnection conn, BBMPlatformContactList contacts, String cookie, int type)


19

{ } public void contactDeclined(BBMPlatformConnection conn, BBMPlatformContact contact) { } public void contactLeft(BBMPlatformConnection conn, BBMPlatformContact contact) { onContactLeft(contact); } public void dataReceived(BBMPlatformConnection conn, BBMPlatformContact sender, BBMPlatformData data) { } };}

Send a file to a contactBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the MyBBMScreen screen in the following code samplepasses in a reference to the application's associated BBMPlatformContext object.



2. Create a class that extends MainScreen. In the constructor for this screen class, pass in theBBMPlatformContext that is associated with your application.

public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) {

}}

3. In the constructor, invoke UIService.showContactPicker() to display a contact picker that allows the userto choose the contact to send the file too. The following code sample displays a contact picker with all the user'sBlackBerry Messenger contacts. The selected set of contacts is returned as an enumeration.

public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To",

Development Guide Send a file to a contact

20

ContactListProvider.BBM_CONTACTS_WITH_APP, false, false); }}

4. If the user chose a contact from the contact picker, retrieve a reference to first element in the enumeration.

public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false); if (contacts.size() > 0) { BBMPlatformContact contact = (BBMPlatformContact)contacts.getAll().nextElement(); } }}

5. Invoke FilePicker.getInstance() to display a file picker that allows the user to choose the file that theywant to send. When the user has selected a file, assign the file path to a String.

public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false); if (contacts.size() > 0) { BBMPlatformContact contact = (BBMPlatformContact)contacts.getAll().nextElement(); FilePicker filePicker = FilePicker.getInstance(); String filePath = filePicker.show(); } }}

6. Invoke MessagingService.sendFile() to send the file.

public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { BBMPlatformContactList contacts = plstformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false); if (contacts.size() > 0) { BBMPlatformContact contact =

Development Guide Send a file to a contact

21

(BBMPlatformContact)contacts.getAll().nextElement(); FilePicker filePicker = FilePicker.getInstance(); String filePath = filePicker.show();

platformContext.getMessagingService().sendFile(contact, filePath, "Here's the file"); } }}

Code sample: Sending a file to a contactThe following code sample assumes that the class that pushed the MyBBMScreen has access to theBBMPlatformContext object for this application and has passed it into the MyBBMScreen constructor.


public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { BBMPlatformContactList contacts = platformContext.getUIService().showContactPicker("Send File To", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false); if (contacts.size() > 0) { BBMPlatformContact contact = (BBMPlatformContact)contacts.getAll().nextElement(); FilePicker filePicker = FilePicker.getInstance(); String filePath = filePicker.show();

platformContext.getMessagingService().sendFile(contact, filePath, "Here's the file"); } }}

Display a list of contacts who have installed yourapplicationBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the screen passes in a reference to theBBMPlatformContext object associated with your application.


Development Guide Display a list of contacts who have installed your application

22

import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.service.*;import net.rim.device.api.ui.container.*;import java.util.*;


public class MyBBMContactListScreen extends MainScreen{ public MyBBMContactListScreen(BBMPlatformContext platformContext) {

}}

3. In the constructor, invoke BBMPlatformContext.getContactListService() to retrieve a reference to theContactListService object that is associated with the application.

ContactListService contactListService = platformContext.getContactListService();

4. In the constructor, invoke ContactListService.getContacts() to retrieve a BBMPlatformContactListobject that contains all of the contacts who have installed this application.

BBMPlatformContactList contacts = contactListService.getContactList();

5. In the constructor, invoke BBMPlatformContactList.getAll() to retrieve an enumeration object of all ofthe contacts in the BBMPlatformContactList.

Enumeration contactsEnum = contacts.getAll();

6. In the constructor, you can now traverse the enumeration. The following code sample demonstrates how todisplay the names of the contacts.

while(contactsEnum.hasMoreElements()) { BBMPlatformContact contact = (BBMPlatformContact)contactsEnum.nextElement(); myScreen.add(new LabelField(contact.getDisplayName());}

Code sample: Displaying a list of contacts who have installed yourapplicationThe following code sample assumes that the class that displayed the MyBBMContactListScreen has passed areference to the application's associated BBMPlatformContext object into the MyBBMContactListScreenconstructor.

import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.service.*;import net.rim.device.api.ui.container.*;import java.util.*;

public class MyBBMContactListScreen extends MainScreen

Development Guide Display a list of contacts who have installed your application

23

{ public MyBBMContactListScreen(BBMPlatformContext platformContext) { ContactListService contactListService = platformContext.getContactListService(); BBMPlatformContactList contacts = contactListService.getContactList(); Enumeration contactsEnum = contacts.getAll();

while(contactsEnum.hasMoreElements()) { BBMPlatform contact = (BBMPlatformContact)contactsEnum.nextElement(); add(new LabelField(contact.getDisplayName()); } }}

Respond to a contact's changes in your contact listBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the screen passes in a reference to the application'sassociated BBMPlatformContext object.



2. Create a class that implements the PresenceListener interface and extends MainScreen. In the constructorfor this screen class, pass in the application's associated BBMPlatformContext object.

public class MyBBMContactListScreen implements PresenceListener extends MainScreen{ public MyBBMContactListScreen(BBMPlatformContext platformContext) {

}}

3. In the constructor, invokeBBMPlatformContext.getContactListService().setPresenceListener() to assign thePresenceListener to your application.

public class MyBBMContactListScreen implements PresenceListener{ public MyBBMContactListScreen(BBMPlatformContext platformContext) { platformContext.getContactListService().setPresenceListener(this); }}

Development Guide Respond to a contact's changes in your contact list

24

4. In the MyBBMContactListScreen class, implement the PresenceListener.presenceUpdated()method. The following code displays a dialog box that informs the user of changes to a contact in your BlackBerryMessenger contact list. The following code sample uses a helper method, getEventName(), to parse theeventType parameter and return a readable String.

public void presenceUpdated(BBMPlatformContact contact, int eventType){ final String str = "[" + getEventName(eventType) + "] was changed by " + contact.getDisplayName(); Dialog.inform(str);}

private String getEventName(int eventType){ String eventName;

switch(eventType) { case PresenceListener.EVENT_TYPE_DISPLAY_PICTURE: eventName = "Display picture"; break; case PresenceListener.EVENT_TYPE_DISPLAY_NAME: eventName = "Display name"; break; case PresenceListener.EVENT_TYPE_PERSONAL_MESSAGE: eventName = "Personal Message"; break; case PresenceListener.EVENT_TYPE_STATUS: eventName = "Status"; break; default: eventName = "Default"; }}

Code sample: Responding to a contact's changes in your contact listThe following code sample assumes that the class that pushed the MyBBMContactListScreen has access to theBBMPlatformContext object for this application and has passed it into the MyBBMContactListScreenconstructor.

import net.rim.blackberry.api.bbm.platform.*;import net.rim.device.api.ui.component.*;

public class MyBBMContactListScreen implements PresenceListener{ public MyClass(BBMPlatformContext platformContext) { platformContext.getContactListService().setPresenceListener(this);

Development Guide Respond to a contact's changes in your contact list

25

}

public void presenceUpdated(BBMPlatformContact contact, int eventType) { final String str = "[" + getEventName(eventType) + "] was changed by " + contact.getDisplayName(); Dialog.inform(str); } private String getEventName(int eventType) { String eventName;

switch(eventType) { case PresenceListener.EVENT_TYPE_DISPLAY_PICTURE: eventName = "Display picture"; break; case PresenceListener.EVENT_TYPE_DISPLAY_NAME: eventName = "Display name"; break; case PresenceListener.EVENT_TYPE_PERSONAL_MESSAGE: eventName = "Personal Message"; break; case PresenceListener.EVENT_TYPE_STATUS: eventName = "Status"; break; default: eventName = "Default"; } }}

Send a session invitation to a contactBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the screen passes in a reference to the application'sassociated BBMPlatformContext object into the screen's contructor.



2. Define a session listener. The code sample in step 5 assumes that you named the listener class,MySessionListener.

3. Create a class that extends MainScreen. In the constructor for this screen class, pass in the application'sassociated BBMPlatformContext object.

Development Guide Send a session invitation to a contact

26


}}

4. In the constructor, retrieve a reference to the messaging service associated with this application's platformcontext.


5. Invoke MessagingService.createSession() to create a new BBMPlatformSession instance. Pass in aninstance of the listener, that you defined in step 2, as a parameter.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformSession mySession = messagingService.createSession(new MySessionListener()); }}

6. Invoke BBMPlatformSession.sendInvitation() to invite a contact to your session. ThesendInvitation()method can take three parameters. The first parameter specifies a message to be deliveredwhen the contact receives the invitation. The second parameter is an argument that will be passed to theapplication's main method as args[1]. The third parameteris the invitation's expiry time. The following codesample passes in the value 0 for expiry time (that is, the invitation never expires). A Contact picker UI componentwill automatically open for the user to choose a contact to invite.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatforSession mySession = messagingService.createSession(new MySessionListener());

if (mySession != null) { mySession.sendInvitation(“Let's play a game”, "Poker App", 0); } }}

Development Guide Send a session invitation to a contact

27

Code sample: Sending a session join invitation to a contactThe following code sample assumes that the class that displayed the MyBBMInviteScreen has passed areference to the application's associated BBMPlatformContext object into the MyBBMScreen constructor.

This code sample also assumes that you have completed the task, Define a session listener and named the sessionlistener class, MySessionListener.


public class MyBBMSessionScreen extends MainScreen{ public MyBBMSessionScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatforSession mySession = messagingService.createSession(new MySessionListener());

if (mySession != null) { mySession.sendInvitation(“Let's play a game”, "Poker App", 0); } }}

Host a public sessionBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the screen passes in a reference to theBBMPlatformContext object associated with your application into the screen's constructor.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.service.*;import net.rim.device.api.ui.component.*;import net.rim.device.api.ui.container.MainScreen;

2. Define a session listener. The code sample in step 5 assumes that you named the listener class,MySessionListener.

3. Create a class that extends MainScreen. In the constructor for this screen class, pass in theBBMPlatformContext object associated with your application.


Development Guide Host a public session

28

}}

4. In the constructor, retrieve a reference to the messaging service for this application.


5. Invoke MessagingService.createSession() to create a new BBMPlatformSession instance. Pass in aninstance of the listener you defined in step 2 as a parameter.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformSession mySession = messagingService.createSession(new MySessionListener()); }}

6. Invoke BBMPlatformSession.setPublic() to set this session as public so that contacts who are not in yourBlackBerry Messenger contact list can join. A confirmation dialog is presented to the user when this method isinvoked.

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformSession mySession = messagingService.createSession(new MySessionListener());

boolean isHosting = mySession.setPublic();

if (isHosting) { // add code to send PIN and PPID to your web service } }}

After you confirm that you want to host the session, you must send your web service your PIN and PPID. Youcan now receive join requests from users looking to join your session even if they are not one of your BlackBerryMessenger contacts. The joinRequestReceived() method in your BBMPlatformSessionListenerimplementation is invoked when a BBMPlatformIncomingJoinRequest object is received by yourapplication. You can accept or decline this request by invokingBBMPlatformIncomingJoinRequest.accept() or BBMPlatformIncomingJoinRequest.decline(),respectively.

Development Guide Host a public session

29

Code sample: Hosting a public sessionThe following code sample assumes that the class that displayed the MyBBMInviteScreen has passed areference to the application's associated BBMPlatformContext object into the MyBBMInviteScreenconstructor.

This code sample also assumes that you have completed the task, Define a session listener and named the sessionlistener class, MySessionListener.

import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.service.*;import net.rim.device.api.ui.component.*;import net.rim.device.api.ui.container.MainScreen;

public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformSession mySession = messagingService.createSession(new MySessionListener()); boolean isHosting = mySession.setPublic();

if (isHosting) { // add code to send PIN and PPID to your web service } }}

Join a public BlackBerry Messenger sessionBefore you begin: Make sure that you have registered your application with the BlackBerry Messenger platform,and that the class that displays the MyBBMSessionScreen screen passes in a reference to the application'sassociated BBMPlatformContext object into the screen's contructor.



2. Create a class that extends MainScreen. In the constructor for this screen class, pass in theBBMPlatformContext object that is associated with your application.

public class MyBBMSessioncreen extends MainScreen{ public MyBBMSessionScreen(BBMPlatformContext platformContext) {

Development Guide Join a public BlackBerry Messenger session

30

}}

3. In the constructor, retrieve a reference to the messaging service for the application.

public class MyBBMSessionScreen extends MainScreen{ public MyBBMSessionScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); }}

4. Invoke MessagingService.sendJoinRequest() to send a join request to a public session with the specifiedhost ID, host PPID, and another parameter that you want to send to the host (for example, you could tell thehost what level you would like to start on if the event is a game). The host must provide you with the host ID,host PPID, and a string that provides some additional information (this can be achieved using a matchmakingserver that you must set up). The sendJoinRequest() method returns aBBMPlatformOutgoingJoinRequest object. A confirmation dialog is displayed when you invoke this method.If you want to cancel the join request before it is accepted or declined by the host, invokeBBMPlatformOutgoingJoinRequest.cancel().

public class MyBBMSessionScreen extends MainScreen{ public MyBBMSessionScreen(BBMPlatformContext platformContext) { BBMPlatformOutgoingJoinRequest request = messagingService.sendJoinRequest(123456, "12344567", "My game"); if (request.getStatus() == BBMPlatformJoinRequest.REQUEST_STATUS_ACCEPTED) { Dialog.inform("Welcome to My Chess Game"); } else { Dialog.inform("The request was declined"); } }}

Code sample: Joining a public sessionThe following code sample assumes that the class that displayed the MyBBMChatScreen has passed a referenceto the application's associated BBMPlatformContext object into the MyBBMChatScreen constructor.


public class MyBBMInviteScreen extends MainScreen{ public MyBBMInviteScreen(BBMPlatformContext platformContext) { BBMPlatformOutgoingJoinRequest request =

Development Guide Join a public BlackBerry Messenger session

31

messagingService.sendJoinRequest(123456, "12344567", "My game"); if (request.getStatus() == BBMPlatformJoinRequest.REQUEST_STATUS_ACCEPTED) { Dialog.inform("Welcome to My Chess Game"); } else { Dialog.inform("The request was declined"); } }}

Send a message to all participants in a sessionBefore you begin: Send a session invitation to a contact to populate your session's contact list with contacts.



2. In the if statement that you created when you completed the Send a session invitation to a contact task, invokeBBMPlatformSession.getContactList() to retrieve an instance of BBMPlatformContactList. Thereturned contact list contains all the contacts that have accepted your invitation.

if(mySession != null){ BBMPlatformContactList contacts = mySession.getContactList();}

3. Create an instance of the BBMPlatformData class (a wrapper class for your data message) and String object(the body of your message). The following code sample uses the BBMPlatformData constructor that definesa content type (the first parameter of the constructor), the data itself (the second parameter), and an applicationdefined ID (the third parameter). You can define the content type and ID using any String and int valuerespectively that your application requires for parsing. You can also send a message without those values if theyare not needed.

String myMsg = "Test data";BBMPlatformData data = new BBMPlatformData("Message", myMsg.getBytes(), 0);

4. Invoke BBMPlatformSession.broadcastData(), inherited from its parent class, to send the message. Thefollowing code sample displays a dialog box confirming that the message has been sent.

String myMsg = "Test data";BBMPlatformData data = new BBMPlatformData("Message", myMsg.getBytes(), 0); mySession.broadcastData(data, contacts);

Development Guide Send a message to all participants in a session

32

Code sample: Sending a message to all participants in a sessionThe following code sample assumes that the class that displayed the MyBBMScreen has passed a reference to theapplication's associated BBMPlatformContext object into the MyBBMScreen constructor.

This code sample also assumes that you have completed the task, Define a session listener, and that you namedthe session listener class, MySessionListener.


public class MyBBMScreen extends MainScreen{ public MyBBMScreen(BBMPlatformContext platformContext) { MessagingService messagingService = platformContext.getMessagingService(); BBMPlatformSession mySession = messagingService.createSession(new MySessionListener());

if (mySession != null) { channel.sendInvitation("Lets play a game", "Poker App", null, 0);

BBMPlatformContactList contacts = channel.getContactList();

String myMsg = "Test data"; BBMPlatformData data = new BBMPlatformData("Message", myMsg.getBytes(), 0);

mySession.sendData(data, contacts); } }}

Development Guide Send a message to all participants in a session

33

Sharing content with BlackBerry Messengercontacts

6

Sharing content across different versions of BlackBerryMessengerThe BBM platform allows your application to share content with a user's BlackBerry Messenger contacts, even ifthe contact is not running the same version of BBM. If the recipient does not have the required version of BBMinstalled on their BlackBerry device, the BBM platform takes the following action:

BBM version Action

6.0.0 and earlier 1. The recipient receives a download invitation to upgrade to BBM 6.0.1 orlater

2. After upgrading BBM, they receive a download invitation for yourapplication

3. After downloading your application, the content is sent when theapplication registers with the BBM platform at the recipient's end

6.0.1 without your applicationinstalled

1. The recipient receives a download invitation for your application

2. After downloading your application, the content is sent when theapplication registers with the BBM platform at the recipient's end

6.0.1 with your applicationinstalled and registered

1. The content is sent to your application

2. If your application is not running, a new item notification ( ) is applied toyour application's Home screen icon, and the recipient will receive themessage when your application is started up again

Share content with a user's BBM contactsThe net.rim.blackberry.api.bbm.platform.service.MessagingService class provides a method that allows yourapplication to share content with a user's BlackBerry Messenger contacts.

To share content, invoke shareContent() on the MessagingService object that is associated with yourapplication and pass in the content that you want to share (for example, a URL), a cookie that is associated withthe content, and a title that is displayed in the contact picker UI. By default, shareContent() displays thecontact picker with all the BBM contacts that have your application installed. You can use the ignoreListargument to provide a list of contacts that the user can choose to ignore.

// Retrieve the messaging service associated with your applicationMessagingService msgService = _platformContext.getMessagingService();

Development Guide Sharing content with BlackBerry Messenger contacts

34

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/service/MessagingService.html

String content = "<content to share>";String cookie = "<cookie>";

// Provide a list of contacts that the user can choose to ignore// or pass in null

BBMPlatformContactList igonoreList = new BBMPlatformContactList();ignoreList.add(pickContact());

msgService.shareContent(content, new BBMPlatformData(cookie), "Contact Picker Title", ignoreList);

// Create a list of contacts that have your app installed

public BBMPlatformContact pickContact(){ UIService uiService = _platformContext.getUIService(); BBMPlatformContactList bbmPlatformContactList = uiService.showContactPicker( "All Contacts", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false); BBMPlatformContact platformContact = null;

if (bbmPlatformContactList != null) { try { platformContact = (BBMPlatformContact) bbmPlatformContactList.getAll().nextElement(); } catch(NoSuchElementException e) { // Code that runs if no more elements exist } finally { return platformContact; } } else { return null; }}

Notifying a user about a share request when yourapplication is not runningYou can use the net.rim.blackberry.api.bbm.platform.BBMPlatformContext interface to notify a BlackBerry®device user that a request to share content was received while your application was not running. You canconfigure this behavior when you register your application with the BBM platform by overridingBBMPlatformApplication.getDefaultSettings() and returning SETTING_SHARECONTENT_SPLAT.

Development Guide Notifying a user about a share request when your application is not running

35

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/BBMPlatformContext.html

public int getDefaultSettings(){ return BBMPlatformContext.SETTING_SHARECONTENT_SPLAT;}

When the BBM platform receives a message fromMessagingServiceListener.onShareContentReceived(), a new item indicator ( ) is applied to yourapplication's Home screen icon to notify the user that a message is pending. When the user opens yourapplication, the BBM platform passes all queued messages to your application as soon as it registers theMessagingServiceListener with the platform.

Development Guide Notifying a user about a share request when your application is not running

36

Working with the user's profile and profile box 7

User profileYou can use the UserProfile class to access the current user's BlackBerry Messenger profile and retrieve orchange the user's display name, display picture, status, and personal message.

You can retrieve a reference to the current user's profile by invoking theBBMPlatformContext.getUserProfile() method.

The UserProfile class also provides retrieval methods for the current user's UserProfileBox andUserProfileLocation instances.

Retrieve the user's profileBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the MyUserProfileScreen screen passes in a reference tothe BBMPlatformContext object associated with your application.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.device.api.system.*;import java.util.*;


public class MyUserProfileScreen extends MainScreen{ public MyUserProfileScreen(BBMPlatformContext platformContext) {

}}

3. In the constructor, invoke BBMPlatformContext.getUserProfile() to retrieve a reference to theUserProfile object associated with this BBMPlatformContext. This returned instance is the current user'sprofile.

UserProfile userProfile = platformContext.getUserProfile();

4. In the constructor, retrieve the user's display name, display picture, status, status message, and personalmessage. Assign these values to the variables.

String displayName = userProfile.getDisplayName();Bitmap displayPicture = userProfile.getDisplayPicture();String personalMsg = userProfile.getPersonalMessage();int status = userProfile.getStatus();String statusMsg = userProfile.getStatusMessage();

Development Guide Working with the user's profile and profile box

37

Code sample: Retrieving the user's profile

The following code sample assumes that the class that displayed the MyUserProfileScreen has passed areference to the application's associated BBMPlatformContext object into the MyUserProfileScreenconstructor.

import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.device.api.ui.container.*;import java.util.*;

public class MyUserProfileScreen extends MainScreen { public MyUserProfileScreen(BBMPlatformContext platformContext) { UserProfile userProfile = platformContext.getUserProfile(); String displayName = userProfile.getDisplayName(); Bitmap displayPicture = userProfile.getDisplayPicture(); String personalMsg = userProfile.getPersonalMessage(); int status = userProfile.getStatus(); String statusMsg = userProfile.getStatusMessage(); }}

Update the user's profileBefore you begin: Make sure that you have registered your application with the BlackBerry Messenger platform,and that the class that displays the screen passes in a reference to the BBMPlatformContext object that isassociated with this application.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.device.api.system.*;import net.rim.device.api.ui.component.*;import java.util.*;

2. Create a class that extends MainScreen. In the constructor for this screen class, pass in theBBMPlatformContext object that is associated with this application.


}}

3. In the constructor, invoke BBMPlatformContext.getUserProfile() to retrieve a reference to theUserProfile object that is associated with BBMPlatformContext. The instance that is returned is the currentuser's profile.

Development Guide User profile

38


4. Invoke UserProfile.setStatus(), and pass in a status and message. A confirmation dialog is displayed whenyou invoke this method. The following code sample updates the user's status to busy. You can also update thepersonal message and display picture by invoking setPersonalMessage() and setDisplayPicture(),respectively.

boolean allowed = userProfile.setStatus(Presence.STATUS_BUSY, "I am busy.");

if(! allowed) { int result = Dialog.ask(Dialog.D_YES_NO, "Would you like CoolApp to stop updating your profile status?"); if(result == Dialog.YES) { // Optional code to prevent the application from asking to update the // user's status } }

Code sample: Updating the user's profile

The following code sample assumes that the class that displayed the MyUserProfileScreen has passed areference to the application's associated BBMPlatformContext object into the MyUserProfileScreenconstructor.


public class MyUserProfileScreen extends MainScreen { public MyUserProfileScreen(BBMPlatformContext platformContext) { UserProfile userProfile = platformContext.getUserProfile(); boolean allowed = userProfile.setStatus(Presence.STATUS_BUSY, "I am busy."); if(! allowed) { int result = Dialog.ask(Dialog.D_YES_NO, "Would you like CoolApp to stop updating your profile status?"); if(result == Dialog.YES) { // Optional code to prevent the application from asking to update // the user's status } } }

}

Development Guide User profile

39

User profile boxThe UserProfile class contains an enumerated set of UserProfileBoxItem objects. EachUserProfileBoxItem has an ID (a primary key), an icon, and some text. A UserProfileBoxItem can representanything from a display picture and character name within your game, to a badge signifying an accomplishment.

A user profile box is a list of items that are associated with the user and your application that the user can sharewith their BlackBerry Messenger contacts.

You can use the UserProfileBox class to add, remove, update, or retrieve the UserProfileBox object'sassociated UserProfileBoxItems.

Display the contents of the user's profile boxBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the MyUserProfileScreen screen passes in a reference tothe BBMPlatformContext object associated with the application.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.device.api.system.*;import net.rim.device.api.ui.component.*;import net.rim.device.api.util.*;import java.util.*;



}}

3. Invoke BBMPlatformContext.getUserProfile() to retrieve a reference to the UserProfile object thatis associated with this BBMPlatformContext. This instance is the current user's profile.

UserProfile userProfile = platformContext.getUserProfile();UserProfileBox userProfileBox = userProfile.getProfileBox();

4. Invoke userProfileBox.isAccessible() in an if statement to make sure that the profile box is accessible.

if (userProfileBox.isAccessible()){}

5. Invoke UserProfileBox.getItems() to retrieve all of the items in the profile box.

Development Guide User profile box

40

if (userProfileBox.isAccessible()){

UserProfileBoxItem[] items = userProfileBox.getItems();}

6. Iterate through the UserProfileBoxItem[]. For each UserProfileBoxItem, invoke Screen.add() todisplay a BitmapField and a LabelField containing the UserProfileItem object's icon and text.

if (userProfileBox.isAccessible()){ UserProfileBoxItem[] items = userProfileBox.getItems();

for(int i = 0; i < items.length; i++) { UserProfileBoxItem profileItem = items[i] Bitmap icon = userProfileBox.getIcon(profileItem.getIconId()); myScreen.add(new BitmapField(icon)); myScreen.add(new LabelField(profileItem.getText())); }}

Code sample: Displaying the contents of a user's profile box

The following code sample assumes that the class that displayed the MyUserProfileBoxScreen has passed areference to the application's associated BBMPlatformContext object into the MyUserProfileBoxScreenconstructor.

import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.device.api.system.*;import net.rim.device.api.ui.component.*;import net.rim.device.api.util.*;import java.util.*;

public class MyUserProfileBoxScreen extends MainScreen { public MyUserProfileBoxScreen(BBMPlatformContext platformContext) { UserProfile userProfile = platformContext.getUserProfile(); UserProfileBox userProfileBox = userProfile.getProfileBox(); if (userProfileBox.isAccessible()) { UserProfileBoxItem[] items = userProfileBox.getItems();

for(int i = 0; i < items.length; i++) { UserProfileBoxItem profileItem = items[i] Bitmap icon = userProfileBox.getIcon(profileItem.getIconId()); myScreen.add(new BitmapField(icon)); myScreen.add(new LabelField(profileItem.getText())); }


41

} }}

Add an item to the user's profile boxBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the MyUserProfileBoxScreen screen passes in a referenceto the BBMPlatformContext object that is associated with the application.




public class MyUserProfileBoxScreen extends MainScreen{ public MyUserProfileBoxScreen(BBMPlatformContext platformContext) {

}}

3. In the contructor, invoke BBMPlatformContext.getUserProfile() to retrieve a reference to theUserProfile object that is associated with this BBMPlatformContext. The returned instance is the currentuser's profile.


4. Invoke UserProfile.getProfileBox() to retrieve a reference to the UserProfileBox object that isassociated with this UserProfile.

UserProfileBox profileBox = userProfile.getProfileBox();if (profileBox.isAccessible()){

}

5. Register icons to be used in the profile box by invoking profileBox.registerIcon() for each icon. InvokeEncodedImage.getEncodedImageResource() to create an image object to use as the icon.

if (profileBox.isAccessible()){ UserProfileBox profileBox = userProfile.getProfileBox(); int iconId = 1;


42

EncodedImage icon = EncodedImage.getEncodedImageResource("myImg.jpg"); profileBox.registerIcon(iconId, icon);}

6. Invoke UserProfileBox.addItem() passing in the icon ID that you just registered and a String to add anitem to the profile box.

if (profileBox.isAccessible()){ UserProfileBox profileBox = userProfile.getProfileBox(); int iconId = 1; EncodedImage icon = EncodedImage.getEncodedImageResource("myImg.jpg"); profileBox.registerIcon(iconId, icon);

profileBox.addItem(iconId, "My message.");}

Code sample: Adding an item to the user's profile box



public class MyUserProfileBoxScreen extends MainScreen { public MyUserProfileBoxScreen(BBMPlatformContext platformContext) { UserProfile userProfile = platformContext.getUserProfile(); UserProfileBox profileBox = userProfile.getProfileBox();

if (profileBox.isAccessible()) { UserProfileBox profileBox = userProfile.getProfileBox(); int iconId = 1; EncodedImage icon = EncodedImage.getEncodedImageResource("myImg.jpg"); profileBox.registerIcon(iconId, icon);

profileBox.addItem(iconId, "My message."); } }}

Remove an item from the user's profile boxBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the MyUserProfileBoxScreen screen passes in a referenceto the BBMPlatformContext object that is associated with the application.


43


import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.device.api.system.*;net.rim.device.api.ui.component.*;import java.util.*;



}}

3. In the constructor, invoke BBMPlatformContext.getUserProfile() to retrieve a reference to theUserProfile object associated with this BBMPlatformContext. This instance is the current user's profile.


4. Invoke UserProfile.getProfileBox() to retrieve a reference to the UserProfileBox object that isasssociated with this UserProfile.

UserProfileBox profileBox = userProfile.getProfileBox();if (profileBox.isAccessible()){

}

5. Invoke UserProfileBox.removeItem() passing in the ID of the item to remove from the profile box. Thisexample removes the first item contained in the UserProfileBoxItem[] returned byUserProfileBox.getItems().

UserProfileBox profileBox = userProfile.getProfileBox();if (profileBox.isAccessible()){ int[] itemIds = profileBox.getItemIds(); if(itemIds.length >= 1) { profileBox.removeItem(itemIds[0]); }}

Code sample: Removing an item from the user's profile box



44

import net.rim.blackberry.api.bbm.platform.*;import net.rim.blackberry.api.bbm.platform.profile.*;import net.rim.device.api.system.*;net.rim.device.api.ui.component.*;import java.util.*;

public class MyUserProfileBoxScreen extends MainScreen { public MyUserProfileBoxScreen(BBMPlatformContext platformContext) { UserProfile userProfile = platformContext.getUserProfile();

UserProfileBox profileBox = userProfile.getProfileBox(); if (profileBox.isAccessible()) { int[] itemIds = profileBox.getItemIds(); if(itemIds.length >= 1) { profileBox.removeItem(itemIds[0]); } } }}

User profile locationYou can use the UserProfileLocation class to access the current user's country (through a country code and aflag icon) and time zone. These are set by the user in their BlackBerry Messenger profile.

To retrieve a reference to the UserProfileLocation that is associated with the current user, invoke theUserProfile.getUserProfileLocation() method.

Retrieve the user's locationBefore you begin: Make sure that you have completed the task, Register your application with the BlackBerryMessenger platform, and that the class that displays the MyUserProfileBoxScreen screen passes in a referenceto the BBMPlatformContext object associated with the application.





Development Guide User profile location

45

}}

3. In the constructor, invoke BBMPlatformContext.getUserProfile() to retrieve a reference to theUserProfile object that is associated with this BBMPlatformContext. The returned instance is the currentuser's profile.


4. In the constructor, invoke UserProfile.getUserProfileLocation() to retrieve a reference to theUserProfileLocation object asssociated with this UserProfile.

UserProfileLocation userProfileLocation = userProfile.getUserProfileLocation();

5. In the constructor, retrieve the user's country code, country flag icon, and timezone. Note that these fields areread-only.

String countryCode = userProfileLocation.getCountryCode();Bitmap countryIcon = userProfileLocation.getCountryIcon();TimeZone timeZone = userProfileLocation.getTimeZone();

Code sample: Retrieving the user's location



public class MyUserProfileBoxScreen extends MainScreen { public MyUserProfileBoxScreen(BBMPlatformContext platformContext) { UserProfile userProfile = platformContext.getUserProfile();

UserProfileLocation userProfileLocation = userProfile.getUserProfileLocation(); if(userProfileLocation != null) { String countryCode = userProfileLocation.getCountryCode(); Bitmap countryIcon = userProfileLocation.getCountryIcon(); TimeZone timeZone = userProfileLocation.getTimeZone(); } else { // User has not enabled location in profile } }}

Development Guide User profile location

46

Defining service listeners 8

Define a channel listenerThe following code sample assumes that you are creating this class as part of an application that requires achannel listener.


import net.rim.blackberry.api.bbm.platform.*;import net.rim.device.api.ui.*;import net.rim.device.api.ui.component.*;

2. Create the framework for the channel listener and define each callback method's signature. The following codesample displays a message that indicates what event has occured.

class MyChannelListener extends BBMPlatformChannelListener{ public void invitationAccepted(BBMPlatformConnection connection, BBMPlatformContact contact) { Dialog.inform(contact.getDisplayName() + " has accepted your invitation."); }

public void invitationDeclined(BBMPlatformConnection connection, String contactDisplayName) { Dialog.inform(contactDisplayName + " has declined your invitation."); } public void invitationFailed(BBMPlatformConnection connection, String inviteeName, int reasonCode) { Dialog.inform(inviteeName + " has failed to receive your invitation. Error: " + reasonCode); }

public void contactLeft(BBMPlatformConnection connection, BBMPlatformContact contact) { Dialog.inform(contact.getDisplayName() + " has left the application."); }

//NOTE: The message parameter is received as a data array. This method converts message to a String before displaying. public void dataReceived(BBMPlatformConnection connection, BBMPlatformContact fromContact, BBMPlatformData message) { Dialog.inform(fromContact.getDisplayName() + ": " + new String(message.getData())); }

//NOTE: param is a custom parameter defined by the application and passed in

Development Guide Defining service listeners

47

from the sender of the invitation public void invitationReceived(BBMPlatformConnection connection, BBMPlatformContact contact, String param) { Dialog.inform(contact.getDisplayName() + ": " + param); }

public void invitationsSent(BBMPlatformConnection connection, int count) { Dialog.inform("I've sent " + count + " invitations."); }

public void joinFailed(BBMPlatformConnection connection, BBMPlatformContact inviter, int reasonCode) { Dialog.inform("The user has failed to join the session. Error: " + reasonCode); } }

Define a messaging service listenerThe following code sample assumes that you are creating this class as part of an application that requires amessaging service listener.



2. Create the framework for the messaging service listener, defining each callback method's signature. Declare amember variable for the channel listener associated with this messaging service.

class MyMessagingServiceListener extends MessagingServiceListener{ public void channelCreated(BBMPlatformChannel channel, InvitationMenuItem menuItem) { //add any code for the channel's initialization here }

public BBMPlatformChannelListener(BBMPlatformChannel channel) { return _channelListener; }}

Development Guide Define a messaging service listener

48

Define a context change listenerThe following example assumes that you are creating a private inner class as part of an application that requires acontext change listener.



2. Create the framework for the context change service listener, defining the accessChanged() method. TheaccessErrorCode parameter is one of the fields from the BBMPlatformContext class (for example,ACCESS_BLOCKED_BY_IT_POLICY). The following code sample displays dialog boxes that informs the userwhat change has occurred.

class MyBBMPlatformContextListener extends BBMPlatformContextListener{ public void accessChanged(boolean isAccessAllowed, int accessErrorCode) { if(isAccessAllowed) { Dialog.inform("Access to the platform context is now allowed."); } else { Dialog.inform("Access to the platform context is now disallowed because of error:" + accessErrorCode); } } public void appInvoked(int reason, Object param) { /*code for handling different contexts for invocation:

<reason> is a constant in BBMPlatformApplication prepended with INVOKE, which tells you why this app was invoked and by whom <param> is an object representing a custom paramater with more information about the invocation context*/

}}

Define a session listenerThe following example assumes that you are creating this class as part of an application that requires a sessionlistener.


Development Guide Define a context change listener

49


2. Create the framework for the session listener, defining each callback method's signature, and implement themethod as required. The following code sample displays a dialog that informs the user of the change that hasoccured.

class MySessionListener extends BBMPlatformSessionListener { public void invitationAccepted(BBMPlatformConnection connection, BBMPlatformContact contact) { Dialog.inform(contact.getDisplayName() + " has accepted the session invitation "); } public void invitationDeclined(BBMPlatformConnection connection, String contactDisplayName) { Dialog.inform(contactDisplayName + " has declined the session invitation ")); } public void joinFailed(BBMPlatformConnection connection, BBMPlatformContact inviter, int reasonCode) { Dialog.inform(inviter.getDisplayName() + " has rejected the session join request due to the reason: " + Integer.toString(reasonCode)); } public void invitationFailed(BBMPlatformConnection connection, String inviteeName, int reasonCode) { Dialog.inform(inviteeName + "cannot accept the channel invite due to the reason: " + Integer.toString(reasonCode)); } public void contactsJoined(BBMPlatformSession session, BBMPlatformContactList contactList) { if (contactList != null) { Enumeration contacts = contactList.getAll(); while (contacts.hasMoreElements()) { BBMPlatformContact contact = (BBMPlatformContact)contacts.nextElement(); Dialog.inform(contact.getDisplayName() + " has joined the session."); } } } public void contactsRemoved(BBMPlatformSession session, BBMPlatformContact removedBy, BBMPlatformContactList contactList)

Development Guide Define a session listener

50

{ if (contactList != null) { Enumeration contacts = contactList.getAll(); while (contacts.hasMoreElements()) { BBMPlatformContact contact = (BBMPlatformContact)contacts.nextElement(); Dialog.inform(contact.getDisplayName() + " has been removed from the session by " + removedBy.getDisplayName()); } } } public void contactLeft(BBMPlatformConnection connection, BBMPlatformContact contact) { Dialog.inform(contact.getDisplayName() + " has left the session "); } public void dataReceived(BBMPlatformConnection connection, BBMPlatformContact fromContact, BBMPlatformData data) { Dialog.inform("session msg from:" + fromContact.getDisplayName() + " : " + data.getDataAsString())); } public void broadcastDataReceived(BBMPlatformSession session, BBMPlatformContact sender, BBMPlatformData data) { Dialog.inform("broadcasting msg from:" + sender.getDisplayName() + " > " + data.getDataAsString())); } public void invitationReceived(BBMPlatformConnection connection, BBMPlatformContact contact, String param) { Dialog.inform(contact.getDisplayName() + " is inviting me to join the session ")); }

public void invitationsSent(BBMPlatformConnection connection, int count) { Dialog.inform(count + " session invitation(s) sent")); } public void sessionEnded(BBMPlatformContact contact) { Dialog.inform(contact.getDisplayName() + " ends the session"); } public void joinRequestReceived(BBMPlatformConnection connection, BBMPlatformIncomingJoinRequest request, String param) { _incomingJoinRequest = request; Dialog.inform("Incoming Session Join request received from " +


51

request.getRequester().getDisplayName() + ". Please Accept or Decline",FOCUSABLE); } public void joinRequestCancelled(BBMPlatformConnection connection, BBMPlatformIncomingJoinRequest request, int reasonCode) { Dialog.inform("The join request has been cancelled by " + request.getRequester().getDisplayName() + " for reason: " + reasonCode,FOCUSABLE); } }


52

Managing your application's BlackBerryMessenger settings

9

Retrieving version information about your application andthe BlackBerry Messenger SDKThe net.rim.blackberry.api.bbm.platform.profile.UserProfile class provides methods that allow your application toquery the version of your application and the version of the BlackBerry Messenger SDK that is installed on a user'sBlackBerry device. You can also query net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact to obtainthe same information about the user's contacts. You can use this information to determine whether yourapplication is compatible between users.

To retrieve the version of your application that is installed on a user's BlackBerry device, invokegetAppVersion() on the userProfile object that represents the user's BBM profile.

String myTpaVersion = myUserProfile.getAppVersion();

To retrieve the version of your application that is installed by a user's contact, invoke getAppVersion() on aBBMPlatformContact object that represents the contact's BBM profile.

String tpaVersion = contact.getAppVersion();

// Use the application version information to determine the compatibility// of your application between users.

If (myTpaVersion > tpaVersion){ Dialog.alert("Unable to start game. Contact requires a newer version of the application.");)

To retrieve the version of the BlackBerry Messenger SDK that is installed on a user's BlackBerry device, invokegetBBMSDKVersion() on the userProfile object that represents the user's BBM profile.

int myBbmSdkVersion = userProfile.getBBMSDKVersion();

To retrieve the version of the BlackBerry Messenger SDK that is installed by a user's contact, invokegetBBMSDKVersion() on a BBMPlatformContact object that represents the contact's BBM profile.

int bbmSdkVersion = contact.getBBMSDKVersion();

// Use the SDK version information to determine BBM platform compatibility// between BlackBerry devices if (myBbmSdkVersion > bbmSdkVersion){ Dialog.alert ("Unable to share content. Contact requires a newer version of the BlackBerry Messenger SDK");}

Development Guide Managing your application's BlackBerry Messenger settings

53

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/profile/UserProfile.html

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/profile/BBMPlatformContact.html

Retrieving application menu items from a BlackBerrydeviceThe net.rim.blackberry.api.bbm.platform.ui.MenuItemManager class provides methods that allow yourapplication to retrieve the menu items that your application has added to a user's BlackBerry® device. Thenet.rim.blackberry.api.bbm.platform.ui.InvitationMenuItem class encapsulates a menu item's information, forexample, ID, order, label, and message.

To retrieve individual menu items, invoke MenuItemManager.getMenuItem() and pass in the menu item ID. Ifno menu item exists, the method returns null. To retrieve all menu items, invokeMenuItemManager.getMenuItems(), which returns an array of InvitationMenuItem[] items.

// Retrieve all menu items

InvitationMenuItem[] menuItems = _menuItemMgr.getMenuItems();

// Display the menu items

myScreen.add(new LabelField("The existing menu items are:"));

for(int i = 0; i < menuItems.length; i++){ myScreen.add(new LabelField(menuItems[i].getId() + ": " + menuItems[i].getLabel()));}

if (menuItems.length = 0){ myScreen.add(new LabelField("There are no menu items to display."));}

Retrieving the profile box settings for your applicationThe net.rim.blackberry.api.bbm.platform.SettingsManager class allows your application to obtain a user's settingfor the profile box for your application. For example, you can determine whether your application's profile box isenabled or disabled.

To obtain the status of the profile box for your application, you must first obtain your application'sSettingsManager object by invoking getSettingsManager() on your application's BBMPlatformContextobject.

To determine the status of the profile box setting, invoke SettingsManager.getSetting() and specifySETTING_PROFILE_BOX as the field to return.

If the profile box for your application is disabled, you can prompt the user to enable your application's profile boxby invoking requestAppSettings() on your application's BBMPlatformContext object.

Development Guide Retrieving application menu items from a BlackBerry device

54

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/ui/MenuItemManager.html

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/ui/InvitationMenuItem.html

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/SettingsManager.html

private static void alertIfNotShowingProfile(){ // Obtain the value of the profile box setting

final SettingsManager settingsMgr = context.getSettingsManager(); final int profileBoxSetting = settingsMgr.getSetting (SettingsManager.SETTING_PROFILE_BOX);

// If the setting is disabled, ask the user to change the setting

if(profileBoxSetting == SettingsManager.VALUE_DISABLED) { if(Dialog.D_OK == Dialog.ask(Dialog.D_OK_CANCEL, "Would you like this application to appear in your profile?")) { // If the user agrees, prompt the user to go to the options screen

context.requestAppSettings(); } }}

Retrieving the public connections setting for yourapplicationThe net.rim.blackberry.api.bbm.platform.SettingsManager class provides a constant,SETTING_ALWAYS_ALLOW_PUBLIC_CONN, that allows your app to determine whether a user has chosen to beprompted before they make or join a public connection.

To retrieve this setting, you must first obtain your application's SettingsManager object by invokinggetSettingsManager() on your application's BBMPlatformContext object.

To determine the status of the public connections setting, invoke SettingsManager.getSetting() and specifySETTING_ALWAYS_ALLOW_PUBLIC_CONN as the field to return.

int value = SettingsManager.getSetting(SettingsManager.SETTING_ALWAYS_ALLOW_PUBLIC_CONN);

if(value == SettingsManager.VALUE_ENABLED){ // User will not be prompted}else if(value == SettingsManager.VALUE_PROMPT){ // User will be prompted}

Development Guide Retrieving the public connections setting for your application

55

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/SettingsManager.html

Prompting the user to change the BlackBerry Messengersettings for your applicationThe net.rim.blackberry.api.bbm.platform.BBMPlatformContext interface provides a method,requestAppSettings(), that allows your application to bring its BBM options screen to the foreground so thatthe user can adjust the settings for the application. This is useful when the application requires certain settings,such as a connection to BBM or to display a profile box in the user’s BBM profile.

// Prompt the user to enable the profile box setting

private static void alertIfNotShowingProfile() { // Retrieve the settings manager associated with the application final SettingsManager settings = context.getSettingsManager(); // Retrieve the profile box setting final int profileBoxSetting = settings.getSetting(SettingsManager.SETTING_PROFILE_BOX);

// If the profile box setting is disabled, ask the user to change the setting if(profileBoxSetting == SettingsManager.VALUE_DISABLED) { if(Dialog.D_OK == Dialog.ask(Dialog.D_OK_CANCEL, "You have not enabled this application to appear in your profile. Would you like to enable it?")) { // If the user agrees, bring up the BBM options screen try { context.requestAppSettings(); } catch(ControlledAccessException e) { // Code that runs when the BBM platform access status is not // ACCESS_ALLOWED or is ACCESS_BLOCKED_BY_USER } } }}

Obtaining information about how your application isinvoked from within BlackBerry MessengerYou can use BBMPlatformContextListener.appInvoked() to capture how your app was invoked fromwithin BlackBerry Messenger and to gather related data, such as the current user, contact, PPID, and profile boxitems. You can use this information to learn how the BBM features that are integrated into your app are beingused. For example, you might want to change the behavior of your app so that it opens in the context in which it istypically invoked, such as when displaying an achievement list in a user's profile box. It can also help you todetermine the importance of these features to your app.

Development Guide Prompting the user to change the BlackBerry Messenger settings for your application

56

http://www.blackberry.com/go/bbmapiref/net/rim/blackberry/api/bbm/platform/BBMPlatformContext.html

The following table shows the contextual information thatBBMPlatformContextListener.appInvoked(reason, param, user) can capture with each reasonconstant:

Reason constantApp is invokedwhen the currentuser clicks

Param User

INVOKE_PROFILE_BOX_ITEM A user's profile boxitem for theapplication

The UserProfileBoxItemthat was clicked

The user whoseprofile box item wasclicked (might be thecurrent user)

INVOKE_PROFILE_BOX A user's profile boxheader for theapplication

null The user whoseprofile box wasclicked (might be thecurrent user)

INVOKE_PERSONAL_MESSAGE The app's personalmessage link in acontact's profile

The personal message string(excluding the link to the app)

The contact whosepersonal messagelink was clicked

INVOKE_CHAT_MESSAGE The link to the appin a contact's chatmessage

null The contact whosechat message linkwas clicked

Let's take a look at a few scenarios

public appInvoked(final int reason, final Object param, final Presence user){ /* Scenario 1: The current user clicks a contact’s profile box header * for the app. */

if(reason == BBMPlatformContext.INVOKE_PROFILE_BOX) { int ppid = getPPID(user);

/* Add code to capture all the items in the current user's profile box * for the app, for example, activities and achievements) /* }

/* Scenario 2: The current user clicks a contact’s profile box item for the app. * The app can capture whose profile box was clicked, and the associated profile * box item. */

if(reason == BBMPlatformContext.INVOKE_PROFILE_BOX_ITEM) { Int ppid = getPPID(user); UserProfileBoxItem item = (UserProfileBoxItem) param;

// display the profile box item, for example, a game score

Development Guide Obtaining information about how your application is invoked from within BlackBerry Messenger

57

int score = Integer.parseInt(item.getCookie()); }

/* Scenario 3: The current user clicks a contact’s personal message link * in a contact's profile. The app can capture whose personal message * was clicked and the personal message (minus the app link).*/

if(reason == BBMPlatformContext.INVOKE_PERSONAL_MESSAGE)

{ int ppid = getPPID(user); String personalMessage = (String) param; }

/* Scenario 4: The current user clicks a contact’s chat message link * in a contact's chat message. The app can capture whose chat message * link was clicked.*/

if(reason == BBMPlatformContext.INVOKE_CHAT_MESSAGE) { int ppid = getPPID(user);

// Add code to start an activity with the contact }}

// A generic function to obtain a user's unique ID

public static int getPPID (Presence user){ if (user instanceof UserProfile) { // returns the current user's PPID return ((UserProfile) user).getPPID(); } else if(user instanceof BBMPlatformContact) { // returns the contact's PPID return ((BBMPlatformContact) user).getPPID(); }}

Development Guide Obtaining information about how your application is invoked from within BlackBerry Messenger

58

Troubleshooting 10

Cannot initialize AES-256: Did you install Unlimited StrengthJurisdiction Policy Files?Possible Cause

When you run the BlackBerry® MDS Simulator you might encounter this message if you install the UnlimitedStrength Jurisdiction Policy files in the wrong JRE directory.

Possible Solution

Install the Unlimited Strength Jurisdiction Policy files in the appropriate directory of the system JRE. The locationof the system JRE can be found in your system's PATH environment variable.

<MDS-CS_MDS>:<ERROR>:<Unknown packet destination:RIM_IM>Possible CauseYou might encounter this error when you send an invitation from one BlackBerry® Smartphone Simulator toanother if:• You are using a 64-bit version of the JRE• Your system's PATH environment variable references a 64-bit version of the JRE

Possible Solution

Verify that you are using a 32-bit version of the JRE.

Development Guide Troubleshooting

59

Provide feedback 11To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

Development Guide Provide feedback

60

http://www.blackberry.com/docsfeedback

Legal notice 12©2012 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, and relatedtrademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used inthe U.S. and countries around the world.

Java, JRE, and JDK are trademarks of Oracle America, Inc. All other trademarks are the property of their respectiveowners.

This documentation including all documentation incorporated by reference herein such as documentationprovided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "ASAVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by ResearchIn 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 proprietaryand confidential information and/or trade secrets, this documentation may describe some aspects of RIMtechnology in generalized terms. RIM reserves the right to periodically change information that is contained in thisdocumentation; however, RIM makes no commitment to provide any such changes, updates, enhancements, orother 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-partyweb 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 Productsand Services. The inclusion of a reference to Third Party Products and Services in this documentation does notimply 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 ORWARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLEQUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM ORA COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, ORPERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTYPRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTSTHAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OFIMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES ORCONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUTABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIREDTHE 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 BELIABLE 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 SERVICESREFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT,CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES,

Development Guide Legal notice

61

http://www.blackberry.com/go/docs

DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESSINTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSSOF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USEDIN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTSOR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OFCOVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOTSUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OFSUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHEROBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANYLIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OFTHE 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 FUNDAMENTALBREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDYCONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS,SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDINGAIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENTCONTRACTORS.

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 RIMHAVE 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 ensurethat your airtime service provider has agreed to support all of their features. Some airtime service providers mightnot offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service. Check with yourservice provider for availability, roaming arrangements, service plans and features. Installation or use of ThirdParty 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 solelyresponsible for determining whether to use Third Party Products and Services and if any third party licenses arerequired to do so. If required you are responsible for acquiring them. You should not install or use Third PartyProducts and Services until all necessary licenses have been acquired. Any Third Party Products and Services thatare provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" withno express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIMand RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shallbe governed by and subject to you agreeing to the terms of separate licenses and other agreements applicablethereto 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.


62

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIMapplicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTENAGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHERTHAN THIS DOCUMENTATION.

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada


63

blackberry messenger sdk development guide 1442041 1114041224 001 1.3 beta us

Documents