Advertising Overview

GAPI controls the Advertise (Broadcast) function of Netrunr.

GAPI advertise may be used to Advertise, or Advertise and send Scan Responses to device scan operations.

Advertise data may include any valid Advertise fields, including manufacturer-specific types, such as beacon information with various formats.

Netrunr supports multi-slot Advertise, where Advertise data is rotated through a set of values on a periodic basis. This allows e.g. multiple beacons formats to be supported concurrently. Multi-slot Advertise can either be done by the application periodically changing Advertise data with the 'set data' op, or by specifying a set of data (array of strings) and period during which to Advertise each array member (string).

advertise(params, success, error)

  • Call: appc.gapi.prototype.advertise(params, success, error) v1.1.6+
  • Parameters: params, success, error
    params: an object:
    {
        op: <1 (set parameters), 2 (set data), 4 (enable), 7 (all>
        enable: <1 (enable) or 0 (disable) advertising; valid when op=4 or op=7>
        channels: <0 (all primary channels), 1 (channel 37), 2 (channel 38), 4 (channel 39); (default: 0)>
        interval: <160 - 16384 (advertising interval, in 0.625*millisecond increments; i.e. 100ms - 10.24s)>
        type: <2 (scannable undirected), 3 (non-connectable undirected)>
        period: <100 or greater (in milliseconds); advertisement rotation period valid only if multi-slot/rotated advertising data>
        ad: <string (advertising data) or array of strings (multi-slot/rotated advertising data)>
        sd: <string (scan response data) or array of strings (multi-slot/rotated scan response data)>
    }

success: a callback accepting an object:

    { 
        c: 59,                 // command
        m: 0,                  // message id (optional)
        result: <result code> 
        subcode: <result subcode>
    }

error: a callback accepting an object:

    { result: <result code> }

Description:

Advertise (non-connectable), or Advertise and respond to device scans (scannable)

Advertise may be setup and initiated with one call, or controlled separately using the op parameter.

Advertise parameters cannot be set or changed unless Advertise is disabled.

Advertise data is encoded and may be set or changed at any time. Advertise data may be either a single string, or an array of strings. If Advertise data is a single string, then the decoded value of that string is broadcast. If Advertise data is an array of strings, then the decoded value of each string in the array is broadcast in turn, according to the period parameter.

An advertise success callback indicates that an Advertise operation has been successfully executed.

If the application wishes to stop the Advertise function at any time, it can issue the advertise command using the op and enable parameters (see Examples below);

Example:

Set Advertise Parameters advertise call:

    gapi.advertise({'op': 1, 'channels': 0, 'interval': 160, 'type': 2, 'period': 10000},
        function(robj) { 
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        function(robj) {
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        });  

Set Advertise Data advertise call:

    /* Set Advertising Data: flags, name ('1234') */
    gapi.advertise({'op': 2, 'ad': '020106050931323334'},
        function(robj) { 
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        function(robj) {
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        });  

Enable Advertise advertise call:

    gapi.advertise({'op': 4, 'enable': 1},
        function(robj) { 
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        function(robj) {
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        });  

Disable Advertise advertise call:

    gapi.advertise({'op': 4, 'enable': 0},
        function(robj) { 
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        function(robj) {
            console.log('advertise: ' + JSON.stringify(robj, null, 2));
        });