thing-if SDK
 All Data Structures Files Functions Variables Typedefs Macros
Data Structures | Macros | Typedefs | Functions
kii_thing_if.h File Reference
#include <kii.h>

Go to the source code of this file.

Data Structures

struct  kii_thing_if_command_handler_resource_t
 
struct  kii_thing_if_state_updater_resource_t
 
struct  kii_thing_if_t
 

Macros

#define EMESSAGE_SIZE   50
 
#define KII_THING_IF_TASK_NAME_STATUS_UPDATE   "status_update_task"
 

Typedefs

typedef kii_bool_t(* KII_THING_IF_ACTION_HANDLER )(const char *schema, int schema_version, const char *action_name, const char *action_params, char error[EMESSAGE_SIZE+1])
 
typedef kii_bool_t(* KII_THING_IF_WRITER )(kii_t *kii, const char *buff)
 
typedef kii_bool_t(* KII_THING_IF_STATE_HANDLER )(kii_t *kii, KII_THING_IF_WRITER writer)
 
typedef kii_bool_t(* KII_THING_IF_CUSTOM_PUSH_HANDLER )(kii_t *kii, const char *message, size_t message_length)
 
typedef struct
kii_thing_if_command_handler_resource_t 
kii_thing_if_command_handler_resource_t
 
typedef struct
kii_thing_if_state_updater_resource_t 
kii_thing_if_state_updater_resource_t
 
typedef struct kii_thing_if_t kii_thing_if_t
 

Functions

kii_bool_t init_kii_thing_if (kii_thing_if_t *kii_thing_if, const char *app_id, const char *app_key, const char *app_host, kii_thing_if_command_handler_resource_t *command_handler_resource, kii_thing_if_state_updater_resource_t *state_updater_resource, KII_JSON_RESOURCE_CB resource_cb)
 
kii_bool_t onboard_with_vendor_thing_id (kii_thing_if_t *kii_thing_if, const char *vendor_thing_id, const char *password, const char *thing_type, const char *thing_properties)
 
kii_bool_t onboard_with_thing_id (kii_thing_if_t *kii_thing_if, const char *thing_id, const char *password)
 
kii_bool_t init_kii_thing_if_with_onboarded_thing (kii_thing_if_t *kii_thing_if, const char *app_id, const char *app_key, const char *app_host, const char *thing_id, const char *access_token, kii_thing_if_command_handler_resource_t *command_handler_resource, kii_thing_if_state_updater_resource_t *state_updater_resource, KII_JSON_RESOURCE_CB resource_cb)
 

Macro Definition Documentation

#define EMESSAGE_SIZE   50
#define KII_THING_IF_TASK_NAME_STATUS_UPDATE   "status_update_task"

Typedef Documentation

typedef kii_bool_t(* KII_THING_IF_ACTION_HANDLER)(const char *schema, int schema_version, const char *action_name, const char *action_params, char error[EMESSAGE_SIZE+1])

callback function for handling action.

Parameters
[in]schemaname of schema. [in] schema_version version of schema.
[in]action_namename of the action.
[in]action_paramsjson object represents parameter of this action.
[out]errorerror message if operation is failed.(optional)
Returns
KII_TRUE if succeeded, otherwise KII_FALSE.

Resource for command handler.

Invocation of #action_handler, #state_handler and #custom_push_handler callback inside this struct is serialized since they are called from the single task/thread.

However, kii_thing_if_state_updater_resource_t::state_handler and callbacks inside this struct is invoked from different task/ thread. That means the invocation could be concurrent.

If you share the resources(memory, file, etc.) among the callbacks called concurrently, be aware for it and avoid deadlock when you implement synchronization for the resources.

typedef kii_bool_t(* KII_THING_IF_CUSTOM_PUSH_HANDLER)(kii_t *kii, const char *message, size_t message_length)

callback function enables to handle all push notifications.

This handler is optional and only used for advanced use-cases. Push notification will be sent to the thing in following cases.

  • Subscribed buckets events
  • Messages sent to the subscribed topics
  • Commands sent to this thing.

Normally you don't need to implement this handler. Without this handler, SDK only deals with push notification includes Command. In this case, SDK parses the push notification and if its a valid Command to the thing, KII_THING_IF_ACTION_HANDLER will be called.

This handler will be implemented and passed to kii_thing_if_t in case you need to handle bucket events notification, messages arrived to subscribed topic or need to implement custom procedure when received a Commands sent to this thing.

You can choose by retruning KII_TRUE or KII_FALSE whether to let SDK to continue handling with default logic which deals with Command push notification.

Parameters
[in]kii_tkii_t object if you want to send request to kii cloud you can use this kii_t object.
[in]messagenotification message
[in]message_lengthlength of message.
Returns
  • KII_TRUE Let SDK to skip executing default logic handles Command. In this case KII_THING_IF_ACTION_HANDLER won't be called even if the push notification includes valid Command.
  • KII_FALSE Let SDK to execute default logic handles Command. If the push notification includes valid Command, KII_THING_IF_ACTION_HANDLER will be called. (If the push notification is not Command, would be ignored safely.)
typedef kii_bool_t(* KII_THING_IF_STATE_HANDLER)(kii_t *kii, KII_THING_IF_WRITER writer)

callback function for writing thing state.

This callback function should write current thing state with KII_THING_IF_WRITER. for example:

kii_bool_t state_handler(
kii_t* kii,
{
char buf[256];
if ((*writer)(kii, "{\"power\":") == KII_FALSE) {
return KII_FALSE;
}
if (get_power() != 0) {
if ((*writer)(kii, "true,") == KII_FALSE) {
return KII_FALSE;
}
} else {
if ((*writer)(kii, "false,") == KII_FALSE) {
return KII_FALSE;
}
}
if ((*writer)(kii, "\"brightness\":") == KII_FALSE) {
return KII_FALSE;
}
sprintf(buf, "%d,", get_brightness());
if ((*writer)(kii, buf) == KII_FALSE) {
return KII_FALSE;
}
if ((*writer)(kii, "\"color\":[") == KII_FALSE) {
return KII_FALSE;
}
sprintf(buf, "%d,", get_color(0));
if ((*writer)(kii, buf) == KII_FALSE) {
return KII_FALSE;
}
sprintf(buf, "%d,", get_color(1));
if ((*writer)(kii, buf) == KII_FALSE) {
return KII_FALSE;
}
sprintf(buf, "%d],", get_color(2));
if ((*writer)(kii, buf) == KII_FALSE) {
return KII_FALSE;
}
if ((*writer)(kii, "\"colorTemperature\":") == KII_FALSE) {
return KII_FALSE;
}
sprintf(buf, "%d}", get_colorTemperature());
if ((*writer)(kii, buf) == KII_FALSE) {
return KII_FALSE;
}
return KII_TRUE;
}
Parameters
[in]kiistate_updater object.
[in]writerwriter to write thing state. implementation of this writer is provided by this SDK.
Returns
KII_TRUE if succeeded. otherwise KII_FALSE.

Resource for state updater. Invocation of #state_handler callback inside this struct is serialized since it called from single task/thraed.

However, #state_handler and callbacks inside kii_thing_if_command_handler_resource_t would be invoked from different task/thread. That means the invocation could be concurrent.

If you share the resources(memory, file, etc.) among the callbacks called concurrently, be aware for it and avoid deadlock when you implement synchronization for the resources.

typedef kii_bool_t(* KII_THING_IF_WRITER)(kii_t *kii, const char *buff)

a function pointer to write thing state.

This function pointer is used at KII_THING_IF_STATE_HANDLER. This function pointer is passed as second argument of KII_THING_IF_STATE_HANDLER. Implementation of this function pointer is provided by this SDK.

Parameters
[in]contextcontext of state handler.
[in]buffjson string of thing state. must be null terminated.
Returns
KII_TRUE if succeeded. otherwise KII_FALSE.

Function Documentation

kii_bool_t init_kii_thing_if ( kii_thing_if_t kii_thing_if,
const char *  app_id,
const char *  app_key,
const char *  app_host,
kii_thing_if_command_handler_resource_t command_handler_resource,
kii_thing_if_state_updater_resource_t state_updater_resource,
KII_JSON_RESOURCE_CB  resource_cb 
)

Initialize kii_thing_if_t object.

After this method is called, applications must call onboard_with_vendor_thing_id(kii_thing_if_t*, const char*, const char*, const char*, const char*) or onboard_with_thing_id(kii_thing_if_t*, const char*, const char*) to onboard from thing.

Parameters
[in]kii_thing_ifkii_thing_if_t object to be initialized.
[in]app_idthe input of Application ID
[in]app_keythe input of Application Key
[in]app_hosthost name. should be one of "CN", "CN3", "JP", "US", "SG" or "EU".
[in]command_handler_datadata container for command handler.
[in]state_updater_datadata container for state updater.
[in]resource_cbcallback to resize to kii_json_resource contents. This is optional. If you build this SDK with KII_JSON_FIXED_TOKEN_NUM macro, you can set NULL to this argument. otherwise, you need to set kii_json_resource_t object to this argument.
Returns
KII_TRUE when succeeded, KII_FALSE when failed.
kii_bool_t init_kii_thing_if_with_onboarded_thing ( kii_thing_if_t kii_thing_if,
const char *  app_id,
const char *  app_key,
const char *  app_host,
const char *  thing_id,
const char *  access_token,
kii_thing_if_command_handler_resource_t command_handler_resource,
kii_thing_if_state_updater_resource_t state_updater_resource,
KII_JSON_RESOURCE_CB  resource_cb 
)

Initialize kii_thing_if_t object with onboarded thing information.

This api is used when onboard process has been done by controller application (typically a mobile apps.) and thing ID and access token is given by the controller application (via BLE, etc.) Since in this case onboard process is already completed, no need to call onboard_with_vendor_thing_id() or onboard_with_thing_id().

kii_thing_if_t::command_handler and kii_thing_if_t::state_updater instances are used to call api.

Parameters
[in]app_idthe input of Application ID
[in]app_keythe input of Application Key
[in]app_hosthost name. should be one of "CN", "CN3", "JP", "US", "SG" or "EU".
[in]thing_idthing id given by a controller application NonNull, NonEmpty value must be specified.
[in]access_tokenaccess token of the thing given by a controller application. NonNull, NonEmpty value must be specified.
[in]command_handler_datadata container for command handler.
[in]state_updater_datadata container for state updater.
[in]resource_cbcallback to resize to kii_json_resource contents. This is optional. If you build this SDK with KII_JSON_FIXED_TOKEN_NUM macro, you can set NULL to this argument. otherwise, you need to set kii_json_resource_t object to this argument.
Returns
KII_TRUE when succeeded, KII_FALSE when failed.
kii_bool_t onboard_with_thing_id ( kii_thing_if_t kii_thing_if,
const char *  thing_id,
const char *  password 
)

Onboard to Thing_If Cloud with specified thing ID. kii_thing_if_t::command_handler and kii_thing_if_t::state_updater instances are used to call api.

Parameters
[in,out]kii_thing_ifkii this SDK instance.
[in]thing_idthing id issued by Kii Cloud. NonNull, NonEmpty value must be specified.
[in]passwordpassword of the thing given by thing vendor. NonNull, NonEmpty value must be specified.
Returns
KII_TRUE when succeeded, KII_FALSE when failed.
kii_bool_t onboard_with_vendor_thing_id ( kii_thing_if_t kii_thing_if,
const char *  vendor_thing_id,
const char *  password,
const char *  thing_type,
const char *  thing_properties 
)

Onboard to Thing_If Cloud with specified vendor thing ID. kii_thing_if_t::command_handler and kii_thing_if_t::state_updater instances are used to call api.

Parameters
[in,out]kii_thing_ifkii this SDK instance.
[in]vendor_thing_idvendor thing id given by thing vendor. NonNull, NonEmpty value must be specified.
[in]passwordpassword of the thing given by thing vendor. NonNull, NonEmpty value must be specified.
[in]thing_typetype of the thing. If the thing is already registered, this argument is ignored. If NULL the argument is ignored.
[in]thing_propertiesOther properties of the thing. please refer to http://docs.kii.com/rest/#thing_management-register_a_thing about the format. If the thing is already registered, this argument is ignored. If NULL the argument is ignored.
Returns
KII_TRUE when succeeded, KII_FALSE when failed.