Connections

Provides services to create, accept, and manage connections.

Connections

Connection types

Creating connections

Connections can be created using blackberry.bbm.platform.io.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

var conn;

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

Connection events

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, 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 blackberry.bbm.platform.io.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 allow all application users to join.

When the application calls blackberry.bbm.platform.io.host, a dialog appears for the user to accept or refuse to host the public connection. If the user accepts, the application posts the host's PIN and PPID to its discovery service. The BBM Social Platform does not provide a discovery service. The application developer must provide one.

Peers should download host information (PIN and PPID) from the discovery service and then call blackberry.bbm.platform.io.joinHost. The peer will also be presented with a dialog to join or decline the public connection.

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.