net.rim.blackberry.api.bbm.platform.io
Interface BBMPlatformConnectionListener

All Known Implementing Classes:

BBMPlatformSessionListener, BBMPlatformChannelListener

public interface BBMPlatformConnectionListener

The BBMPlatformConnectionListener is a base class of BBMPlatformChannelListener and BBMPlatformSessionListener. which provide callback methods for Connection events.
Note that the BBM Platform cannot guarantee all the packets will come in order, so applications will have to make sure the sequence of events if desired. An application should use BBMPlatformChannelListener or BBMPlatformSessionListener to listen to the events.

See Also:

MessagingService.createChannel(BBMPlatformChannelListener channelListener), MessagingServiceListener.getChannelListener(BBMPlatformChannel channel), MessagingService.createSession(BBMPlatformSessionListener sessionListener), MessagingServiceListener.getSessionListener(BBMPlatformSession session)

Field Summary

static int	CONTACT_INVITED_BY_ME Used in contactsJoined(BBMPlatformConnection connection, BBMPlatformContactList contactList, String cookie, int type) and called by the join invitation sender.
static int	CONTACT_INVITING_ME Used in contactsJoined(BBMPlatformConnection connection, BBMPlatformContactList contactList, String cookie, int type) and called by the join invitation receiver, i.e., the new contact who just joined.

Method Summary

void	contactDeclined(BBMPlatformConnection connection, BBMPlatformContact contact) This callback notifies the user when a contact whom the user invited has declined the join invitation.
void	contactLeft(BBMPlatformConnection connection, BBMPlatformContact contact) This callback notifies the user when a contact, who is in the same connection as the user, destroys a BBMPlatformChannel, or leaves or ends a BBMPlatformSession.
void	contactsInvited(BBMPlatformConnection connection, BBMPlatformContactList contactList) This callback notifies that the user has sent join invitations to some contacts.
void	contactsJoined(BBMPlatformConnection connection, BBMPlatformContactList contactList, String cookie, int type) This callback is used to notify the application when a contact joined a BBMPlatformChannel or BBMPlatformSession.
void	dataReceived(BBMPlatformConnection connection, BBMPlatformContact sender, BBMPlatformData data) This callback notifies the user when the user receives the data.
void	joinRequestCanceled(BBMPlatformConnection connection, BBMPlatformIncomingJoinRequest request, int reasonCode) This callback notifies the user that a join request he or she received previously has been canceled by the request sender, which can happen only if the request has not been accepted or declined by the user (i.e., the host) yet.
void	joinRequestReceived(BBMPlatformConnection connection, BBMPlatformIncomingJoinRequest request, String cookie) This callback notifies when the user, who is hosting a public connection, receives a join request from other people who are running the same application and attempting to connect with the user.

Field Detail

CONTACT_INVITED_BY_ME

public static final int CONTACT_INVITED_BY_ME

Used in contactsJoined(BBMPlatformConnection connection, BBMPlatformContactList contactList, String cookie, int type) and called by the join invitation sender. contactList will consist of the invitation receiver only.

Since:

BBM SDK 1.0

CONTACT_INVITING_ME

public static final int CONTACT_INVITING_ME

Used in contactsJoined(BBMPlatformConnection connection, BBMPlatformContactList contactList, String cookie, int type) and called by the join invitation receiver, i.e., the new contact who just joined. contactList will consist of the invitation sender only.

Since:

BBM SDK 1.0

Method Detail

contactDeclined

public void contactDeclined(BBMPlatformConnection connection,
                            BBMPlatformContact contact)

This callback notifies the user when a contact whom the user invited has declined the join invitation.

Parameters:

connection - The BBMPlatformChannel or BBMPlatformSession the contact has declined to join.

contact - The contact who declined to join.

Since:

BBM SDK 1.0

contactLeft

public void contactLeft(BBMPlatformConnection connection,
                        BBMPlatformContact contact)

This callback notifies the user when a contact, who is in the same connection as the user, destroys a BBMPlatformChannel, or leaves or ends a BBMPlatformSession. The contact who left the connection is also removed from the user's corresponding connection contact list.

Parameters:

connection - The connection where the contact has left.

contact - The contact who left the connection.

Since:

BBM SDK 1.0

See Also:

BBMPlatformChannel.destroy(), BBMPlatformSession.leave(), BBMPlatformSession.end()

contactsInvited

public void contactsInvited(BBMPlatformConnection connection,
                            BBMPlatformContactList contactList)

This callback notifies that the user has sent join invitations to some contacts.
It will not be called if the user sent download invitations.

Parameters:

connection - The connection from which the invitation was sent.

contactList - consists of the contacts who are invited via BBMPlatformConnection.sendInvitation(String inviteMessage, String cookie, long expiryTime).

Since:

BBM SDK 1.0

contactsJoined

public void contactsJoined(BBMPlatformConnection connection,
                           BBMPlatformContactList contactList,
                           String cookie,
                           int type)

This callback is used to notify the application when a contact joined a BBMPlatformChannel or BBMPlatformSession.
A contact can join a connection that the user has been in two ways: one requires the user and the contact are BBM contacts to each other while the alternative approach allows non-BBM contacts to be connected with each other, i.e., the user and the contact are not necessary in each other's BBM contact list.
1. The user can send a join invitation to the contact via BBMPlatformConnection.sendInvitation(String inviteMessage, String cookie, long expiryTime). After the contact accepts the invitation, they can be connected. This approach requires the contact be in the user's BBM contact list. In this case, this event will be called on the invitation sending side.
2. The user can host a public connection via BBMPlatformConnection.setPublic() so that the contact can send a join request via MessagingService.sendJoinRequest(int, String, String) to the user. After the user accepts the request, they can be connected. This approach does NOT require the contact be in the user's BBM contact list. In this case, this event will be called on the host side. On the request sender side, MessagingServiceListener.joinRequestAccepted(BBMPlatformOutgoingJoinRequest request, String cookie) will be called.

Parameters:

connection - The BBMPlatformChannel or BBMPlatformSession the contact has joined.

contactList - It consists of the contacts who have joined the connection.

cookie - A custom parameter defined by the application and passed from the invitation sending side.

type - It is used to differentiate the cases where this method gets called. It's one of these constants: CONTACT_INVITED_BY_ME, CONTACT_INVITING_ME, BBMPlatformSessionListener.CONTACT_INVITED_BY_OTHER and BBMPlatformSessionListener.CONTACT_JOINED_BEFORE_ME.

For example, in a BBMPlatformChannel, the new contact, who just joined, will be notified via channelListener.contactsJoined(channel, contactList, cookie, CONTACT_INVITING_ME) where contactList will consist of the invitation sender only.
Also, the invitation sender will be notified via channelListener.contactsJoined(channel, contactList, cookie, CONTACT_INVITED_BY_ME) where contactList will consist of the new contact only.

In a BBMPlatformSession, the new contact, who just joined, will firstly be notified via sessionListener.contactsJoined(channel, contactList, cookie, CONTACT_INVITING_ME) where contactList will consist of the invitation sender only; then be notified again via sessionListener.contactsJoined(channel, contactList, cookie, BBMPlatformSessionListener.CONTACT_JOINED_BEFORE_ME) where contactList will consist of other existing contacts in the session.
The invitation sender will be notified via sessionListener.contactsJoined(channel, contactList, cookie, CONTACT_INVITED_BY_ME) where contactList will consist of the new contact only.
Also other existing participants will be notified via sessionListener.contactsJoined(channel, contactList, cookie, BBMPlatformSessionListener.CONTACT_INVITED_BY_OTHER). where contactList will also consist of the new contact only.

Since:

BBM SDK 1.0

dataReceived

public void dataReceived(BBMPlatformConnection connection,
                         BBMPlatformContact sender,
                         BBMPlatformData data)

This callback notifies the user when the user receives the data.

Parameters:

connection - The connection through which the data is sent.

sender - The contact who sent the data.

data - The data that the user received.

Since:

BBM SDK 1.0

joinRequestCanceled

public void joinRequestCanceled(BBMPlatformConnection connection,
                                BBMPlatformIncomingJoinRequest request,
                                int reasonCode)

This callback notifies the user that a join request he or she received previously has been canceled by the request sender, which can happen only if the request has not been accepted or declined by the user (i.e., the host) yet.
A canceled request will also be removed from the user's pending queue, i.e, the user will not be able to accept or decline a request that has been canceled.
The request sender is supposed to cancel a join request that has been sent to the user via BBMPlatformOutgoingJoinRequest.cancel().

Parameters:

connection - The public connection the user is hosting.

request - The BBMPlatformIncomingJoinRequest that has been canceled.

reasonCode - It's defined in IOErrorCode to explain why the request is canceled.

Since:

BBM SDK 1.0

joinRequestReceived

public void joinRequestReceived(BBMPlatformConnection connection,
                                BBMPlatformIncomingJoinRequest request,
                                String cookie)

This callback notifies when the user, who is hosting a public connection, receives a join request from other people who are running the same application and attempting to connect with the user.
The request sender is supposed to send a join request to the user via MessagingService.sendJoinRequest(int, String, String)

Parameters:

connection - The public connection the user is hosting.

request - A BBMPlatformIncomingJoinRequest the user receives.

cookie - It is an optional parameter defined and sent by the request sending side. For example, it can be a game level.
The cookie can be null.

Since:

BBM SDK 1.0