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]	schema	name of schema. [in] schema_version version of schema.
[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 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 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_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.

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_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_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_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
	)

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_if	kii this SDK instance.
[in]	thing_id	thing id issued by Kii Cloud. NonNull, NonEmpty value must be specified.
[in]	password	password 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_if	kii this SDK instance.
[in]	vendor_thing_id	vendor thing id given by thing vendor. NonNull, NonEmpty value must be specified.
[in]	password	password of the thing given by thing vendor. NonNull, NonEmpty value must be specified.
[in]	thing_type	type of the thing. If the thing is already registered, this argument is ignored. If NULL the argument is ignored.
[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 argument is ignored. If NULL the argument is ignored.

Returns

KII_TRUE when succeeded, KII_FALSE when failed.