blackberry.bbm.platform.io.Connection

- BlackBerry OS 5.0+

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

add

---

void add(user : blackberry.bbm.platform.user.BBMPlatformUser, [cookie: String])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Adds a user, who has already joined a connection in this application, to this connection.

Parameter	Type	Description
user	blackberry.bbm.platform.user.BBMPlatformUser	The user to be added.
cookie	String Optional	A custom parameter provided by the third party application.

Throws	Description
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 device is locked.

inviteContacts

---

void inviteContacts(inviteMessage : String, [options: Object])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Allows the user to invite contacts to join this connection.

A Contact Picker dialog will appear allowing the user to select contacts to invite. Only contacts with the application will be shown in the Contact Picker.

Parameter	Type	Description
inviteMessage	String	Message shown to user in invitation.
options	Object Optional	Options. expiryTime: Delay until the invitation expires (ms). If not provided or <= 0, then invitation will never 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	Description
IllegalStateException	If the connection is full.
IllegalStateException	If the connection is inactive, which can happen if the user ends or leaves the connection.

remove

---

void remove(user : blackberry.bbm.platform.users.BBMPlatformUser | blackberry.bbm.platform.users.BBMPlatformUser[])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Removes a user from the connection.

Parameter	Type	Description
user	blackberry.bbm.platform.users.BBMPlatformUser | blackberry.bbm.platform.users.BBMPlatformUser[]	Single user, or array of users, to remove from the connection.

Throws	Description
NullPointerException	If user is null.
IllegalArgumentException	If of of the users being removed does not belong to the connection.
PersistentContentException	If Content Protection is enabled and device is locked.

Code Example(s)

<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>

removeAll

---

void removeAll()

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Removes all users from the connection.

Throws	Description
PersistentContentException	If Content Protection is enabled and device is locked.

send

---

void send(data : String, [users: blackberry.bbm.platform.users.BBMPlatformUser[]])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Sends data to all users on the connection or a subset. Data cannot be sent to users who have not joined.

Parameter	Type	Description
data	String	Object to be sent.
users	blackberry.bbm.platform.users.BBMPlatformUser[] Optional	Data recipients. If not provided, data will be sent to all users on this connection.

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.
IllegalArgumentException	If users contains a user who has not joined this connection.
IllegalArgumentException	If users.length > 24.
PersistentContentException	If Content Protection is enabled and device is locked.

Code Example(s)

<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>

ondata

---

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

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Invoked when data is received from a user.

Parameter	Type	Description
sender	blackberry.bbm.platform.users.BBMPlatformUser	User that sent the data.
data	String	Data received.

Code Example(s)

<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>

onuserdeclined

---

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

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Invoked when a user declines an invitation.

Parameter	Type	Description
user	blackberry.bbm.platform.users.BBMPlatformUser	User who declined.

onuserleft

---

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

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Invoked when a user leaves the connection.

Parameter	Type	Description
user	blackberry.bbm.platform.users.BBMPlatformUser	User who left.

onusersinvited

---

void onusersinvited(users : blackberry.bbm.platform.io.BBMPlatformUser)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Invoked when the user invites others to join the connection. This will not be called if the user invites others to download the application.

Parameter	Type	Description
users	blackberry.bbm.platform.io.BBMPlatformUser	the users who were invited

onusersjoined

---

void onusersjoined(users : blackberry.bbm.platform.users.BBMPlatformUser[], type : String, cookie : String)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Invoked when users join the connection by accepting an invitation.

Parameter	Type	Description
users	blackberry.bbm.platform.users.BBMPlatformUser[]	The users who joined.
type	String	The type of join. "invitedbyme": The joining users were invited by the current user. "acceptedbyme": The current user is joining the connection.
cookie	String	The cookie that was sent with the invitation. undefined if no cookie was sent.

Properties:

---

Property	Type	Description	Supported Platform(s)
id	Number readonly	This connection's unique ID. Automatically set on connection creation.	- BlackBerry OS 5.0+
joinedUsers	blackberry.bbm.platform.users.BBMPlatformUser[] readonly	Users who have joined the connection.	- BlackBerry OS 5.0+
pendingUsersCount	Number readonly	The number of invited users who have not yet joined the connection.	- BlackBerry OS 5.0+

Constants:

---

Property	Type	Description	Supported Platform(s)
MAX_USERS default: 24 users	Number	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.	- BlackBerry OS 5.0+
MAX_COOKIE_LENGTH default: 128 characters	Number	The maximum length of an invitation cookie.	- BlackBerry OS 5.0+
MAX_INVITE_MSG_LENGTH default: 128 characters	Number	The maximum length of an invitation message.	- BlackBerry OS 5.0+
MAX_DATA_LENGTH default: 61440 characters	Number	The maximum length of a data payload .	- BlackBerry OS 5.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:16 GMT-0500 (EST)