blackberry.bbm.platform.io.Connection
The base interface for all connections. See blackberry.bbm.platform.io.Channel and blackberry.bbm.platform.io.Session for more information on the respective connection types.
Supported Platform(s)
- BlackBerry OS 5.0+ |
API | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
add | Y | Y | Y | ||||
inviteContacts | Y | Y | Y | ||||
remove | Y | Y | Y | ||||
removeAll | Y | Y | Y | ||||
send | Y | Y | Y | ||||
id | Y | Y | Y | ||||
joinedUsers | Y | Y | Y | ||||
pendingUsersCount | Y | Y | Y | ||||
MAX_USERS | Y | Y | Y | ||||
MAX_COOKIE_LENGTH | Y | Y | Y | ||||
MAX_INVITE_MSG_LENGTH | Y | Y | Y | ||||
MAX_DATA_LENGTH | Y | Y | Y | ||||
ondata | Y | Y | Y | ||||
onuserdeclined | Y | Y | Y | ||||
onuserleft | Y | Y | Y | ||||
onusersinvited | Y | Y | Y | ||||
onusersjoined | 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 | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
<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 | add |
void | inviteContacts |
void | remove |
void | removeAll |
void | send |
Events
void | ondata |
void | onuserdeclined |
void | onuserleft |
void | onusersinvited |
void | onusersjoined |
Properties
Number | id |
blackberry.bbm.platform.users.BBMPlatformUser[] | joinedUsers |
Number | pendingUsersCount |
Constants
Number | MAX_USERS |
Number | MAX_COOKIE_LENGTH |
Number | MAX_INVITE_MSG_LENGTH |
Number | MAX_DATA_LENGTH |
Functions
void
add
(user : blackberry.bbm.platform.user.BBMPlatformUser, [cookie : String])
Adds a user, who has already joined a connection in this application, to this connection.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
user | The user to be added. |
cookie | A custom parameter provided by the third party application. |
Throws | |
---|---|
NullPointerException |
If user is null.
|
IllegalArgumentException |
If user is not connected with the current user in any existing connections in this application.
|
PersistentContentException | If Content Protection is enabled and the device is locked. |
void
inviteContacts
(inviteMessage : String, [options : Object])
Allows the user to invite contacts to join this connection.
A Contact Picker dialog appears and allows the user to select contacts to invite. Only contacts with the application will be shown in the Contact Picker.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
inviteMessage | Message shown in the invitation to users. |
options |
Options.
expiryTime: Delay until the invitation expires (ms). If not provided or <= 0 , the invitation will not expire.
cookie: A custom parameter provided by the third party application. e.g. The current game level. Max length of 128 characters. contacts: The contacts that will be shown. |
Throws | |
---|---|
IllegalStateException | If the connection is full. |
IllegalStateException | If the connection is inactive, which can happen if the user ends or leaves the connection. |
void
remove
(user : blackberry.bbm.platform.users.BBMPlatformUser | blackberry.bbm.platform.users.BBMPlatformUser[])
Removes a user from the connection.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
user | Single user, or an array of users, to remove from the connection. |
Throws | |
---|---|
NullPointerException |
If user is null.
|
IllegalArgumentException | If one of the users being removed does not belong to the connection. |
PersistentContentException | If Content Protection is enabled and the device is locked. |
Code Example:
|
|
void
removeAll
()
Removes all users from the connection.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Throws | |
---|---|
PersistentContentException | If Content Protection is enabled and the device is locked. |
void
send
(data : String, [users : blackberry.bbm.platform.users.BBMPlatformUser[]])
Sends data to all users on the connection or a subset. Data cannot be sent to users who have not joined.
Unreachable Users
If a user becomes unreachable, up to 50 packets (50 calls of send()
) will be queued. A ContactUnreachableException will be thrown on the 51st call.
If the user later becomes reachable, blackberry.bbm.platform.io.event:onuserreachable will be invoked with the now-reachable user.
The BBM Social Platform will continue to attempt to deliver the packets to an unreachable user for 24 hours. If the user does not become reachable within this time, the packets will expire, and blackberry.bbm.platform.io.event:ondataexpired will be invoked.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
data | Object to be sent. |
users | Data recipients. If not provided, data will be sent to all users on this connection. |
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.
|
IllegalArgumentException |
If users contains a user who has not joined this connection.
|
IllegalArgumentException |
If users.length > 24 .
|
PersistentContentException | If Content Protection is enabled and the device is locked. |
Code Example:
|
|
|
Events
void
ondata
(sender : blackberry.bbm.platform.users.BBMPlatformUser, data : String)
Invoked when data is received from a user.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
sender | User that sent the data. |
data | Data received. |
Code Example:
|
void
onuserdeclined
(user : blackberry.bbm.platform.users.BBMPlatformUser)
Invoked when a user declines an invitation.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
user | The user who declined. |
void
onuserleft
(user : blackberry.bbm.platform.users.BBMPlatformUser)
Invoked when a user leaves the connection.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
user | The user who left. |
void
onusersinvited
(users : blackberry.bbm.platform.io.BBMPlatformUser[])
Invoked when the user invites others to join the connection. This will not be called if the user invites others to download the application.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
users | The users who were invited. |
void
onusersjoined
(users : blackberry.bbm.platform.users.BBMPlatformUser[], type : String, cookie : String)
Invoked when users join the connection by accepting an invitation.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
users | The users who joined. |
type |
The way that users joined.
|
cookie |
The cookie that was sent with the invitation. undefined
if no cookie was sent.
|
Properties
readonly
Number
id
This connection's unique ID. Automatically set on connection creation.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
readonly
blackberry.bbm.platform.users.BBMPlatformUser[]
joinedUsers
Users who have joined the connection.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Constants
Number
MAX_USERS
= 24 users
The maximum number of users a connection can have, not including the current user.
Once the limit is reached, the platform will not allow the user to send more join invitations
and will not allow more users to join.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Number
MAX_COOKIE_LENGTH
= 128 characters
The maximum length of an invitation cookie.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |