net.rim.blackberry.api.bbm.platform.service
Class MessagingService

java.lang.Object
  |
  +--net.rim.blackberry.api.bbm.platform.Plugin
        |
        +--net.rim.blackberry.api.bbm.platform.service.Service
              |
              +--net.rim.blackberry.api.bbm.platform.service.MessagingService

public abstract class MessagingService
extends Service

This class provides methods to success the BBM messaging service and to send invitations and files.

Since:
BBM SDK 1.0

 
Method Summary
abstract  BBMPlatformChannel createChannel(BBMPlatformChannelListener channelListener)
          Creates a BBMPlatformChannel.
abstract  BBMPlatformSession createSession(BBMPlatformSessionListener sessionListener)
          Creates a BBMPlatformSession.
abstract  Enumeration getOutgoingJoinRequests()
          Retrieves all the pending join requests the user has sent but haven't been accepted or declined by the hosts.
abstract  int sendDownloadInvitation()
          Invites contacts of the user to download an application.
abstract  void sendFile(BBMPlatformContact contact, String path, String comment)
          Sends a file to a contact.
abstract  void sendFile(String path, String comment)
          Sends a file to a contact that the user will pick from the Contact Picker.
abstract  BBMPlatformOutgoingJoinRequest sendJoinRequest(int hostPin, String hostPPID, String cookie)
          Sends a join request to a person who is running the same third-party application and is hosting a public connection that is available for other application users to join.
abstract  void setServiceListener(MessagingServiceListener messagingServiceListener)
          Sets the messaging service listener.
abstract  void shareContent(String description, BBMPlatformData content, ContactListProvider clProvider, String contactPickerTitle)
          Shares content with the recipient.
abstract  void shareContent(String description, BBMPlatformData content, String contactPickerTitle, BBMPlatformContactList ignoreList)
          Shares content with the recipient.
 
Methods inherited from class net.rim.blackberry.api.bbm.platform.Plugin
getName
 

Method Detail

createChannel

public abstract BBMPlatformChannel createChannel(BBMPlatformChannelListener channelListener)
Creates a BBMPlatformChannel.
Parameters:
channelListener - A BBMPlatformChannelListener is always required for the channel being created.
Returns:
A BBMPlatformChannel if the channel listener is set as required.
Throws:
NullPointerException - if channelListener is null.
Since:
BBM SDK 1.0

createSession

public abstract BBMPlatformSession createSession(BBMPlatformSessionListener sessionListener)
Creates a BBMPlatformSession.
Parameters:
sessionListener - A BBMPlatformSessionListener is always required for the session being created.
Returns:
A BBMPlatformSession if the session listener is set as required.
Throws:
NullPointerException - if sessionListener is null.
Since:
BBM SDK 1.0

getOutgoingJoinRequests

public abstract Enumeration getOutgoingJoinRequests()

Retrieves all the pending join requests the user has sent but haven't been accepted or declined by the hosts.

Globally there can be multiple public connections hosted by different people running the same application, so the user can have multiple join requests which were sent to different public connections and different hosts.

The user can cancel a request even if it has been sent to a host as long as the request hasn't been accepted or declined. Once a request has been accepted, or declined, or canceled, it will be removed from the pending queue on both the request sender side and the host side.

Returns:
Returns the enumeration of all pending join requests the user has sent, which can be null.


The type of each object the Enumeration contains is BBMPlatformOutgoingJoinRequest.
Since:
BBM SDK 1.0

sendDownloadInvitation

public abstract int sendDownloadInvitation()

Invites contacts of the user to download an application.

The Contact Picker will pop up for the user to select contacts to be invited. Only the contacts who haven't installed the application will be displayed on the Contact Picker.

Returns:
A result code which is specified by IOErrorCode. For example, IOErrorCode.DOWNLOAD_INVITATION_LIMIT_REACHED will be returned if the download invitation limit per minute is reached. The Platform allows up to 10 download invitations per minute.
Since:
BBM SDK 1.0

sendFile

public abstract void sendFile(BBMPlatformContact contact,
                              String path,
                              String comment)
Sends a file to a contact. The contact must be in the contact list of the user. The user will be prompted to edit the comment and choose to send or cancel the file transfer. If the contact cannot receive the specific file type, the file will not be sent. The application is notified of any errors that occur through MessagingServiceListener.fileTransferFailed(java.lang.String, net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact, int). The call is non-blocking.
Parameters:
contact - Recipient of the file
path - Path of the file
comment - Default comment of the file
Throws:
NullPointerException - if either contact or path is null
Since:
BBM SDK 1.0

sendFile

public abstract void sendFile(String path,
                              String comment)
Sends a file to a contact that the user will pick from the Contact Picker. The user will be prompted to edit the comment and choose to send or cancel the file transfer. If the contact cannot receive the specific file type, the file will not be sent. The application is notified of any errors that occur through MessagingServiceListener.fileTransferFailed(java.lang.String, net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact, int). The call is non-blocking.
Parameters:
path - path of the file
comment - default comment of the file
Throws:
NullPointerException - if path is null
Since:
BBM SDK 1.0

sendJoinRequest

public abstract BBMPlatformOutgoingJoinRequest sendJoinRequest(int hostPin,
                                                               String hostPPID,
                                                               String cookie)

Sends a join request to a person who is running the same third-party application and is hosting a public connection that is available for other application users to join.

The host may or may not be a BBM contact of the user. Once the host accepts the join request, the user and the host will be able to communicate within the public connection.

There will be a confirmation dialog when this method gets called, so the method blocks until the dialog is dismissed by the user.

Parameters:
hostPin - The pin of the host which can be obtained via net.rim.device.api.system.DeviceInfo#getDeviceId(). hostPin must be positive. Also, if the application is running on BlackBerry Simulator, make sure the pin of the Simulator is no larger than 0x7FFFFFFF.
hostPPID - The PPID of the host. PPID is used to uniquely identify each application user.
cookie - An optional information an application can send along the join request based on their needs. For example, the cookie can be the user's current game level. The cookie parameter can be null.
Returns:
BBMPlatformOutgoingJoinRequest if the request gets sent to the host successfully.
Throws:
IllegalStateException - if the request sender has connected with the host in a connection but still attempts to send another join request to the host.
IllegalArgumentException - if hostPin is zero or negative.
IllegalArgumentException - if hostPPID is invalid.
IllegalArgumentException - if cookie is longer than 128 characters.
Since:
BBM SDK 1.0

setServiceListener

public abstract void setServiceListener(MessagingServiceListener messagingServiceListener)

Sets the messaging service listener.

In order to use the BBM messaging service, an application has to provide the messaging service listener when it registers with the BBM Platform.

Parameters:
messagingServiceListener - It listens to the events related to connection status change.
For example, a new connection is created by the Platform, or an existing connection is ended. The connection created or ended can be a BBMPlatformChannel or BBMPlatformSession.
Throws:
NullPointerException - if messagingServiceListener is null.
Since:
BBM SDK 1.0

shareContent

public abstract void shareContent(String description,
                                  BBMPlatformData content,
                                  ContactListProvider clProvider,
                                  String contactPickerTitle)

Shares content with the recipient. The contact picker will pop up to allow the user to select the recipient. The content will not appear in BBM but received by the application. On the recipient side, the callback MessagingServiceListener.onShareContentReceived(net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact, java.lang.String, net.rim.blackberry.api.bbm.platform.io.BBMPlatformData, long) will be invoked.

The recipient may or may not currently have the application installed. In the latter case, the content is saved on the device of the recipient. Once the application is installed, the callback in MessagingServiceListener will be invoked.

If the recipient does not have the required version of BBM installed, the recipient will receive a message in BBM asking for BBM upgrade. If eventually the recipient installs the application, the application will receive the content.

Parameters:
description - The description of the content.
content - The content to be shared.
clProvider - It allows an application to define the type of contact list that needs to be shown in the contact picker. If clProvider is null, the Contact Picker will be shown with the default setting.
contactPickerTitle - The title to be shown on the contact picker.
Throws:
IllegalArgumentException - if description is null or more than 128 characters
IllegalArgumentException - if content is null or too large
DataOverflowException - if the rate of data sent by the application exceeds that which the BBM Platform allows.
ContactUnreachableException - if pending data for an unreachable contact in the destination has exceeded the buffer limit set by the BBM Platform.
Since:
BBM SDK 1.2

shareContent

public abstract void shareContent(String description,
                                  BBMPlatformData content,
                                  String contactPickerTitle,
                                  BBMPlatformContactList ignoreList)

Shares content with the recipient. The contact picker will pop up to allow the user to select the recipient. The content will not appear in BBM but received by the application.

On the recipient side, the callback MessagingServiceListener.onShareContentReceived(net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact, java.lang.String, net.rim.blackberry.api.bbm.platform.io.BBMPlatformData, long) will be invoked.

The recipient may or may not currently have the application installed. In the latter case, the content is saved on the device of the recipient. Once the application is installed, the callback in MessagingServiceListener will be invoked.

If the recipient does not have the required version of BBM installed, the recipient will receive a message in BBM asking for BBM upgrade. If eventually the recipient installs the application, the application will receive the content.

Parameters:
description - The description of the content.
content - The content to be shared.
contactPickerTitle - The title to be shown on the contact picker.
ignoreList - The list of contacts not to be shown on the contact picker. If null is used, all contacts will appear in the contact picker.
Throws:
IllegalArgumentException - if description is null or more than 128 characters
IllegalArgumentException - if content is null or too large
DataOverflowException - if the rate of data sent by the application exceeds that which the BBM Platform allows.
ContactUnreachableException - if pending data for an unreachable contact in the destination has exceeded the buffer limit set by the BBM Platform.
Since:
BBM SDK 1.2



Copyright 1999- Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.