#include <kii.h>

Data Structures
struct	kii_thing_if_error_t

struct	kii_thing_if_command_handler_resource_t

struct	kii_thing_if_state_updater_resource_t

struct	kii_thing_if_system_cb_t

struct	kii_thing_if_t

Macros
#define	EMESSAGE_SIZE 50

#define	KII_THING_IF_TASK_NAME_STATUS_UPDATE "status_update_task"

Typedefs
typedef enum kii_thing_if_state_t	kii_thing_if_state_t

typedef enum kii_thing_if_error_code_t	kii_thing_if_error_code_t

typedef struct kii_thing_if_error_t	kii_thing_if_error_t

typedef kii_bool_t(*	KII_THING_IF_ACTION_HANDLER )(const char alias, 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_system_cb_t	kii_thing_if_system_cb_t

typedef struct kii_thing_if_t	kii_thing_if_t

Enumerations
enum	kii_thing_if_state_t { KII_THING_IF_STATE_INITIALIZED, KII_THING_IF_STATE_ONBOARDED, KII_THING_IF_STATE_STARTED }

enum	kii_thing_if_error_code_t { KII_THING_IF_ERROR_INVALID_STATE, KII_THING_IF_ERROR_HTTP, KII_THING_IF_ERROR_SOCKET, KII_THING_IF_ERROR_INSUFFICIENT_BUFFER, KII_THING_IF_ERROR_INSUFFICIENT_ARG_BUFFER, KII_THING_IF_ERROR_INVALID_PAYLOAD }

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_thing_if_system_cb_t *system_cb, KII_JSON_RESOURCE_CB resource_cb)

kii_bool_t	start (kii_thing_if_t *kii_thing_if)

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 firmware_version, const char layout_position, const char thing_properties, kii_thing_if_error_t error)

kii_bool_t	onboard_with_thing_id (kii_thing_if_t kii_thing_if, const char thing_id, const char password, const char thing_type, const char firmware_version, const char layout_position, const char thing_properties, kii_thing_if_error_t error)

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_thing_if_system_cb_t *system_cb, KII_JSON_RESOURCE_CB resource_cb)

kii_bool_t	update_firmware_version (kii_thing_if_t kii_thing_if, const char firmware_version, kii_thing_if_error_t *error)

kii_bool_t	get_firmware_version (kii_thing_if_t kii_thing_if, char firmware_version, size_t firmware_version_len, kii_thing_if_error_t *error)

kii_bool_t	update_thing_type (kii_thing_if_t kii_thing_if, const char thing_type, kii_thing_if_error_t *error)

kii_bool_t	get_thing_type (kii_thing_if_t kii_thing_if, char thing_type, size_t thing_type_len, kii_thing_if_error_t *error)

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 *alias, const char *action_name, const char *action_params, char error[EMESSAGE_SIZE+1])

callback function for handling action.

Parameters

[in]	alias	name of alias.
[in]	action_name	name of the action.
[in]	action_params	json object represents parameter of this action.
[out]	error	error message if operation is failed.(optional)

Returns: KII_TRUE if succeeded, otherwise KII_FALSE.

typedef struct kii_thing_if_command_handler_resource_t kii_thing_if_command_handler_resource_t

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_t	kii_t object if you want to send request to kii cloud you can use this kii_t object.
[in]	message	notification message
[in]	message_length	length 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 enum kii_thing_if_error_code_t kii_thing_if_error_code_t

Error reasons of thing-if ThingSDK.

typedef struct kii_thing_if_error_t kii_thing_if_error_t

Error information of thing-if ThingSDK.

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,
        KII_THING_IF_WRITER writer)
{
    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]	kii	state_updater object.
[in]	writer	writer to write thing state. implementation of this writer is provided by this SDK.

Returns: KII_TRUE if succeeded. otherwise KII_FALSE.

typedef enum kii_thing_if_state_t kii_thing_if_state_t

States of kii_thing_if_t instance.

typedef struct kii_thing_if_state_updater_resource_t kii_thing_if_state_updater_resource_t

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 struct kii_thing_if_system_cb_t kii_thing_if_system_cb_t

System callback function pointers.

typedef struct kii_thing_if_t kii_thing_if_t

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]	context	context of state handler.
[in]	buff	json string of thing state. must be null terminated.

Returns: KII_TRUE if succeeded. otherwise KII_FALSE.

Enumeration Type Documentation

enum kii_thing_if_error_code_t

Error reasons of thing-if ThingSDK.

Enumerator
KII_THING_IF_ERROR_INVALID_STATE	State of kii_thing_if_t instance is invalid to use some functions.
KII_THING_IF_ERROR_HTTP	HTTP error.
KII_THING_IF_ERROR_SOCKET	Socket error.
KII_THING_IF_ERROR_INSUFFICIENT_BUFFER	HTTP request/ response buffer is insufficient. You need to increase size of HTTP request/ response buffer of kii_thing_if_t::command_handler and/or kii_thing_if_t::state_updater.
KII_THING_IF_ERROR_INSUFFICIENT_ARG_BUFFER	Size of argument buffer is insufficient. Some functions such as get_thing_type receives a pointer of an array. This error is raised if the length of the given array is shorter than required. Application should increase the length of the array.
KII_THING_IF_ERROR_INVALID_PAYLOAD	Fail to parse HTTP response. Received body payload in the response is unexpected form. You might not see this error since the error is arranged for contingencies such as received broken data from the undelying network. If this error constantly happens you may need to ask for support.

enum kii_thing_if_state_t

States of kii_thing_if_t instance.

Enumerator
KII_THING_IF_STATE_INITIALIZED	A kii_thing_if_t instance is initialized.
KII_THING_IF_STATE_ONBOARDED	A kii_thing_if_t instance is onboarded.
KII_THING_IF_STATE_STARTED	A kii_thing_if_t instance is started.

Function Documentation

kii_bool_t get_firmware_version	(	kii_thing_if_t *	kii_thing_if,
		char *	firmware_version,
		size_t	firmware_version_len,
		kii_thing_if_error_t *	error
	)

Get firmware version of a thing.

This function must be called between start and one of following functions:

Parameters

[in]	kii_thing_if_t	This SDK instance.
[out]	firmware_version	a buffer to copy firmware version got from Kii Cloud. This SDK makes the buffer null terminated string.
[in]	firmware_version_len	length of firmware_version which is second argument of this function.
[out]	error	Error infomation. This is optional. If NULL, error information is not set.

Returns: KII_TRUE when succeeded, KII_FALSE when failed. If returned value is KII_FALSE and error is not NULL, this SDK set error information to the error.

kii_bool_t get_thing_type	(	kii_thing_if_t *	kii_thing_if,
		char *	thing_type,
		size_t	thing_type_len,
		kii_thing_if_error_t *	error
	)

Get current thing type of a thing.

This function must be called between start and one of following functions:

Parameters

[in]	kii_thing_if_t	This SDK instance.
[out]	thing_type	a buffer to copy thing type got from Kii Cloud. This SDK makes the buffer null terminated string.
[in]	thing_type_len	length of thing_type which is second argument of this function.
[out]	error	Error infomation. This is optional. If NULL, error information is not set.

Returns: KII_TRUE when succeeded, KII_FALSE when failed. If returned value is KII_FALSE and error is not NULL, this SDK set error information to the error.

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_thing_if_system_cb_t *	system_cb,
		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.

After this functions succeeded, kii_thing_if_t::state becomes KII_THING_IF_STATE_INITIALIZED.

Parameters

[in]	kii_thing_if	kii_thing_if_t object to be initialized.
[in]	app_id	the input of Application ID
[in]	app_key	the input of Application Key
[in]	app_host	host name. should be one of "CN", "CN3", "JP", "US", "SG" or "EU".
[in]	command_handler_data	data container for command handler.
[in]	state_updater_data	data container for state updater.
[in]	resource_cb	callback 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_thing_if_system_cb_t *	system_cb,
		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.

After this functions succeeded, kii_thing_if_t::state becomes KII_THING_IF_STATE_ONBOARDED.

Parameters

[in]	app_id	the input of Application ID
[in]	app_key	the input of Application Key
[in]	app_host	host name. should be one of "CN", "CN3", "JP", "US", "SG" or "EU".
[in]	thing_id	thing id given by a controller application NonNull, NonEmpty value must be specified.
[in]	access_token	access token of the thing given by a controller application. NonNull, NonEmpty value must be specified.
[in]	command_handler_data	data container for command handler.
[in]	state_updater_data	data container for state updater.
[in]	resource_cb	callback 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,
		const char *	thing_type,
		const char *	firmware_version,
		const char *	layout_position,
		const char *	thing_properties,
		kii_thing_if_error_t *	error
	)

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.

After this functions succeeded, kii_thing_if_t::state becomes KII_THING_IF_STATE_ONBOARDED.

Parameters

[in,out]	kii_thing_if	This SDK instance.
[in]	thing_id	thing ID issued by Kii Cloud. Must not be NULL and empty string.
[in]	password	Password of the thing given by thing vendor. Must not be NULL and empty string.
[in]	thing_type	Type of the thing. If the thing is already registered, this value would be ignored by Kii Cloud. If this value is NULL or empty string, this value is ignored.
[in]	firmware_version	Firmware version of the thing. If the thing is already registered, this value would be ignored by Kii Cloud. If this value is NULL or empty string this value is ignored.
[in]	layout_position	Layout position of the thing. Should be one of "STANDALONE", "GATEWAY" or "ENDNODE". If the thing is already registered, this value would be ignored by Kii Cloud. If this value is NULL or empty string and the thing is not registered yet, then "STANDALONE" is used as default.
[in]	thing_properties	Other 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 value would be ignored by Kii Cloud. If this value is NULL or empty string this value is ignored.

Returns: KII_TRUE when succeeded, KII_FALSE when failed. If returned value is KII_FALSE and error is not NULL, this SDK set error information to the error. This function does not set KII_THING_IF_ERROR_INVALID_STATE to kii_thing_if_error_t::code.

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 *	firmware_version,
		const char *	layout_position,
		const char *	thing_properties,
		kii_thing_if_error_t *	error
	)

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.

After this functions succeeded, kii_thing_if_t::state becomes KII_THING_IF_STATE_ONBOARDED.

Parameters

[in,out]	kii_thing_if	This SDK instance.
[in]	vendor_thing_id	Vendor thing id given by thing vendor. Must not be NULL and empty string.
[in]	password	Password of the thing given by thing vendor. Must not be NULL and empty string.
[in]	thing_type	Type of the thing. If the thing is already registered, this value would be ignored by Kii Cloud. If this value is NULL or empty string, this value is ignored.
[in]	firmware_version	Firmware version of the thing. If the thing is already registered, this value would be ignored by Kii Cloud. If this value is NULL or empty string this value is ignored.
[in]	layout_position	Layout position of the thing. Should be one of "STANDALONE", "GATEWAY" or "ENDNODE". If the thing is already registered, this value would be ignored by Kii Cloud. If this value is NULL or empty string and the thing is not registered yet, then "STANDALONE" is used as default.
[in]	thing_properties	Other 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 value would be ignored by Kii Cloud. If this value is NULL or empty string this value is ignored.

Returns: KII_TRUE when succeeded, KII_FALSE when failed. If returned value is KII_FALSE and error is not NULL, this SDK set error information to the error. This function does not set KII_THING_IF_ERROR_INVALID_STATE to kii_thing_if_error_t::code.

kii_bool_t start ( kii_thing_if_t * kii_thing_if )

Start kii_thing_if_t instance.

thing-if ThingSDK starts to receive command and update states with this function.

This function must be called after one of following functions

After this functions succeeded, kii_thing_if_t::state becomes KII_THING_IF_STATE_STARTED.

Parameters

[in] kii_thing_if_t This SDK instance.

Returns: KII_TRUE when succeeded, KII_FALSE when failed.

kii_bool_t update_firmware_version	(	kii_thing_if_t *	kii_thing_if,
		const char *	firmware_version,
		kii_thing_if_error_t *	error
	)

Upate firmware version of a thing.

This function must be called between start and one of following functions:

Parameters

[in]	kii_thing_if_t	This SDK instance.
[in]	firmware_version	firmware version to update.
[out]	error	Error infomation. This is optional. If NULL, error information is not set.

Returns: KII_TRUE when succeeded, KII_FALSE when failed. If returned value is KII_FALSE and error is not NULL, this SDK set error information to the error.

kii_bool_t update_thing_type	(	kii_thing_if_t *	kii_thing_if,
		const char *	thing_type,
		kii_thing_if_error_t *	error
	)

Upate thing type of a thing.

This function must be called between start and one of following functions:

Parameters

[in]	kii_thing_if_t	This SDK instance.
[in]	thing_type	thing type to update.
[out]	error	Error infomation. This is optional. If NULL, error information is not set.

Returns: KII_TRUE when succeeded, KII_FALSE when failed. If returned value is KII_FALSE and error is not NULL, this SDK set error information to the error.

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation