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

java.lang.Object
  |
  +--net.rim.blackberry.api.bbm.platform.service.MessagingServiceListener

public abstract class MessagingServiceListener

extends Object

This class provides callback methods to handle messaging events such as connections being established or ended.

Constructor Summary

MessagingServiceListener()
Creates a new instance of a MessagingServiceListener.

Method Summary

abstract void	channelCreated(BBMPlatformChannel channel) Called when a new BBMPlatformChannel has been created.
abstract void	channelCreated(BBMPlatformChannel channel, int menuItemId) Called when a new channel has been created to send the invitation associated with a menu item.
abstract void	fileTransferFailed(String path, BBMPlatformContact contact, int reason) Called when after the application calls MessagingService.sendFile(net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact, java.lang.String, java.lang.String) and the file transfer fails for some reason.
abstract BBMPlatformChannelListener	getChannelListener(BBMPlatformChannel channel) Called when the BBM Platform needs to create a new channel on behalf of the application.
abstract BBMPlatformSessionListener	getSessionListener(BBMPlatformSession session) Called when the BBM Platform needs to create a new session on behalf of the application.
void	joinRequestAccepted(BBMPlatformOutgoingJoinRequest request, String cookie) Called to notify the application when a request sent by the user has been accepted by the host.
void	joinRequestDeclined(BBMPlatformOutgoingJoinRequest request, int reasonCode) Called to notify the application that a request sent by the user has been declined by the host.
void	onContactReachable(BBMPlatformContact contact) Called to notify an application that the contact is now reachable after the ContactUnreachableException was thrown.
void	onMessagesExpired(BBMPlatformContact contact, BBMPlatformData[] data) Called to notify an application about pending packets for the unreachable contact that have expired.
void	onShareContentReceived(BBMPlatformContact sender, String description, BBMPlatformData content, long timeStamp) Called when the content arrives at the recipient
abstract void	sessionCreated(BBMPlatformSession session) Called when a new BBMPlatformSession has been created.
abstract void	sessionEnded(BBMPlatformContact contact, BBMPlatformSession session) Called when a session is ended by the contact

Constructor Detail

MessagingServiceListener

public MessagingServiceListener()

Creates a new instance of a MessagingServiceListener.

Since:

BBM SDK 1.0

Method Detail

channelCreated

public abstract void channelCreated(BBMPlatformChannel channel)

Called when a new BBMPlatformChannel has been created.

Parameters:

channel - The channel that has been created.

Since:

BBM SDK 1.0

channelCreated

public abstract void channelCreated(BBMPlatformChannel channel,
                                    int menuItemId)

Called when a new channel has been created to send the invitation associated with a menu item.

Parameters:

channel - The channel that has been created.

menuItemId - id of the menu item which was invoked by the user

Since:

BBM SDK 1.0

fileTransferFailed

public abstract void fileTransferFailed(String path,
                                        BBMPlatformContact contact,
                                        int reason)

Called when after the application calls MessagingService.sendFile(net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact, java.lang.String, java.lang.String) and the file transfer fails for some reason.

Parameters:

path - Path of the file that is sent

contact - The recipient of the file if it is specified in MessagingService.sendFile(net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact, java.lang.String, java.lang.String), otherwise null

reason - The reason code for the failure, defined in IOErrorCode

Since:

BBM SDK 1.0

getChannelListener

public abstract BBMPlatformChannelListener getChannelListener(BBMPlatformChannel channel)

Called when the BBM Platform needs to create a new channel on behalf of the application. The application must return a valid BBMPlatformChannelListener for the channel to work properly.

If the application is not running when the user accepts an invitation to join a channel, the BBM Platform will launch the application, create the channel, and call this method to retrieve the BBMPlatformChannelListener and thus associate the listener with the channel that has been created.

Parameters:

channel - The BBMPlatformChannel that is created by the BBM platform.

Returns:

BBMPlatformChannelListener that will be associated with the channel.

Since:

BBM SDK 1.0

getSessionListener

public abstract BBMPlatformSessionListener getSessionListener(BBMPlatformSession session)

Called when the BBM Platform needs to create a new session on behalf of the application. The application must return a valid BBMPlatformSessionListener for the session to work properly.

If the application is not running when the user accepts an invitation to join a session, the BBM Platform will launch the application, create the session, and call this method to retrieve the BBMPlatformSessionListener and thus associate the listener with the session that has been created.

Parameters:

session - The BBMPlatformSession that is created by the BBM platform.

Returns:

BBMPlatformSessionListener that will be associated with the session.

Since:

BBM SDK 1.0

joinRequestAccepted

public void joinRequestAccepted(BBMPlatformOutgoingJoinRequest request,
                                String cookie)

Called to notify the application when a request sent by the user has been accepted by the host.

An application user can host an event within a public channel or session to let all application users join, for example, a poker game. The application can post the host's and the event's information via its own discovery service so that other users can discover the information and can send requests to these hosts in order to join their events.

Parameters:

request - The join request that has been accepted by the host.

cookie - It's an optional parameter that was defined and sent by the host to provide additional information to the request sender.

Since:

BBM SDK 1.0

joinRequestDeclined

public void joinRequestDeclined(BBMPlatformOutgoingJoinRequest request,
                                int reasonCode)

Called to notify the application that a request sent by the user has been declined by the host.

An application user can host an event within a public channel or session to let all application users join, for example, a poker game. The application can post the host's and the public event's information via its own discovery service so that other users can discover the information and can send requests to these hosts in order to join their events.

Parameters:

request - The join request that has been declined by the host.

reasonCode - The reason code for declining, defined in IOErrorCode

Since:

BBM SDK 1.0

onContactReachable

public void onContactReachable(BBMPlatformContact contact)

Called to notify an application that the contact is now reachable after the ContactUnreachableException was thrown.

Parameters:

contact - The platform contact that has come out of unreachable state.

Since:

BBM SDK 1.0

onMessagesExpired

public void onMessagesExpired(BBMPlatformContact contact,
                              BBMPlatformData[] data)

Called to notify an application about pending packets for the unreachable contact that have expired.

Parameters:

contact - The BBMPlatformContact whose pending messages got expired.

data - The array of pending BBMPlatformData that got expired.

Since:

BBM SDK 1.0

onShareContentReceived

public void onShareContentReceived(BBMPlatformContact sender,
                                   String description,
                                   BBMPlatformData content,
                                   long timeStamp)

Called when the content arrives at the recipient

Parameters:

sender - contact who sent the content

description - the description for this content

content - the actual content

time - stamp the time stamp when this message was received

Since:

BBM SDK 1.2

See Also:

MessagingService.shareContent(java.lang.String, net.rim.blackberry.api.bbm.platform.io.BBMPlatformData, java.lang.String, net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContactList)

sessionCreated

public abstract void sessionCreated(BBMPlatformSession session)

Called when a new BBMPlatformSession has been created.

Parameters:

session - The session that has been created.

Since:

BBM SDK 1.0

sessionEnded

public abstract void sessionEnded(BBMPlatformContact contact,
                                  BBMPlatformSession session)

Called when a session is ended by the contact

Parameters:

contact - The participant who ends the session, a null value implies this participant is not on the user's BBM contact list.

session - The session being ended

Since:

BBM SDK 1.0