ks-client

API

All the functions that accept a callback also return promises. So you can use the library in the usual callback style or promise style, whichever you prefer.

Requires C gateway version >= 1.0.18 or JS gateway version >= 2.0.0.

Example

var KSClient = require("ks-client");
var constants = KSClient.constants;
var client = new KSClient;

var path = "/tmp/ks_gw_socket";

// this is equivalent to...
client.connect(path, function(err) {
  if (err) {
    // handle error
    return;
  }

  // handle success
});

// ...this
client.connect(path).then(function () {
  // handle success
}).catch(function (err) {
  // handle error
});

new KSClient

Creates a new client object.

The client is an EventEmitter and it emits the following events.

Event: ipc-disconnected

Fired when the IPC gets disconnected. You will need to call #connect again after this.

Event: state

Fired when the state of the gateway changes.

Field | Type | Description ------|------|------------ state | int | Represents the state of the client. One of the network state constants from constants.md. error | int | Possible error code. One of the error constants from constants.md.

Event: notification

Fired when a notification is received.

Field | Type | Description ------|------|------------ address | string | Alphanumeric string. payloadType | string | Type of payload. One of: "BINARY", "INT", "STRING", "PING", "PONG". payload | int, Buffer or string | 32 bit integer when payloadType is "INT", Buffer when "BINARY", string otherwise.

Event: rid

Fired when your application receives its RID.

Field | Type | Description ------|------|------------ address | string | Alphanumeric string. rid | string | The RID received. secret | string | The secret of that RID.

Event: gateway-rid

Fired when the gateway receives its RIDs.

Field | Type | Description ------|------|------------ rid | string | The gateway RID.

#connect(path, [callback])

Connect to a socket in the given address or path. For example, /tmp/ks_gw_socket or localhost:12345.

#disconnect([callback])

Disconnects an established connection, if any.

#register(address, version, customerId, channels, [callback])

Registers with the daemon. App will start receiving notifications and other events.

NOTE: If you need to update the channels, you have to first unregister nd then register again, with the different channels.

Argument | Type | Description ---------|------|------------ address | string | Alphanumeric string. version | string | Alphanumeric string. customerId | string | Your customer ID. Alphanumeric. channels | Array | Array of strings describing the channels you wish to subscribe to.

#unregister(address, version, customerId, [callback])

Unregisters from the daemon.

Argument | Type | Description ---------|------|------------ address | string | Alphanumeric string. version | string | Alphanumeric string. customerId | string | Your customer ID. Alphanumeric.

#publish(payloadType, payload, [tag], [callback])

Publishes a message to the server.

Argument | Type | Description ---------|------|------------ payloadType | string | Type of payload. One of: "BINARY", "INT", "STRING", "PING", "PONG". payload | int, Buffer or string | 32 bit integer when payloadType is "INT", Buffer when "BINARY", string otherwise. tag | string | SRIKY WHAT WAS THIS AGAIN?

#requestState([callback])

Request the state from the daemon. This will cause the state event to be emitted. The callback is run when the request has been written.

#requestRid([callback])

Request your rid from the daemon. This will cause the rid event to be emitted. The callback is run when the request has been written.

#requestAppId([callback])

Request the application ID from the daemon. Callback will be called with the application ID.

#setNetworkAvailable(opts, [callback])

Set the availability of the network. opts is an object of the following format:

{
  state: constants.NETWORK_STATE_MOBILE_2G, // one of the network state constants
  mcc: "555", // optional, use with mobile networks
  mnc: "66", // optional, use with mobile networks
}

mcc and mnc are used for optimization of the connection. If they change, you should update the state.

#setEngineEnabled(enabled, [callback])

Enable or disable the gateway.

Argument | Type | Description ---------|------|------------ enabled | boolean |

#setOrganizationSecret(secret, [callback])

Set the organization secret. This will only have an effect if it is called on an empty database before any applications have been registered.

Argument | Type | Description ---------|------|------------ secret | string |

Example use

A complete example that works similarly to the C SDK's sample_publish can be found in src/lib/example.js.