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



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.