blackberry.bbm.platform.io.Session

A connection to communicate with one or more peers, where the peers are aware of each other.

Peers may in turn invite other users, who are also visible to everyone in the session, whether or not they are contacts of the session originator.

For example, a session connection could be used for a multi-player game application such as a poker game. When all of the users in the session want to see the poker table, game data is sent to each player in the game as it occurs.

User A invites user B, and user B joins the session

session_invite1.png

User B invites user C, and user C joins the session

session_invite2.png

User C invites user D, and user D joins the session

session_invite3.png

Once a user has joined, they can send data to anyone in the session.


Supported Platform(s)

- BlackBerry OS 5.0+
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
broadcast Y Y Y       
end Y Y Y       
leave Y Y Y       
onbroadcastdata Y Y Y       
onended Y Y Y       
onusersremoved Y Y Y       

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.bbm.platform" /> Y Y Y       

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions

void broadcast (data : String)


Sends data to all users.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
data Object to be sent.

Throws
ContactUnreachableException If a user is unreachable, up to 50 packets will be queued, and on the 51st call this exception is thrown.
DataOverflowException If the application sends data at a rate greater than what the BBM Social Platform allows.
NullPointerException If data is null or empty.
IllegalArgumentException If data.length is larger than blackberry.bbm.platform.io.Connection.MAX_DATA_LENGTH.
PersistentContentException If Content Protection is enabled and the device is locked.

void end ()


Ends the connection for all participants.

All participants will be removed from joinedUsers. All pending invitations will be removed and pendingUsers will be set to 0.

onended will be called for all users currently in the connection.

The connection will become inactive for the current user, and should not be used again.


Supported Platforms
 - BlackBerry OS 5.0+


Throws
IllegalStateException if the current user has already ended the connection.

void leave ()


Removes the current user from the connection, but leaves it active for all other participants.

onUserLeft will be called for all other users currently in the connection.

The connection will become inactive for the current user, and should not be used again.


Supported Platforms
 - BlackBerry OS 5.0+


Throws
IllegalStateException if the current user has already left the connection.

Events

void onbroadcastdata (sender : blackberry.bbm.platform.users.BBMPlatformUser, data : String)


Invoked when broadcast data is received from a user.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
sender The user that sent the data.
data Data received.

void onended (user : blackberry.bbm.platform.users.BBMPlatformUser)


Invoked when the connection is ended by another user.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
user The user who ended the connection.

void onusersremoved (remover : blackberry.bbm.platform.users.BBMPlatformUser, users : blackberry.bbm.platform.users.BBMPlatformUser[])


Invoked when users are removed.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
remover The user who removed users.
users The removed users.
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:43 GMT-0500 (EST)