Client SDK Documentation
Enumerations
KaltiotSmartState
KS_STATE_OFFLINE
KS_STATE_DISCONNECTING
KS_STATE_CONNECTING
KS_STATE_ONLINE
KaltiotSmartError
KS_ERROR_NO_ERROR
KS_ERROR_CONNECT_ERROR
KS_ERROR_GATEWAY_DISCONNECT
KS_ERROR_UNKNOWN
KS_ERROR_CLIENT_DISCONNECT
payload_type_t
KS_GW_CLIENT_PAYLOAD_BINARY
KS_GW_CLIENT_PAYLOAD_INT
KS_GW_CLIENT_PAYLOAD_STRING
KS_GW_CLIENT_PAYLOAD_PING
KS_GW_CLIENT_PAYLOAD_PONG
network_state_e
NETWORK_STATE_DISABLED
NETWORK_STATE_MOBILE_2G
NETWORK_STATE_MOBILE_3G
NETWORK_STATE_MOBILE_4G
NETWORK_STATE_MOBILE_5G
NETWORK_STATE_WIFI
NETWORK_STATE_COUNT
Functions
void ks_gw_client_notification_cb(const char *address, const char *payload,
const uint16_t payload_length, const payload_type_t payload_type);
Callback function that is called when a notification is received. You should implement this.
Argument | Description |
---|---|
address | Null-terminated string. |
payload | Byte data. |
payload_length | Length of the payload. |
payload_type | Type of the payload. |
void ks_gw_client_rid_cb(const char *address, const char *rid, const char *secret);
Callback function that is called when a rid is received. You should implement this.
Argument | Description |
---|---|
address | Null-terminated string. |
rid | Null-terminated string. Unique resource identifier for every iot application registered to Kaltiot Smart IoT. Using this identifier you are able to send notifications to the iot application from Kaltiot Smart Rest api. |
secret | Null-terminated string. |
void ks_gw_client_state_changed_cb(KaltiotSmartState state, KaltiotSmartError error);
Callback function that is called when the state of the daemon changes. You should implement this.
Argument | Description |
---|---|
status | Status code that tells the new state. |
error | Possible error code associated with the state. |
extern bool ks_gw_client_connect(const char *path);
Connects to the daemon. Call this before registering. Returns true if the connection has been successfully established.
Argument | Description |
---|---|
path | The path or address to connect to. It is treated as a unix domain socket path unless it has a colon in it, in which case the IPC will use local TCP on ip:port. You can also leave it NULL, then the default path (/tmp/ks_client_socket) will be used. |
extern void ks_gw_client_disconnect();
Disconnects from the daemon.
extern void ks_gw_client_register_iot(const char *address, const char *version,
const char *customer_id, const char **channels, uint16_t num_channels);
Registers with the daemon. App will start receiving notifications and other events.
NOTE: If you need to update the groups, you have to first unregister and then register again, with the different groups.
Argument | Description |
---|---|
address | Alphanumeric, null-terminated string. |
version | Alphanumeric, null-terminated string. |
customer_id | Alphanumeric, null-terminated string. Identifier given by customer to the IoT application registering to Kaltiot Smart IoT. Use this field to identify your IoT application on gateway. It has to be unique for a given gateway. For example "sensor1". |
channels | Array of alphanumeric, null-terminated strings that represent the channels such as "temperature" or "motion". |
num_channels | The number of channels in the array. |
extern void ks_gw_client_unregister_iot(const char *address, const char *version, const char *customer_id);
Unregisters from the daemon.
Argument | Description |
---|---|
address | Alphanumeric, null-terminated string. |
version | Alphanumeric, null-terminated string. |
customer_id | Alphanumeric, null-terminated string. |
extern void ks_gw_client_publish_message(const uint8_t *payload, const uint16_t payload_len,
const payload_type_t payload_type);
Publishes a message to the server.
If payload_type is KS_GW_CLIENT_PAYLOAD_STRING, payload and length should include the null terminator of the string.
Argument | Description |
---|---|
payload | Byte data. |
payload_len | Length of the payload. |
payload_type | Type of the payload. |
extern void ks_gw_client_task();
Should be called periodically. It checks whether there is any data waiting to be read in the buffer, and based on said data calls the above callbacks.
extern void ks_gw_client_request_state();
Forces state_changed_cb to be called with the current state.
extern void ks_gw_client_request_rid();
Forces rid_cb to be called with the current rid info.
typedef void (*ks_app_id_callback) (const char *app_id, void *arg);
extern void ks_gw_client_request_app_id(ks_app_id_callback callback, void *arg);
Requests the application id from the daemon. The callback is called with the application id and an optional argument that the user can specify.
Argument | Description |
---|---|
callback | Callback function. |
arg | Optional argument passed to the callback. |
extern void ks_gw_client_set_engine_enabled(bool enabled);
Enables or disables the entire engine. Equivalent to closing the daemon.
Argument | Description |
---|---|
enabled |
extern void ks_gw_client_set_network_available(network_state_e state, const char *mcc, const char *mnc);
Sets the network status. MCC and MNC can be included with a mobile network state.
Argument | Description |
---|---|
state | The new state. |
mcc | Can be an empty null-terminated string, not NULL. |
mnc | Can be an empty null-terminated string, not NULL. |
Sample application
This can also be found in the client SDK package, in the sample_notification directory.
/** * This will connect to the daemon and register the application, then wait * for a notification to be received. After a notification is received, it * unregisters, disconnects and exits. */ #include "ks_gw_client.h" #include <stdio.h> #include <unistd.h> static bool notification_received = false; /* Callback receiving all incoming notifications. */ void ks_gw_client_notification_cb(const char *address, const char *payload, const uint16_t payload_length, const payload_type_t payload_type, const char *msg_id, const uint16_t msg_id_length) { notification_received = true; printf("notification received\n"); printf(" type: %d\n", payload_type); printf(" address: %s\n", address); printf(" payload: %.*s\n", payload_length, (const char *) payload); } /* Callback receiving all ks_gw_client connection state changes. */ void ks_gw_client_state_changed_cb(KaltiotSmartState state, KaltiotSmartError error) { printf("state changed\n"); printf(" state: %d\n", state); printf(" error: %d\n", error); } /* Callback receiving unique RID for this device. */ void ks_gw_client_rid_cb(const char *address, const char *rid, const char *secret) { if (!address) address = "null"; if (!rid) rid = "null"; if (!secret) secret = "null"; printf("rid received\n"); printf(" address: %s\n", address); printf(" rid: %s\n", rid); printf(" secret: %s\n", secret); } /* Connect and run until a notification is received. */ int main(int argc, char const *argv[]) { char address[] = "sample_notification_address"; char version[] = "1.2.3"; char customer_id[] = "sample_notification_customer_id"; char const *channels[] = { "sample_notification_channels" }; uint16_t num_channels = 1; if (!ks_gw_client_connect(NULL)) { printf("failed to connect\n"); return 1; } printf(" customer_id: %s\n", customer_id); ks_gw_client_set_engine_enabled(true); ks_gw_client_set_network_available(NETWORK_STATE_MOBILE_2G, "123", "45"); ks_gw_client_register_iot(address, version, customer_id, channels, num_channels); ks_gw_client_request_rid(); while (!notification_received) { ks_gw_client_task(); sleep(1); } ks_gw_client_unregister_iot(address, version, customer_id); ks_gw_client_disconnect(); printf("exiting application\n"); return 0; }