Connections

Provides services to create, accept, and manage connections.

Connections

Connection types

The BBM Platform supports the following types of connections:
blackberry.bbm.platform.io.Channel
blackberry.bbm.platform.io.Session

Creating a connections

Connections can be created using createConnection. When a connection is created, the application should assign callbacks to it in order to be notified of various events.

var type = ... // One of "channel" or "session"
var conn = blackberry.bbm.platform.io.createConnection(type);
setConnectionCallbacks(conn, type);

Accepting incoming connections

When the current user accepts an invitation within BBM, onconnectionaccepted will be invoked with the connection on which the invitation was accepted. The application should assign callbacks to the connection within this method.

var conn;

blackberry.bbm.platform.io.onconnectionaccepted = function(type, connection, cookie) {
    // Save the connection and set the callbacks
    conn = connection;
    setConnectionCallbacks(conn, type);
};

Connection events

A generic function can be used to assign callbacks to connections.

function setConnectionCallbacks(conn, type) {
    // Channel/Session callbacks
    conn.onusersinvited = function(users) {
        // ...
    };
    conn.onusersjoined = function(users, type, cookie) {
        // ...
    };
    conn.onuserdeclined = function(user) {
        // ...
    };
    conn.onuserleft = function(user) {
        // ...
    };
    conn.ondata = function(user, data) {
        // ...
    };
    
    // Session callbacks
    if(type == "session") {
        conn.onbroadcastdata = function(user, data) {
            // ...
        };
        conn.onusersremoved = function(user, users) {
            // ...
        };
        conn.onended = function(user) {
            // ...
        };
    }
};

Adding Users to Connections

There are two ways to add users to connections: (1) inviting contacts to join a connection, and (2) hosting a connection for non-contacts to join. A user does not have to be the connection creator in order to invite users.

1. Inviting contacts to join

An application user can invite contacts to join a connection.

When the application calls inviteContacts a Contact Picker dialog will be shown containing contacts that have the application installed. If the user invites contacts then the onusersinvited callback will be invoked on the inviter's side.

Invitees receive the invitations within BBM.

• If they accept the invitation, onusersjoined is invoked on the inviter's side, and onconnectionaccepted is invoked on the invitee's side with the connection they just joined.
• If they decline the invitation, onuserdeclined is invoked on the inviter's side.

2. Hosting a public connection for non-contacts to join

An application user can also host an event within a public connection to let all application users join.

When the application calls host a dialog will be shown for the user to allow or deny the decision. If the user allows, the application should then post the host's PIN and PPID to its discovery service. The BBM platform does not provide a discovery service. This must be provided by the application developer.

Peers should download host information (PIN and PPID) from the discovery service and then call joinHost. The peer will also be presented with a dialog to allow or deny the decision.

At this point the request is in the "pending" state. In this state the peer can cancel the request, and the host can accept or decline.

Supported Platform(s)

- BlackBerry OS 5.0+

View Supported Platform Table

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

---