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+
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
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 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 add
void inviteContacts
void remove
void removeAll
void send

Events



Constants

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:
<script type="text/javascript">

// Remove the first user in a connection
var users = conn.joinedUsers;
if(users.length > 0) {
    conn.remove(conn.joinedUsers[0])
}

</script>
<script type="text/javascript">

// Remove all users in a connection
var users = conn.joinedUsers;
if(users.length > 0) {
    conn.remove(conn.joinedUsers)
}

</script>

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:
<script type="text/javascript">

// Send message to all users
var replyText = ""; // Obtain reply text from user...
var msgObj = {
    id:'msg',
    value:replyText
};
try {
    connnection1.send(JSON.stringify(msgObj));
} catch(e) {
    // Error occurred while sending data
}

</script>
<script type="text/javascript">

// Ping all users
var pingObj = { id:'ping' };
try {
    connection1.send(JSON.stringify(pingObj));
} catch(e) {
    // Error occurred while sending data
}

</script>
<script type="text/javascript">

// Send high score to all users
var highScoreObj = {
    id: 'highscore',
    score: 9000,
    hits: 130,
    misses: 40
};
try {
    connection1.send(JSON.stringify(highScoreObj));
} catch(e) {
    // Error occurred while sending data
}

</script>

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:
<script type="text/javascript">

connection1.ondata = function(user, data) {
    var dataObj = JSON.parse(data);
    var dataID = dataObj.id;

    // Handle application-defined data types
    if(dataID == "msg") {
        // Handle msg type
    } else if(dataID == "ping") {
        // Handle ping type
    } else if(dataID == "highscore") {
        // Handle highscore type
    }
};

</script>

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.
  • "invitedbyme": The joining users were invited by the current user.
  • "acceptedbyme": The current user is joining the connection.
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+

readonly Number pendingUsersCount


The number of invited users who have not yet 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+

Number MAX_INVITE_MSG_LENGTH = 128 characters


The maximum length of an invitation message.


Supported Platforms
 - BlackBerry OS 5.0+

Number MAX_DATA_LENGTH = 61440 characters


The maximum length of a data payload.


Supported Platforms
 - BlackBerry OS 5.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:04 GMT-0500 (EST)