Connections

Provides services to create, accept, and manage connections.

Connections

Connection types

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

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

When the current user accepts an invitation within BBM, blackberry.bbm.platform.io.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) {
    // 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, the onusersinvited callback will be invoked on the inviter's side.

Invitees receive the invitations within BBM.


invite_to_join.png

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.


hosting.png


Supported Platform(s)

- BlackBerry OS 5.0+
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.bbm.platform.io.createConnection Y Y Y       
blackberry.bbm.platform.io.host Y Y Y       
blackberry.bbm.platform.io.joinHost Y Y Y       
hostRequests Y Y Y       
hostedConnection Y Y Y       
joinHostRequests Y Y Y       
blackberry.bbm.platform.io.onconnectionaccepted Y Y Y       
blackberry.bbm.platform.io.ondataexpired Y Y Y       
blackberry.bbm.platform.io.onuserreachable 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

static blackberry.bbm.platform.io.Channel | blackberry.bbm.platform.io.Session blackberry.bbm.platform.io.createConnection (type : String)


Creates a connection.

The application should assign callbacks to the connection after creating it.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
type The type of connection to create: "channel" or "session".

Return:

The connection created.


static void blackberry.bbm.platform.io.host (connection : blackberry.bbm.platform.io.Connection, onComplete: function(hosting : Boolean), onRequestReceived: function(request : blackberry.bbm.platform.io.IncomingJoinRequest), onRequestCanceled: function(request : blackberry.bbm.platform.io.IncomingJoinRequest, reason : String))


Enables hosting on this connection. The user is prompted with a dialog to allow or deny hosting.

To stop hosting, call blackberry.bbm.platform.io.host(). Stopping hosting will not remove users from the connection who have already joined, but it will prevent others from joining. hostRequests will be emptied.

The user may only host on one connection in the application. If this application is already hosting a public connection and this method is invoked on a different connection, then hosting will stop on the old connection and begin on the new one. The user will again be prompted with a dialog to allow or deny hosting.

Reasons why a request is canceled

  • "peercanceled": The peer canceled the request without a specific reason.
  • "peerleft": The peer exited the application.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
connection The connection on which to host.
onComplete Invoked when the user finishes approving/denying hosting.

hosting: true if the user decided to start hosting; false otherwise.
onRequestReceived Invoked when the host receives a join request from a peer.

request: The received request.
onRequestCanceled Invoked when a peer cancels a join request.

request: The canceled request.
reason: The reason that the request was canceled.

static void blackberry.bbm.platform.io.joinHost (hostPIN : String, hostPPID : String, onComplete: function(request : blackberry.bbm.platform.io.OutgoingJoinRequest), onHostAccepted: function(request : blackberry.bbm.platform.io.OutgoingJoinRequest, cookie : String), onHostDeclined: function(request : blackberry.bbm.platform.io.OutgoingJoinRequest, reason : String), [cookie : String])


Sends a join request to a user hosting a public connection for others to join.

The host does not need to be a contact of the current user.

Reasons why a request is declined

  • "hostdeclined": The host declined without a specific reason.
  • "hostppidinvalid": The host PPID is invalid.
  • "appnotrunning": The host's application was not running when they received the request.
  • "connectionnotfound": The host is not hosting on any connection, or stopped hosting the connection while the request was pending.
  • "connectionfull": The host's connection is full.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
hostPIN The host PIN. Can be obtained by blackberry.identity.PIN
hostPPID The host PPID. Can be obtained by blackberry.bbm.platform.self.ppid.
onComplete Invoked when the user finishes approving the join request.

request: The request sent to the host; undefined if the user aborted the join request.
onHostAccepted Invoked when the join request is accepted by the host.

request: The accepted request.
cookie: The cookie sent when the host accepted the join request in accept. undefined if a cookie wasn't provided.
onHostDeclined Invoked when the join request is declined by the host.

request: The declined request.
reason: The reason that the request was declined.
cookie A custom parameter provided by the application, such as the current game level. Max length of 128 characters.

Throws
IllegalStateException If the current user has connected with the host in a connection but still attempts to send another join request to the host.
IllegalArgumentException If hostPIN is invalid.
IllegalArgumentException If hostPPID is invalid.
IllegalArgumentException If cookie is longer than 128 characters.

Events

static void blackberry.bbm.platform.io.onconnectionaccepted (connectionType : String, connection : blackberry.bbm.platform.io.Channel|blackberry.bbm.platform.io.Session)


Invoked when an incoming connection is accepted. There are two cases when this may happen:

  • When an invitation is accepted in the BBM chat window.
  • When a host accepts a join request.

This callback is required when using either invitation framework. It must be assigned before the call to blackberry.bbm.platform.register.

The application should assign callbacks to the connection in this method.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
connectionType The type of connection: "channel" or "session".
connection The connection.

static void blackberry.bbm.platform.io.ondataexpired (user : blackberry.bbm.platform.users.BBMPlatformUser, data : String[])


Invoked when pending data for an unreachable user has expired. See send for more details.

See send


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
user The unreachable user.
data The data messages which expired.

static void blackberry.bbm.platform.io.onuserreachable (user : blackberry.bbm.platform.users.BBMPlatformUser)


Invoked when a contact has become reachable after a ContactUnreachableException was thrown from send.

See send


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
user The user who has become reachable.

Properties

static readonly blackberry.bbm.platform.io.IncomingJoinRequest[] hostRequests


Requests that the current user (host) has received on hostedConnection.

Requests in this list are in the pending state. New requests will be added to this list automatically. Requests that are accepted, denied, or canceled will be removed from this list automatically.

The host can accept or decline a request using accept and decline.


Supported Platforms
 - BlackBerry OS 5.0+

static readonly blackberry.bbm.platform.io.Connection hostedConnection


The connection being hosted. undefined if no connection is being hosted.

Use blackberry.bbm.platform.io.host to host an existing connection.


Supported Platforms
 - BlackBerry OS 5.0+

static readonly blackberry.bbm.platform.io.OutgoingJoinRequest[] joinHostRequests


Requests that the current user (peer) has sent to hosts using blackberry.bbm.platform.io.joinHost.

Requests in this list are in the pending state. New requests will be added to this list automatically. Requests that are accepted, denied, or canceled will be removed from this list automatically.

The user can cancel a request using cancel.


Supported Platforms
 - BlackBerry OS 5.0+

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