Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Developing a BBM connected app

Key classes of the BlackBerry Messenger platform

The following table describes the key classes of the BlackBerry Messenger platform.

Class

Description

BBMPlatformContext

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

The BlackBerry Messenger platform returns a BBMPlatformContext instance when your application registers with the BlackBerry Messenger platform.

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

MessagingService

The MessagingService class allows you to create a BBMPlatformChannel or BBMPlatformSession instance, invite contacts to download your application, or send a file to a BlackBerry Messenger contact.

To receive notifications of events related to the messaging service, you must extend the abstract class, MessagingServiceListener, override its callback methods, and invoke the MessagingService.setServiceListener() method.

To retrieve a reference to the MessagingService that is associated with your application, invoke BBMPlatformContext.getMessagingService().

BBMPlatformChannel

The BBMPlatformChannel interface represents a private connection between your application and one or more contacts. If your application is communicating with multiple contacts, the contacts are not aware of each other. Consequently, the contacts can only communicate with your application, not each other.

You can invoke BBMPlatformConnection.setPublic() to set your channel to allow connections from contacts not on your BlackBerry Messenger contact list.

To receive notifications of events and changes to the channel, you must extend the BBMPlatformChannelListener class and override the callback methods inherited from the BBMPlatformConnectionListener class.

To create an instance of BBMPlatformChannel, invoke MessagingService.createChannel(), passing in a reference to a BBMPlatformChannelListener instance.

BBMPlatformSession

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

You can invoke BBMPlatformConnection.setPublic() to set your session to allow connections from contacts not on your BlackBerry Messenger contact list.

To receive notifications of events and changes to the session, you must extend the BBMPlatformSessionListener class and override its callback methods and the callback methods inherited from the BBMPlatformConnectionListener class.

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

ContactListService

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

To receive notifications of changes to contacts in the contact list, you must implement the interface, PresenceListener. PresenceListener contains one callback method, presenceUpdated(), which is called when one 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, invoke ContactListService.setListener(PresenceListener).

UIService

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

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

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 using your BlackBerry Messenger connected application.

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

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