Report and Event Overview

GAPI contains two mechanisms to convey non-transactional data: report and event.

report conveys recurring data, such as periodic Advertising or recurring Notification or Indication information.

event conveys non-recurring activities, such as a spurious device disconnect, hardware error, or end of a long-lived transation, such as list.

Both methods have success and error callbacks. The success callback is passed an object containing information about the report or event. The error callback is passed an object indicating the reason for the report or event error.

report(params, success, error)

  • Call: appc.gapi.prototype.report(params, success, error)
  • Parameters: params, success, error
    params: A JavaScript object with properties: did (see below)
    { 
        did:        <device id ('*' means all connected devices)>
    }

success: a callback accepting an object:

    { 
        result: <result code>,
        subcode: <result subcode>
        report: <kind of report>,
        [other information]: see below
    }

error: a callback accepting an object:

    { result: <result code> }

Description:

Enable reports. Reports convey information that is generally periodic or recurring, resulting from a prior method call (e.g. list or subscribe).

In the object passed to the report success callback, the value of the report property identifies the kind of report.

Advertising: If the success callback includes Advertising data, the result object will contain a nodes array:

    nodes: [{
        did:    <device id (address)>,
        ev:     <advertising event type>,
        dtype:  <device type (0, public; 1, random)>,
        adv:    <advertising data>,
        rsp:    <scan response data>,
        rssi:   <RSSI>,
        tss:    <timestamp of scan result (sec)>,
        tsus:   <timestamp of scan result (usec)>
    }]

Objects in the nodes array contain device Advertising information.

Advertising (adv) and Scan Response (rsp) are arrays of objects. Each object in an adv or rsp array represents Advertising data. The t property of each object identifies a Data Type Value; the v property identifies a Data Type Name. t is represented as a (decimal) integer. v is represented according to the integer value of t. For example, single octet flags are integers. 16-bit and 32-bit UUIDs are integers. Multiple octet values (including 128-bit UUIDs) are arrays of integers. Human-readable text, UTF-8 strings.

Notifications: If the success callback includes Notification data, the report object will contain a notifications array:

    notifications: [{
        handle: <Characteristic handle>,
        value:  <Characteristic value>
        tss:    <timestamp (sec)>,
        tsus:   <timestamp (usec)>
    }]

Both handle and value are represented as hex-ASCII.

Notifications may occur after the application subscribes to a device GATT Characteristic that supports the Characteristic Notify property.

Example::

    var params = {did: '*'};

    gapi.report(params,
        function (robj) {
            console.log('subscribe: ', JSON.stringify(robj, null, 2);
        },
        function (errObj) {
            console.log('subscribe: ', JSON.stringify(robj, null, 2);
        });

event(params, success, error)

  • Call: appc.gapi.prototype.event(params, success, error)
  • Parameters: params, success, error
    params: A JavaScript object with property: did (see below)
    {
        did:        <device id ('*' means all connected devices)>
    }

success: a callback accepting an object:

    { 
        result:     <result code>,
        subcode:    <result subcode>,
        event:      <event type>,
        node        <device id (if any)>
    }

error: a callback accepting an object:

    { result: <result code> }

Description:

Receive events. Events convey state information, or indications that are generally not expected. For example, events such as device disconnected, hardware error, etc. indicate unexpected changes of state in devices. An event such as list command complete, is an expected state change, indicating the end of a list operation.

Example:

    var params = {did: '*'};

    gapi.report(params,
        function (robj) {
            console.log('subscribe: ', JSON.stringify(robj, null, 2);
        },
        function (errObj) {
            console.log('subscribe: ', JSON.stringify(robj, null, 2);
        });