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

All Superinterfaces:

BBMPlatformConnection

public interface BBMPlatformChannel

extends BBMPlatformConnection

When a channel is created, the user can invite one or more BBM contacts to interact. also, any participant can further invite their BBM contacts to join to the channel.
Note that a person in a channel is visible and available to only those whom this person invited or who invited this person, which is different from BBMPlatformSession.
For example, if user_A invited user_B to a channel and user_B joined, then user_B invited user_C to join to the same channel and user_C joined.
In this case, user_A sees user_B only and thus can share data with user_B only. So does user_C since he/she was invited by user_B.
User_B can see both user_A and user_C in this channel and thus can share data with both of them.
But user_A and user_C are not visible to each other and thus cannot share data with each other.

All data sent within a channel is always private, i.e., the sender must specify who is going to receive the data and thus only that recipient will see it. Private data can be sent to a specific channel contact via BBMPlatformConnection.sendData(BBMPlatformData data, BBMPlatformContact contact) or a subset of the channel contacts via BBMPlatformConnection.sendData(BBMPlatformData data, BBMPlatformContactList contactList).
Location sharing is one use case.

Method Summary

void	destroy() This API should be used when user leaves the channel.
void	setListener(BBMPlatformChannelListener listener) This API allows an application to set the BBMPlatformChannelListener for a channel.

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

destroy

public void destroy()

This API should be used when user leaves the channel.
Calling this API will remove the user's channel contact list and all pending invitations that the user sent from this channel. Therefore, contactLeft() will be called in BBMPlatformChannelListener on each of the contacts that was in the user's channel contact list.
However, pending incoming invitations, sent from other BBM contacts to the user, won't be removed, which allows the user to re-join the channel in the future as long as the invitation hasn't expired.
The channel should not be used after the application calling destroy() on it. Therefore, multiple calls of destroy() on the same channel object is not allowed.

Throws:

IllegalStateException - on each subsequent call on the channel after it has been destroyed.

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

Since:

BBM SDK 1.0

setListener

public void setListener(BBMPlatformChannelListener listener)

This API allows an application to set the BBMPlatformChannelListener for a channel.

Parameters:

listener - a BBMPlatformChannelListener that is supposed to associate with the channel.

Throws:

NullPointerException - if listener is null. The Platform allows each channel to have its own listener or to use an existing listener shared with other channels.

Since:

BBM SDK 1.0