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 the users in the session want to see the poker table, and game data is sent to each player in the game as it occurs.
User A invites user B, and user B joins the sessionUser B invites user C, and user C joins the session
User C invites user D, and user D joins the session
Once a user has joined they can send data to anyone in the session.
Supported Platform(s)
- BlackBerry OS 5.0+
| API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| 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 ID | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| <feature id="blackberry.bbm.platform" /> | Y | Y | Y |
| Permission Elements (PlayBook Only) |
|---|
| This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
API Summary
Functions
- Functions inherited from class blackberry.bbm.platform.io.Connection:
- add inviteContacts remove removeAll send
Events
- Events inherited from class blackberry.bbm.platform.io.Connection:
- ondata onuserdeclined onuserleft onusersinvited onusersjoined
Properties
- Properties inherited from class blackberry.bbm.platform.io.Connection:
- id joinedUsers pendingUsersCount
Constants
- Constants inherited from class blackberry.bbm.platform.io.Connection:
- MAX_COOKIE_LENGTH MAX_DATA_LENGTH MAX_INVITE_MSG_LENGTH MAX_USERS
broadcast
| void broadcast(data : String) |
Supported Platform(s)
- BlackBerry OS 5.0+Description
Sends data to all users.
| Parameter | Type | Description |
|---|---|---|
| data | String | Object to be sent. |
| Throws | Description |
|---|---|
| ContactUnreachableException | If a user is unreachable, up to 50 packets will be queued. This will be thrown on the 51st call. |
| DataOverflowException | If the rate of data sent by the application exceeds that which the BBM 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 device is locked. |
end
| void end() |
Supported Platform(s)
- BlackBerry OS 5.0+Description
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 afterwards.
| Throws | Description |
|---|---|
| IllegalStateException | if the current user has already ended the connection. |
leave
| void leave() |
Supported Platform(s)
- BlackBerry OS 5.0+Description
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 afterwards.
| Throws | Description |
|---|---|
| IllegalStateException | if the current user has already left the connection. |
onbroadcastdata
| void onbroadcastdata(sender : blackberry.bbm.platform.users.BBMPlatformUser, data : String) |
Supported Platform(s)
- BlackBerry OS 5.0+Description
Invoked when broadcast data is received from a user.
| Parameter | Type | Description |
|---|---|---|
| sender | blackberry.bbm.platform.users.BBMPlatformUser | User that sent the data. |
| data | String | Data received. |
onended
| void onended(user : blackberry.bbm.platform.users.BBMPlatformUser) |
Supported Platform(s)
- BlackBerry OS 5.0+Description
Invoked when the connection is ended by another user.
| Parameter | Type | Description |
|---|---|---|
| user | blackberry.bbm.platform.users.BBMPlatformUser | The user who ended the connection. |
onusersremoved
| void onusersremoved(remover : blackberry.bbm.platform.users.BBMPlatformUser, users : blackberry.bbm.platform.users.BBMPlatformUser[]) |
Supported Platform(s)
- BlackBerry OS 5.0+Description
Invoked when users are removed.
| Parameter | Type | Description |
|---|---|---|
| remover | blackberry.bbm.platform.users.BBMPlatformUser |
The user who removed users.
|
| users | blackberry.bbm.platform.users.BBMPlatformUser[] | The removed users. |