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

All Superinterfaces:

BBMPlatformConnection

public interface BBMPlatformSession

extends BBMPlatformConnection

When a session is created, a user can invite one or more BBM contacts to interact; also, any participant can further invite their BBM contacts to join to the session.
Each participant in a session is visible and available to all other participants for data sharing in the session, which is different from BBMPlatformChannel. Therefore, it's NOT necessary that every participant in the session is a BBM contact to other participants.
For example, if user_A created a session and invited user_B to join, and user_B further invited user_C, who is not user_A's BBM contact, to join, then user_A and user_C can see each other within the session even they are not a BBM contact to each other, and thus be able to share data to each other as well.

The Platform allows a user to send public data to all participants in a session via broadcastData(BBMPlatformData data).
In this case, the sender has no need to specify the data recipients and the data is supposed to be sent to all participants in the session.
For example, a session connection would be used for a multi-player game such as a poker game; all users in the session would see the poker table, and game data is sent to each player in the game as it occurs.

The Platform also allows a user to send private data to a specific session contact via BBMPlatformConnection.sendData(BBMPlatformData data, BBMPlatformContact contact) or a subset of the session contacts via BBMPlatformConnection.sendData(BBMPlatformData data, BBMPlatformContactList contactList), which is the same as the data sharing in BBMPlatformChannel.

Since:

BBM SDK 1.0

Method Summary

void	broadcastData(BBMPlatformData data) This API is used to broadcast public data to ALL contacts of this session.
void	end() This call will remove the session contact list and all pending invitations that the user has sent and received.
void	leave() This call will remove the session contact list and all pending sent invitations on the user's side only.
void	setListener(BBMPlatformSessionListener listener) This API is used to let an application set a BBMPlatformSessionListener for the session.

Methods inherited from interface net.rim.blackberry.api.bbm.platform.io.BBMPlatformConnection

add, getContactList, getId, getIncomingJoinRequests, getListener, getMaxContacts, getMaxCookieLength, getMaxDataSize, getMaxInvitationMessageLength, getPendingContactsCount, isPublic, remove, remove, removeAllContacts, sendData, sendData, sendInvitation, sendInvitation, setPrivate, setPublic

Method Detail

broadcastData

public void broadcastData(BBMPlatformData data)
                   throws DataOverflowException,
                          ContactUnreachableException

This API is used to broadcast public data to ALL contacts of this session.
Note that the Platform cannot guarantee all the packets will come in order, so applicaitons will have to make sure the sequence of events if needed.

In a BBMPlatformSession, broadcasting data is always public, so the reply data should go to everyone in the session. For example, when people are playing a Poker game together.
The recipient will receive the data via BBMPlatformSessionListener.broadcastDataReceived(BBMPlatformSession session, BBMPlatformContact sender, BBMPlatformData data).
If the application wants to send private data to a specific session contact or a subset of the session contacts, it should use BBMPlatformConnection.sendData(BBMPlatformData data, BBMPlatformContactList contactList) or BBMPlatformConnection.sendData(BBMPlatformData data, BBMPlatformContact contact)

Parameters:

data - The data that the user is sending.

Throws:

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

NullPointerException - if data is null or empty.

IllegalArgumentException - if data is larger than 60KB.

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

end

public void end()

This call will remove the session contact list and all pending invitations that the user has sent and received.
Therefore, after user ends the sssion, none of any existing participants can still be active in this session, which is different from what the leave() API does.
MessagingServiceListener.sessionEnded(BBMPlatformContact contact, BBMPlatformSession session) will be called on each of contacts that was in this session contact list.
The session instance will beome inactive after this call.
The session should not be used after the application calling this API on the session. Therefore, multiple calls of end() on the same session object is not allowed.

Throws:

IllegalStateException - on each subsequent call on the session after it has been ended.

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

See Also:

leave()

leave

public void leave()

This call will remove the session contact list and all pending sent invitations on the user's side only.
Pending received invitations are still remained so that the user can rejoin the session if he/she wants, as long as the invitation hasn't expired yet.
After user left the sssion, other existing participants can still be active in this session, which is different from what end() does. BBMPlatformConnectionListener.contactLeft(BBMPlatformConnection connection, BBMPlatformContact contact) will be called on each of the session participants.
After this call, the session instance will become inactive.
The session should not be used after the application calling this API on the session. Therefore, multiple calls of leave() on the same session object is not allowed.

Throws:

IllegalStateException - on each subsequent call on the session after the user has left it.

PersistentContentException - when Content Protection is enabled and device is locked.

Since:

BBM SDK 1.0

See Also:

end()

setListener

public void setListener(BBMPlatformSessionListener listener)

This API is used to let an application set a BBMPlatformSessionListener for the session.

Parameters:

listener - A BBMPlatformSessionListener that is supposed to associated the session.

Since:

BBM SDK 1.0