Transport Overview¶

GAPI transports are used to transfer data between a client application and a GAPI gateway. There are currently two types of transports, WebSocket and HTTP. After initialization, and possibly before login, a transport type , ws or http, may be set using config. It is highly recommended to use ws whenever possible.

Note: 'ws' actually uses a Secure WebSocket (wss); 'http' uses TLS.

Communication between the application and the GAPI gateway will not occur unless a call to open results in open's success callback being invoked.

After completing all gateway communications, the application should close all of its transports by making a call to close.

An application may connect to more than one GAPI gateway at a time by running with more than one instance of the GAPI module. In this case, login should only be called once; the authorization token received in the success callback of login should then be used for operations on all gateways. Similarly, logout should only be called after transports to all gateways have been closed.

Transport Connection¶

open(params, success, error)¶

• Call: appc.gapi.prototype.open(params, success, error)
  
• Parameters: params, success, error
  params: an empty object:

    { }

success: a callback accepting an object:

    { result: <result code> }

error: a callback accepting an object:

    { result: <result code> }

Description:

Opens a transport connection between the application and a gateway that is registered to the user's account.

On success, the client may connect to BLE devices it discovers by scanning (using list) or that are already connected during previous sessions.

Applications should call open to open a transport (after calling config, if not using the default gateway id).

Example:

    gapi.open({}, function(robj) {
        console.log('open: ' + robj.result);
    }, function(robj) {
        console.log('open: ERROR: ' + robj.result);
    });

close(params, success, error)¶

• Call: appc.gapi.prototype.close(params, success, error)
  
• Parameters: params, success, error
  params: an object:

    { }

success: a callback accepting an object:

    { result: <result code> }

error: a callback accepting an object:

    { result: <result code> }

Description:

Close a transport connection.

Applications should call close to disconnect network connections and release resources.

Example:

    gapi.close({}, null, null);