tio.h File Reference

#include "kii.h"
#include "khc.h"
#include "jkii.h"

Go to the source code of this file.

Data Structures
struct	tio_action_value_t
	Represents value of the action. More...
struct	tio_action_t
	Represents action. More...
struct	tio_action_err_t
	Represents error. More...
struct	tio_action_result_data_t
	Represents action result data. More...
struct	tio_handler_t
	Stores data/ callbacks used by tio_handler. More...
struct	tio_handler_task_info_t
	Indicates handler state. More...
struct	tio_updater_t
	Stores data/ callbacks used by tio_updater. More...

Typedefs
typedef kii_bool_t	tio_bool_t
	Boolean type. More...
typedef kii_author_t	tio_author_t
	Author of API. More...
typedef enum tio_code_t	tio_code_t
	Error Codes used in tio. More...
typedef enum tio_data_type_t	tio_data_type_t
	Data types. More...
typedef struct tio_action_value_t	tio_action_value_t
	Represents value of the action. More...
typedef struct tio_action_t	tio_action_t
	Represents action. More...
typedef struct tio_action_err_t	tio_action_err_t
	Represents error. More...
typedef struct tio_action_result_data_t	tio_action_result_data_t
	Represents action result data. More...
typedef size_t(*	TIO_CB_SIZE) (void *userdata)
	Callback asks for size of the state to be uploaded. More...
typedef size_t(*	TIO_CB_READ) (char *buffer, size_t size, void *userdata)
	Callback reads state. More...
typedef tio_bool_t(*	TIO_CB_ACTION) (tio_action_t *action, tio_action_err_t *err, tio_action_result_data_t *data, void *userdata)
	Callback handles action. More...
typedef void(*	TIO_CB_ERR) (tio_code_t code, const char *err_message, void *userdata)
	Callback propagates error information. More...
typedef tio_bool_t(*	TIO_CB_PUSH) (const char *message, size_t message_length, void *userdata)
	Callback handles custom push notification. More...
typedef struct tio_handler_t	tio_handler_t
	Stores data/ callbacks used by tio_handler. More...
typedef struct tio_updater_t	tio_updater_t
	Stores data/ callbacks used by tio_updater. More...
typedef void(*	TIO_CB_PARSED_ACTION) (char *command_id, tio_action_t *action, void *userdata)
	Callback handles parsed action. More...

Enumerations
enum	tio_code_t {   TIO_ERR_OK, TIO_ERR_SOCK_CONNECT, TIO_ERR_SOCK_SEND, TIO_ERR_SOCK_RECV,   TIO_ERR_SOCK_CLOSE, TIO_ERR_WRITE_CALLBACK, TIO_ERR_HEADER_CALLBACK, TIO_ERR_ALLOCATION,   TIO_ERR_TOO_LARGE_DATA, TIO_ERR_RESP_STATUS, TIO_ERR_PARSE_JSON, TIO_ERR_CREATE_TASK,   TIO_ERR_FAIL }
	Error Codes used in tio. More...
enum	tio_data_type_t {   TIO_TYPE_NULL, TIO_TYPE_BOOLEAN, TIO_TYPE_INTEGER, TIO_TYPE_DOUBLE,   TIO_TYPE_STRING, TIO_TYPE_OBJECT, TIO_TYPE_ARRAY }
	Data types. More...

Functions
void	tio_handler_init (tio_handler_t *handler)
	tio_handler_t initializer. More...
void	tio_handler_set_cb_sock_connect_http (tio_handler_t *handler, KHC_CB_SOCK_CONNECT cb_connect, void *userdata)
	Set socket connect callback used for HTTP(S) More...
void	tio_handler_set_cb_sock_send_http (tio_handler_t *handler, KHC_CB_SOCK_SEND cb_send, void *userdata)
	Set socket send callback used for HTTP(S) More...
void	tio_handler_set_cb_sock_recv_http (tio_handler_t *handler, KHC_CB_SOCK_RECV cb_recv, void *userdata)
	Set socket recv callback used for HTTP(S) More...
void	tio_handler_set_cb_sock_close_http (tio_handler_t *handler, KHC_CB_SOCK_CLOSE cb_close, void *userdata)
	Set socket close callback used for HTTP(S) More...
void	tio_handler_set_http_buff (tio_handler_t *handler, char *buff, size_t buff_size)
	Set buffer used to construct/ parse HTTP request/ response. More...
void	tio_handler_set_stream_buff (tio_handler_t *handler, char *buff, size_t buff_size)
	Set stream buffer. Stream buffer is used store part of HTTP body when reading/ writing it from the network. More...
void	tio_handler_set_resp_header_buff (tio_handler_t *handler, char *buff, size_t buff_size)
	Set response header buffer. More...
void	tio_handler_set_cb_sock_connect_mqtt (tio_handler_t *handler, KHC_CB_SOCK_CONNECT cb_connect, void *userdata)
	Set socket connect callback used for MQTT(S) More...
void	tio_handler_set_cb_sock_send_mqtt (tio_handler_t *handler, KHC_CB_SOCK_SEND cb_send, void *userdata)
	Set socket send callback used for MQTT(S) More...
void	tio_handler_set_cb_sock_recv_mqtt (tio_handler_t *handler, KHC_CB_SOCK_RECV cb_recv, void *userdata)
	Set socket recv callback used for MQTT(S) More...
void	tio_handler_set_cb_sock_close_mqtt (tio_handler_t *handler, KHC_CB_SOCK_CLOSE cb_close, void *userdata)
	Set socket close callback used for MQTT(S) More...
void	tio_handler_set_mqtt_to_sock_recv (tio_handler_t *handler, unsigned int to_sock_recv_sec)
	Set timeout of receiving data from socket user for MQTT(S) More...
void	tio_handler_set_mqtt_to_sock_send (tio_handler_t *handler, unsigned int to_sock_send_sec)
	Set timeout of sending data from socket user for MQTT(S) More...
void	tio_handler_set_cb_task_create (tio_handler_t *handler, KII_CB_TASK_CREATE cb_task_create, void *userdata)
	Set callback creates task. More...
void	tio_handler_set_cb_task_continue (tio_handler_t *handler, KII_CB_TASK_CONTINUE cb_continue, void *userdata)
	Set callback determines whether to continue or discontinue task. More...
void	tio_handler_set_cb_task_exit (tio_handler_t *handler, KII_CB_TASK_EXIT cb_exit, void *userdata)
	Callback called right before exit of tio_handler task. More...
void	tio_handler_set_cb_delay_ms (tio_handler_t *handler, KII_CB_DELAY_MS cb_delay_ms, void *userdata)
	Callback asks to delay/ sleep task execution. More...
void	tio_handler_set_cb_err (tio_handler_t *handler, TIO_CB_ERR cb_err, void *userdata)
	Set callback propagates error. You can use it for debugging, etc or you can skip calling this API. More...
void	tio_handler_set_cb_push (tio_handler_t *handler, TIO_CB_PUSH cb_push, void *userdata)
	Set callback handles custom push message. More...
void	tio_handler_set_mqtt_buff (tio_handler_t *handler, char *buff, size_t buff_size)
	Set buffer used to parse MQTT message. More...
void	tio_handler_set_keep_alive_interval (tio_handler_t *handler, size_t keep_alive_interval_sec)
	Set MQTT Keep-Alive interval. More...
void	tio_handler_set_app (tio_handler_t *handler, const char *app_id, const char *host)
	Set app identifier and host. More...
void	tio_handler_set_json_parser_resource (tio_handler_t *handler, jkii_resource_t *resource)
	Set JSON parser resource. More...
void	tio_handler_set_cb_json_parser_resource (tio_handler_t *handler, JKII_CB_RESOURCE_ALLOC cb_alloc, JKII_CB_RESOURCE_FREE cb_free)
	JSON parser resource callbacks. More...
void	tio_handler_set_cb_slist_resource (tio_handler_t *handler, KHC_CB_SLIST_ALLOC cb_alloc, KHC_CB_SLIST_FREE cb_free, void *cb_alloc_data, void *cb_free_data)
	Set custom memory allocator for the linked list used to constuct request headers of HTTP. More...
void	tio_handler_enable_insecure_http (tio_handler_t *handler, tio_bool_t enable_insecure_http)
	Enable insecure HTTP connection. More...
void	tio_handler_enable_insecure_mqtt (tio_handler_t *handler, tio_bool_t enable_insecure_mqtt)
	Enable insecure MQTT connection. More...
tio_code_t	tio_handler_onboard (tio_handler_t *handler, const char *vendor_thing_id, const char *password, const char *thing_type, const char *firmware_version, const char *layout_position, const char *thing_properties)
	Execute onboarding. More...
const tio_author_t *	tio_handler_get_author (tio_handler_t *handler)
	Get author. More...
tio_code_t	tio_handler_start (tio_handler_t *handler, const tio_author_t *author, TIO_CB_ACTION cb_action, void *userdata)
	Start tio_handler task. More...
tio_code_t	tio_handler_handle_command (tio_handler_t *handler, const char *command, size_t command_length, TIO_CB_ACTION cb_action, void *userdata)
	Handle the command. More...
tio_code_t	tio_handler_parse_command (tio_handler_t *handler, const char *command, size_t command_length, TIO_CB_PARSED_ACTION cb_parsed_action, void *userdata)
	Parse the received command. More...
void	tio_updater_init (tio_updater_t *updater)
	tio_updater_t initializer. More...
void	tio_updater_set_cb_sock_connect (tio_updater_t *updater, KHC_CB_SOCK_CONNECT cb_connect, void *userdata)
	Set socket connect callback used for HTTP(S) More...
void	tio_updater_set_cb_sock_send (tio_updater_t *updater, KHC_CB_SOCK_SEND cb_send, void *userdata)
	Set socket send callback used for HTTP(S) More...
void	tio_updater_set_cb_sock_recv (tio_updater_t *updater, KHC_CB_SOCK_RECV cb_recv, void *userdata)
	Set socket recv callback used for HTTP(S) More...
void	tio_updater_set_cb_sock_close (tio_updater_t *updater, KHC_CB_SOCK_CLOSE cb_close, void *userdata)
	Set socket close callback used for HTTP(S) More...
void	tio_updater_set_cb_task_create (tio_updater_t *updater, KII_CB_TASK_CREATE cb_task_create, void *userdata)
	Set callback creates task. More...
void	tio_updater_set_cb_task_continue (tio_updater_t *updater, KII_CB_TASK_CONTINUE cb_continue, void *userdata)
	Set callback determines whether to continue or discontinue task. More...
void	tio_updater_set_cb_task_exit (tio_updater_t *updater, KII_CB_TASK_EXIT cb_exit, void *userdata)
	Callback called right before exit of tio_updater task. More...
void	tio_updater_set_cb_delay_ms (tio_updater_t *updater, KII_CB_DELAY_MS cb_delay_ms, void *userdata)
	Callback asks to delay/ sleep task execution. More...
void	tio_updater_set_cb_error (tio_updater_t *updater, TIO_CB_ERR cb_err, void *userdata)
	Set callback propagates error. You can use it for debugging, etc or you can skip calling this API. More...
void	tio_updater_set_buff (tio_updater_t *updater, char *buff, size_t buff_size)
	Set buffer used to construct/ parse HTTP request/ response. More...
void	tio_updater_set_stream_buff (tio_updater_t *updater, char *buff, size_t buff_size)
	Set stream buffer. Stream buffer is used store part of HTTP body when reading/ writing it from the network. More...
void	tio_updater_set_resp_header_buff (tio_updater_t *updater, char *buff, size_t buff_size)
	Set response header buffer. More...
void	tio_updater_set_app (tio_updater_t *updater, const char *app_id, const char *host)
	Set app identifier and host. More...
void	tio_updater_set_interval (tio_updater_t *updater, size_t update_interval_sec)
	Set interval of updating state. More...
void	tio_updater_set_json_parser_resource (tio_updater_t *updater, jkii_resource_t *resource)
void	tio_updater_set_cb_json_parser_resource (tio_updater_t *updater, JKII_CB_RESOURCE_ALLOC cb_alloc, JKII_CB_RESOURCE_FREE cb_free)
void	tio_updater_set_cb_slist_resource (tio_updater_t *updater, KHC_CB_SLIST_ALLOC cb_alloc, KHC_CB_SLIST_FREE cb_free, void *cb_alloc_data, void *cb_free_data)
	Set custom memory allocator for the linked list used to constuct request headers of HTTP. More...
void	tio_updater_enable_insecure_http (tio_updater_t *updater, tio_bool_t enable_insecure_http)
	Enable insecure HTTP connection. More...
tio_code_t	tio_updater_onboard (tio_updater_t *updater, const char *vendor_thing_id, const char *password, const char *thing_type, const char *firmware_version, const char *layout_position, const char *thing_properties)
	Execute onboarding. More...
const tio_author_t *	tio_updater_get_author (tio_updater_t *updater)
	Get author. More...
tio_code_t	tio_updater_start (tio_updater_t *updater, const tio_author_t *author, TIO_CB_SIZE cb_state_size, void *state_size_data, TIO_CB_READ cb_read_state, void *read_state_data)
	Start tio_updater task. More...

Variables
const char	TIO_TASK_NAME_UPDATE_STATE []
	tio_updater Task name. More...

Typedef Documentation

tio_action_err_t

typedef struct tio_action_err_t tio_action_err_t

Represents error.

tio_action_result_data_t

typedef struct tio_action_result_data_t tio_action_result_data_t

Represents action result data.

tio_action_t

typedef struct tio_action_t tio_action_t

Represents action.

tio_action_value_t

typedef struct tio_action_value_t tio_action_value_t

Represents value of the action.

tio_author_t

typedef kii_author_t tio_author_t

Author of API.

tio_bool_t

typedef kii_bool_t tio_bool_t

Boolean type.

TIO_CB_ACTION

typedef tio_bool_t(* TIO_CB_ACTION) (tio_action_t *action, tio_action_err_t *err, tio_action_result_data_t *data, void *userdata)

Callback handles action.

Called when received remote control command from cloud or tio_handler_handle_command is invoked. Command may includes multiple actions. The callback is called per action.

Parameters

[in]	action	Includes alias_name, action_name and action value.
[out]	err	Implementation can set error when the given action is failed to execute.
[out]	data	Implementation can set data as json string. Reported error is recoreded in cloud. When succeeded, the argument can be ignored.
[in,out]	userdata	Context object pointer given to tio_handler_start().

TIO_CB_ERR

typedef void(* TIO_CB_ERR) (tio_code_t code, const char *err_message, void *userdata)

Callback propagates error information.

Called when error occurred. Can be used for debugging and implementation is optional.

Parameters

[in]	code	Error code.
[in]	err_message	Error message.
[in,out]	userdata	Context object pointer passed to tio_handler_set_cb_err()/ tio_updater_set_cb_err().

TIO_CB_PARSED_ACTION

typedef void(* TIO_CB_PARSED_ACTION) (char *command_id, tio_action_t *action, void *userdata)

Callback handles parsed action.

Called when tio_handler_parse_command is called. Command may includes multiple actions. The callback is called per action.

Parameters

[in]	command_id	Command ID of parsed command, your app can use it to update action result.
[in]	action	Includes alias_name, action_name and action value.
[in,out]	userdata	Context object pointer given to tio_handler_parse_command.

TIO_CB_PUSH

typedef tio_bool_t(* TIO_CB_PUSH) (const char *message, size_t message_length, void *userdata)

Callback handles custom push notification.

By default tio_handler handles remote controll command and ignores other kind of messages. If you send message to the devices other than remote controll command, you can use this callback to handle them. This callback is called before TIO_CB_ACTION callback, and if it returns KII_TRUE, tio_handler skips parsing message as remote controll command and TIO_CB_ACTION callback won't be called. if it returns KII_FALSE, tio_handler try to parse message as remote controll command and call TIO_CB_ACTION callback as well if the message is remote controll command. If you only needs to handle remote contoll command, you don't have to implement this callback and call tio_handler_set_cb_push().

Parameters

[in]	message	Push message received from cloud. Could be remote controll command or other message sent by Kii Topic/ Kii Bucket subscription.
[in]	message_length	Length of the message.
[in,out]	userdata	Context object pointer passed to tio_handler_set_cb_push().

Returns

KII_TRUE results skip handling message as remote controll command, KII_FALSE results try to handle message as remote controll command.

TIO_CB_READ

typedef size_t(* TIO_CB_READ) (char *buffer, size_t size, void *userdata)

Callback reads state.

This callback would be called mutiple times until it returns 0. Implementation should keep track of the total size already read and write rest data to the buffer.

Parameters

[out]	buffer	Implementation must write the part of the state sequentially.
[in]	size	Size of the buffer.
[in,out]	userdata	Context object pointer passed to tio_updater_start().

Returns

size of the state read. Returning 0 is required when all state has been read.

TIO_CB_SIZE

typedef size_t(* TIO_CB_SIZE) (void *userdata)

Callback asks for size of the state to be uploaded.

Parameters

[in,out]

userdata

Context object pointer passed to tio_updater_start().

Returns

size of the state to be uploaded. if 0, TIO_CB_READ callback passed to tio_updater_start() is not called.

tio_code_t

typedef enum tio_code_t tio_code_t

Error Codes used in tio.

tio_data_type_t

typedef enum tio_data_type_t tio_data_type_t

Data types.

Same as JSON data types except for having Integer and Double instead of Number.

tio_handler_t

typedef struct tio_handler_t tio_handler_t

Stores data/ callbacks used by tio_handler.

tio_updater_t

typedef struct tio_updater_t tio_updater_t

Stores data/ callbacks used by tio_updater.

Enumeration Type Documentation

tio_code_t

enum tio_code_t

Error Codes used in tio.

Enumerator
TIO_ERR_OK	Succeeded.
TIO_ERR_SOCK_CONNECT	Socket error in connection.
TIO_ERR_SOCK_SEND	Socket error in sending data.
TIO_ERR_SOCK_RECV	Socket error in receiving data.
TIO_ERR_SOCK_CLOSE	Socket error in closing.
TIO_ERR_WRITE_CALLBACK	Error in write callback.
TIO_ERR_HEADER_CALLBACK	Error in header callback.
TIO_ERR_ALLOCATION	Error in memory allocation.
TIO_ERR_TOO_LARGE_DATA	Data is larger than expected.
TIO_ERR_RESP_STATUS	REST API returns error status code.
TIO_ERR_PARSE_JSON	Error in parsing JSON.
TIO_ERR_CREATE_TASK	Error in creating task.
TIO_ERR_FAIL	Other errors.

tio_data_type_t

enum tio_data_type_t

Data types.

Same as JSON data types except for having Integer and Double instead of Number.

Enumerator
TIO_TYPE_NULL	NULL type.
TIO_TYPE_BOOLEAN	Boolean type.
TIO_TYPE_INTEGER	Integer type.
TIO_TYPE_DOUBLE	Double type.
TIO_TYPE_STRING	String type.
TIO_TYPE_OBJECT	Object type.
TIO_TYPE_ARRAY	Array type.

Function Documentation

tio_handler_enable_insecure_http()

void tio_handler_enable_insecure_http	(	tio_handler_t *	handler,
		tio_bool_t	enable_insecure_http
	)

Enable insecure HTTP connection.

HTTP over ssl/tls is used by default. If you need to use HTTP over plain tcp, you need to call this method.

Parameters

[out]	handler	tio_handler_t instance.
[in]	enable_insecure_http	KII_TRUE indicates using insecure connection.

tio_handler_enable_insecure_mqtt()

void tio_handler_enable_insecure_mqtt	(	tio_handler_t *	handler,
		tio_bool_t	enable_insecure_mqtt
	)

Enable insecure MQTT connection.

MQTT over ssl/tls is used by default. If you need to use MQTT over plain tcp, you need to call this method.

Parameters

[out]	handler	tio_handler_t instance.
[in]	enable_insecure_mqtt	KII_TRUE indicates using insecure connection.

tio_handler_get_author()

const tio_author_t* tio_handler_get_author

(

tio_handler_t *

handler

)

Get author.

Author is used to authorize API call and consists of device ID and access token. This API must be called after the successful execution of tio_handler_onboard().

Parameters

[in]

handler

tio_handler_t instance.

Returns

tio_author_t pointer. You may need to copy the value of device ID and access token and store them.

tio_handler_handle_command()

tio_code_t tio_handler_handle_command	(	tio_handler_t *	handler,
		const char *	command,
		size_t	command_length,
		TIO_CB_ACTION	cb_action,
		void *	userdata
	)

Handle the command.

Basically, your app doesn't need to use this method. Since tio_handler automatically invokes this method when it received a command then after all the TIO_CB_ACTION callbacks invoked, it responds to the command synchronously.

In the case, your app needs to handle command asynchronously. Your app can receive the command in the TIO_CB_PUSH callback, and then use tio_handler_parse_command to handle each action asynchronously. Your app should return KII_TRUE to the TIO_CB_PUSH callback to skip automatically command handling logic. When your app is ready to respond to the command, then invoke this method.

When app invokes the method, TIO_CB_ACTION callback is invoked. Command may includes multiple actions. The callback TIO_CB_ACTION is invoked per action.

Parameters

[in]	handler	tio_handler_t instance.
[in]	command	received command.
[in]	command_length	Size of command.
[in]	cb_action	Action callback.
[in]	userdata	Context object pointer passed to cb_action.

tio_handler_init()

void tio_handler_init

(

tio_handler_t *

handler

)

tio_handler_t initializer.

Must be called when start using tio_handler_t instance.

Parameters

[out]

handler

tio_handler_t instance.

tio_handler_onboard()

tio_code_t tio_handler_onboard	(	tio_handler_t *	handler,
		const char *	vendor_thing_id,
		const char *	password,
		const char *	thing_type,
		const char *	firmware_version,
		const char *	layout_position,
		const char *	thing_properties
	)

Execute onboarding.

Onboarding step is required to register device to IoT cloud and obtain access token. Once the device is registered and IoT cloud publishes device ID and access token, You can skip this process and call tio_handler_start()/ tio_updater_start(). After the successfull execution, you can obtain device ID and access token via tio_handler_get_author() API.

Note: input params other than vendor_thing_id and password are ignored after the first registration.

Parameters

[out]	handler	tio_handler_t instance.
[in]	vendor_thing_id	Unique ID determined by device vendor.
[in]	password	Password of the device.
[in]	thing_type	Type of the device.
[in]	firmware_version	Firmware version of the device.
[in]	layout_position	You'll set NULL and STAND_ALONE is chosen. Other position won't be used.
[in]	thing_properties	Properties of thing. Expect JSON object include custom properties defined by Vendor. Can be NULL if you don't need them.

tio_handler_parse_command()

tio_code_t tio_handler_parse_command	(	tio_handler_t *	handler,
		const char *	command,
		size_t	command_length,
		TIO_CB_PARSED_ACTION	cb_parsed_action,
		void *	userdata
	)

Parse the received command.

If the received command needs to be handled asynchronously, and your app doesn't respond the command immediately. You can this method to only parse the command, then handle each action separately in TIO_CB_PARSED_ACTION callback. After all the actions are handled, and it is ready to respond the command, your app can call tio_handler_handle_command to respond command to server.

Parameters

[in]	handler	tio_handler_t instance.
[in]	command	Received command.
[in]	command_length	Length of received command.
[in]	cb_parsed_action	TIO_CB_PARSED_ACTION callback called when parsed a action.
[in]	userdata	Context object pointer passed to cb_parsed_action.

Returns

TIO_ERR_OK when succeeded to parse the command.

tio_handler_set_app()

void tio_handler_set_app	(	tio_handler_t *	handler,
		const char *	app_id,
		const char *	host
	)

Set app identifier and host.

Parameters

[out]	handler	tio_handler_t instance.
[in]	app_id	Application ID published by Cloud.
[in]	host	Host tied to the application.

tio_handler_set_cb_delay_ms()

void tio_handler_set_cb_delay_ms	(	tio_handler_t *	handler,
		KII_CB_DELAY_MS	cb_delay_ms,
		void *	userdata
	)

Callback asks to delay/ sleep task execution.

Called when the task needs to delay/ sleep.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_delay_ms	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_delay_ms.

tio_handler_set_cb_err()

void tio_handler_set_cb_err	(	tio_handler_t *	handler,
		TIO_CB_ERR	cb_err,
		void *	userdata
	)

Set callback propagates error. You can use it for debugging, etc or you can skip calling this API.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_err	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_err.

tio_handler_set_cb_json_parser_resource()

void tio_handler_set_cb_json_parser_resource	(	tio_handler_t *	handler,
		JKII_CB_RESOURCE_ALLOC	cb_alloc,
		JKII_CB_RESOURCE_FREE	cb_free
	)

JSON parser resource callbacks.

Set JSON parser resource callback. If you choose to allocate memory statically, you can call tio_handler_set_json_parser_resource() instead.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_alloc	allocation callback.
[in]	cb_free	free callback.

tio_handler_set_cb_push()

void tio_handler_set_cb_push	(	tio_handler_t *	handler,
		TIO_CB_PUSH	cb_push,
		void *	userdata
	)

Set callback handles custom push message.

In case you don't use costom push message, you can skip calling this API.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_push	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_cb_push.

tio_handler_set_cb_slist_resource()

void tio_handler_set_cb_slist_resource	(	tio_handler_t *	handler,
		KHC_CB_SLIST_ALLOC	cb_alloc,
		KHC_CB_SLIST_FREE	cb_free,
		void *	cb_alloc_data,
		void *	cb_free_data
	)

Set custom memory allocator for the linked list used to constuct request headers of HTTP.

If this method is not called, default memory allocator using malloc/ free is used.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_alloc	Allocation callback function pointer.
[in]	cb_free	Free callback function pointer.
[in]	cb_alloc_data	Context object pointer passed to cb_alloc.
[in]	cb_free_data	Context object pointer passed to cb_free.

tio_handler_set_cb_sock_close_http()

void tio_handler_set_cb_sock_close_http	(	tio_handler_t *	handler,
		KHC_CB_SOCK_CLOSE	cb_close,
		void *	userdata
	)

Set socket close callback used for HTTP(S)

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_close	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_close.

tio_handler_set_cb_sock_close_mqtt()

void tio_handler_set_cb_sock_close_mqtt	(	tio_handler_t *	handler,
		KHC_CB_SOCK_CLOSE	cb_close,
		void *	userdata
	)

Set socket close callback used for MQTT(S)

Note that socket used for MQTT must be blocking-mode and its recv/send timeout must be set by tio_handler_set_mqtt_to_sock_recv()/ tio_handler_set_mqtt_to_sock_send() APIs. It is necessary for sending pingReq message periodically to achieve Keep-Alive since we don't require system clock APIs abstraction.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_close	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_close.

tio_handler_set_cb_sock_connect_http()

void tio_handler_set_cb_sock_connect_http	(	tio_handler_t *	handler,
		KHC_CB_SOCK_CONNECT	cb_connect,
		void *	userdata
	)

Set socket connect callback used for HTTP(S)

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_connect	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_connect.

tio_handler_set_cb_sock_connect_mqtt()

void tio_handler_set_cb_sock_connect_mqtt	(	tio_handler_t *	handler,
		KHC_CB_SOCK_CONNECT	cb_connect,
		void *	userdata
	)

Set socket connect callback used for MQTT(S)

Note that socket used for MQTT must be blocking-mode and its recv/send timeout must be set by tio_handler_set_mqtt_to_sock_recv()/ tio_handler_set_mqtt_to_sock_send() APIs. It is necessary for sending pingReq message periodically to achieve Keep-Alive since we don't require system clock APIs abstraction.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_connect	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_connect.

tio_handler_set_cb_sock_recv_http()

void tio_handler_set_cb_sock_recv_http	(	tio_handler_t *	handler,
		KHC_CB_SOCK_RECV	cb_recv,
		void *	userdata
	)

Set socket recv callback used for HTTP(S)

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_recv	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_recv.

tio_handler_set_cb_sock_recv_mqtt()

void tio_handler_set_cb_sock_recv_mqtt	(	tio_handler_t *	handler,
		KHC_CB_SOCK_RECV	cb_recv,
		void *	userdata
	)

Set socket recv callback used for MQTT(S)

Note that socket used for MQTT must be blocking-mode and its recv/send timeout must be set by tio_handler_set_mqtt_to_sock_recv()/ tio_handler_set_mqtt_to_sock_send() APIs. It is necessary for sending pingReq message periodically to achieve Keep-Alive since we don't require system clock APIs abstraction.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_recv	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_recv.

tio_handler_set_cb_sock_send_http()

void tio_handler_set_cb_sock_send_http	(	tio_handler_t *	handler,
		KHC_CB_SOCK_SEND	cb_send,
		void *	userdata
	)

Set socket send callback used for HTTP(S)

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_send	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_send.

tio_handler_set_cb_sock_send_mqtt()

void tio_handler_set_cb_sock_send_mqtt	(	tio_handler_t *	handler,
		KHC_CB_SOCK_SEND	cb_send,
		void *	userdata
	)

Set socket send callback used for MQTT(S)

Note that socket used for MQTT must be blocking-mode and its recv/send timeout must be set by tio_handler_set_mqtt_to_sock_recv()/ tio_handler_set_mqtt_to_sock_send() APIs. It is necessary for sending pingReq message periodically to achieve Keep-Alive since we don't require system clock APIs abstraction.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_send	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_send.

tio_handler_set_cb_task_continue()

void tio_handler_set_cb_task_continue	(	tio_handler_t *	handler,
		KII_CB_TASK_CONTINUE	cb_continue,
		void *	userdata
	)

Set callback determines whether to continue or discontinue task.

If this method is not called or NULL is set, task exits only when un-recoverble error occurs. If you need cancellation mechanism, you need to set this callback. Terminate task without using this callback may cause memory leak. This method must be called before calling tio_handler_start().

In case checking cancellation flag in continue_cb, the flag might be set by other task/ thread. Implementation must ensure consistency of the flag by using Mutex, etc.

If un-recoverble error occurs, task exits the infinite loop and immediately calls KII_CB_TASK_EXIT callback if set. In this case KII_CB_TASK_CONTINUE callback is not called.

Parameters

[out]	handler	tio_handler_t instance
[in]	cb_continue	Callback determines whether to continue or discontinue task. If continue_cb returns KII_TRUE, task continues. Otherwise the task exits the infinite loop and calls KII_CB_TASK_EXIT callback if set. task_info argument type of the cb_continue (defined as void* in KII_CB_TASK_CONTINUE) is tio_handler_task_info*.
[in]	userdata	Context data pointer passed as second argument when cb_continue is called.

tio_handler_set_cb_task_create()

void tio_handler_set_cb_task_create	(	tio_handler_t *	handler,
		KII_CB_TASK_CREATE	cb_task_create,
		void *	userdata
	)

Set callback creates task.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_task_create	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_task_create.

tio_handler_set_cb_task_exit()

void tio_handler_set_cb_task_exit	(	tio_handler_t *	handler,
		KII_CB_TASK_EXIT	cb_exit,
		void *	userdata
	)

Callback called right before exit of tio_handler task.

Task exits when the task is discontinued by KII_CB_TASK_CONTINUE callback or un-recoverble error occurs. In exit_cb, you'll need to free memory used for buffers set by following APIs

• tio_handler_set_http_buff(),
• tio_handler_set_stream_buff(),
• tio_handler_set_resp_header_buff()
• tio_handler_set_mqtt_buff(), and memory used for the userdata passed to following callbacks in case not yet freed.
• tio_handler_set_cb_sock_connect_http()
• tio_handler_set_cb_sock_send_http()
• tio_handler_set_cb_sock_recv_http()
• tio_handler_set_cb_sock_close_http()
• tio_handler_set_cb_sock_connect_mqtt()
• tio_handler_set_cb_sock_send_mqtt()
• tio_handler_set_cb_sock_recv_mqtt()
• tio_handler_set_cb_sock_close_mqtt()
• tio_handler_set_cb_task_continue()
• tio_handler_set_cb_task_exit()

In addition, you may need to call task/ thread termination API. It depends on the task/ threading framework you used to create task/ thread. After the exit_cb returned, task function immediately returns.

If this API is not called or set NULL, task function immediately returns when task is discontinued or un-recoverble error occurs.

Parameters

[out]	handler	tio_handler_t instance.
[in]	cb_exit	Called right before the exit. task_info argument type of cb_exit (defined as void* in KII_CB_TASK_EXIT) is tio_handler_task_info*
[in]	userdata	Context data pointer passed as second argument when cb_exit is called.

tio_handler_set_http_buff()

void tio_handler_set_http_buff	(	tio_handler_t *	handler,
		char *	buff,
		size_t	buff_size
	)

Set buffer used to construct/ parse HTTP request/ response.

This method must be called and set valid buffer before calling method before calling tio_handler_start(). The buffer is used to serialize/ deserialize JSON.

You can change the size of buffer depending on the request/ response size. Typically, 1024 bytes is enough. However it varies depending on your data schema used to define thing properties/ command. Avoid defining large thing properties/ command if you need to reduce memory usage.

Memory used by the buffer can be safely freed after you've terminated tio_handler task.

Parameters

[out]	handler	tio_handler_t instance.
[in]	buff	pointer to the buffer.
[in]	buff_size	size of the buffer.

tio_handler_set_json_parser_resource()

void tio_handler_set_json_parser_resource	(	tio_handler_t *	handler,
		jkii_resource_t *	resource
	)

Set JSON parser resource.

Set JSON parser resource. Required number of token depending on the remote controll command definition. If you choose to allocate memory dynamically, you can call tio_handler_set_cb_json_parser_resource() instead.

Parameters

[out]	handler	tio_handler_t instance.
[in]	resource	used to parse JSON.

tio_handler_set_keep_alive_interval()

void tio_handler_set_keep_alive_interval	(	tio_handler_t *	handler,
		size_t	keep_alive_interval_sec
	)

Set MQTT Keep-Alive interval.

Limitation: keep_alive_interval must be larger than socket recv/ send timeout set by tio_handler_set_mqtt_to_sock_recv() / tio_handler_set_mqtt_to_sock_send(). Twice as large as recv/ send timeout works fine but recommend few minutes to avoid congestion.

Parameters

[out]	handler	tio_handler_t instance.
[in]	keep_alive_interval_sec	Keep-Alive interval in seconds.

tio_handler_set_mqtt_buff()

void tio_handler_set_mqtt_buff	(	tio_handler_t *	handler,
		char *	buff,
		size_t	buff_size
	)

Set buffer used to parse MQTT message.

This method must be called and set valid buffer before calling method tio_handler_start() The buffer is used to parse MQTT message.

You can change the size of buffer depending on the request/ response size. It must be enough large to store whole message send by MQTT. Typically, 1024 bytes is enough. However it varies depending on your data schema used to define Commands. Avoid defining large Commands.

Memory used by the buffer can be safely freed after you've terminated tio_handler task.

Parameters

[out]	handler	tio_handler_t instance.
[in]	buff	pointer to the buffer.
[in]	buff_size	size of the buffer.

tio_handler_set_mqtt_to_sock_recv()

void tio_handler_set_mqtt_to_sock_recv	(	tio_handler_t *	handler,
		unsigned int	to_sock_recv_sec
	)

Set timeout of receiving data from socket user for MQTT(S)

This setting is mandatory to achieve MQTT keep-alive mechanism. We use timeout instead of requirering system clock access to periodically send pingReq. Socket recv implementation given to tio_handler_set_cb_sock_recv_mqtt() must have same timeout specified by to_sock_recv_sec.

Parameters

[out]	handler	tio_handler_t instance.
[in]	to_sock_recv_sec	Socket recv timeout in seconds.

tio_handler_set_mqtt_to_sock_send()

void tio_handler_set_mqtt_to_sock_send	(	tio_handler_t *	handler,
		unsigned int	to_sock_send_sec
	)

Set timeout of sending data from socket user for MQTT(S)

This setting is mandatory to achieve MQTT keep-alive mechanism. We use timeout instead of requirering system clock access to periodically send pingReq. Socket send implementation given to tio_handler_set_cb_sock_send_mqtt() must have same timeout specified by to_sock_send_sec.

Parameters

[out]	handler	tio_handler_t instance.
[in]	to_sock_send_sec	Socket send timeout in seconds.

tio_handler_set_resp_header_buff()

void tio_handler_set_resp_header_buff	(	tio_handler_t *	handler,
		char *	buff,
		size_t	buff_size
	)

Set response header buffer.

The buffer is used to store single HTTP response header. If this method is not called or set NULL to the buffer, tio_handler allocates memory of response header buffer when the HTTP session started and free when the HTTP session ends. The buffer allocated by tio_handler is 256 bytes.

If header is larger than the buffer, the header is skipped and not parsed. tio_handler needs to parse Status Line, Content-Length and Transfer-Encoding header. The buffer must have enough size to store those headers. 256 bytes would be enough. If you set the buffer by the method, the method must be called before calling tio_handler_start() and memory used by the buffer can be safely freed after you've terminated tio_handler task.

Parameters

[out]	handler	tio_handler_t instance.
[in]	buff	pointer to the buffer.
[in]	buff_size	size of the buffer.

tio_handler_set_stream_buff()

void tio_handler_set_stream_buff	(	tio_handler_t *	handler,
		char *	buff,
		size_t	buff_size
	)

Set stream buffer. Stream buffer is used store part of HTTP body when reading/ writing it from the network.

If this method is not called or set NULL to the buffer, tio_handler allocates memory of stream buffer when the HTTP session started and free when the HTTP session ends. The buffer allocated by tio_handler is 1024 bytes.

You can change the size of buffer depending on your request/ response size. It must be enough large to store size line in chunked encoded message. However, you may use much larger buffer since size line might require very small buffer as it consists of HEX size and CRLF for the better performance.

If you set the buffer by the method, the method must be called before tio_handler_start(). and memory used by the buffer can be safely freed after you've terminated tio_handler task.

Parameters

[out]	handler	tio_handler_t instance.
[in]	buff	pointer to the buffer.
[in]	buff_size	size of the buffer.

tio_handler_start()

tio_code_t tio_handler_start	(	tio_handler_t *	handler,
		const tio_author_t *	author,
		TIO_CB_ACTION	cb_action,
		void *	userdata
	)

Start tio_handler task.

You can start tio_handler task by this method. If the API returns TIO_ERR_OK, asynchronous task is started successfully and callbacks set by tio_handler setter methods and this method is called when corresponding event occurs.

Parameters

[in]	handler	tio_handler_t instance.
[in]	author	API author.
[in]	cb_action	Action callback called when received remote controll command.
[in]	userdata	Context object pointer passed to cb_action.

tio_updater_enable_insecure_http()

void tio_updater_enable_insecure_http	(	tio_updater_t *	updater,
		tio_bool_t	enable_insecure_http
	)

Enable insecure HTTP connection.

HTTP over ssl/tls is used by default. If you need to use HTTP over plain tcp, you need to call this method.

Parameters

[out]	handler	tio_handler_t instance.
[in]	enable_insecure_http	KII_TRUE indicates using insecure connection.

tio_updater_get_author()

const tio_author_t* tio_updater_get_author

(

tio_updater_t *

updater

)

Get author.

Author is used to authorize API call and consists of device ID and access token. This API must be called after the successful execution of tio_updater_onboard().

Parameters

[in]

updater

tio_updater_t instance.

Returns

tio_author_t pointer. You may need to copy the value of device ID and access token and store them.

tio_updater_init()

void tio_updater_init

(

tio_updater_t *

updater

)

tio_updater_t initializer.

Must be called when start using tio_updater_t instance.

Parameters

[out]

updater

tio_updater_t instance.

tio_updater_onboard()

tio_code_t tio_updater_onboard	(	tio_updater_t *	updater,
		const char *	vendor_thing_id,
		const char *	password,
		const char *	thing_type,
		const char *	firmware_version,
		const char *	layout_position,
		const char *	thing_properties
	)

Execute onboarding.

Onboarding step is required to register device to IoT cloud and obtain access token. Once the device is registered and IoT cloud publishes device ID and access token, You can skip this process and call tio_handler_start()/ tio_updater_start(). After the successfull execution, you can obtain device ID and access token via tio_updater_get_author() API.

Note: input params other than vendor_thing_id and password are ignored after the first registration.

Parameters

[out]	updater	tio_updater_t instance.
[in]	vendor_thing_id	Unique ID determined by device vendor.
[in]	password	Password of the device.
[in]	thing_type	Type of the device.
[in]	firmware_version	Firmware version of the device.
[in]	layout_position	You'll set NULL and STAND_ALONE is chosen. Other position won't be used.
[in]	thing_properties	Properties of thing. Expect JSON object include custom properties defined by Vendor. Can be NULL if you don't need them.

tio_updater_set_app()

void tio_updater_set_app	(	tio_updater_t *	updater,
		const char *	app_id,
		const char *	host
	)

Set app identifier and host.

Parameters

[out]	updater	tio_updater_t instance.
[in]	app_id	Application ID published by Cloud.
[in]	host	Host tied to the application.

tio_updater_set_buff()

void tio_updater_set_buff	(	tio_updater_t *	updater,
		char *	buff,
		size_t	buff_size
	)

Set buffer used to construct/ parse HTTP request/ response.

This method must be called and set valid buffer before calling method before calling tio_updater_start(). The buffer is used to serialize/ deserialize JSON.

You can change the size of buffer depending on the request/ response size. Typically, 1024 bytes is enough. Not that for uploading state, the buffer is not used and stream based TIO_CB_READ callback is used. You don't have to take account into the size of the state.

Memory used by the buffer can be safely freed after you've terminated tio_updater task.

Parameters

[out]	updater	tio_updater_t instance.
[in]	buff	pointer to the buffer.
[in]	buff_size	size of the buffer.

tio_updater_set_cb_delay_ms()

void tio_updater_set_cb_delay_ms	(	tio_updater_t *	updater,
		KII_CB_DELAY_MS	cb_delay_ms,
		void *	userdata
	)

Callback asks to delay/ sleep task execution.

Called when the task needs to delay/ sleep.

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_delay_ms	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_delay_ms.

tio_updater_set_cb_error()

void tio_updater_set_cb_error	(	tio_updater_t *	updater,
		TIO_CB_ERR	cb_err,
		void *	userdata
	)

Set callback propagates error. You can use it for debugging, etc or you can skip calling this API.

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_err	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_err.

tio_updater_set_cb_json_parser_resource()

void tio_updater_set_cb_json_parser_resource	(	tio_updater_t *	updater,
		JKII_CB_RESOURCE_ALLOC	cb_alloc,
		JKII_CB_RESOURCE_FREE	cb_free
	)

tio_updater_set_cb_slist_resource()

void tio_updater_set_cb_slist_resource	(	tio_updater_t *	updater,
		KHC_CB_SLIST_ALLOC	cb_alloc,
		KHC_CB_SLIST_FREE	cb_free,
		void *	cb_alloc_data,
		void *	cb_free_data
	)

Set custom memory allocator for the linked list used to constuct request headers of HTTP.

If this method is not called, default memory allocator using malloc/ free is used.

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_alloc	Allocation callback function pointer.
[in]	cb_free	Free callback function pointer.
[in]	cb_alloc_data	Context object pointer passed to cb_alloc.
[in]	cb_free_data	Context object pointer passed to cb_free.

tio_updater_set_cb_sock_close()

void tio_updater_set_cb_sock_close	(	tio_updater_t *	updater,
		KHC_CB_SOCK_CLOSE	cb_close,
		void *	userdata
	)

Set socket close callback used for HTTP(S)

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_close	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_close.

tio_updater_set_cb_sock_connect()

void tio_updater_set_cb_sock_connect	(	tio_updater_t *	updater,
		KHC_CB_SOCK_CONNECT	cb_connect,
		void *	userdata
	)

Set socket connect callback used for HTTP(S)

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_connect	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_connect.

tio_updater_set_cb_sock_recv()

void tio_updater_set_cb_sock_recv	(	tio_updater_t *	updater,
		KHC_CB_SOCK_RECV	cb_recv,
		void *	userdata
	)

Set socket recv callback used for HTTP(S)

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_recv	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_recv.

tio_updater_set_cb_sock_send()

void tio_updater_set_cb_sock_send	(	tio_updater_t *	updater,
		KHC_CB_SOCK_SEND	cb_send,
		void *	userdata
	)

Set socket send callback used for HTTP(S)

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_send	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_send.

tio_updater_set_cb_task_continue()

void tio_updater_set_cb_task_continue	(	tio_updater_t *	updater,
		KII_CB_TASK_CONTINUE	cb_continue,
		void *	userdata
	)

Set callback determines whether to continue or discontinue task.

If this method is not called or NULL is set, task won't exit. If you need cancellation mechanism, you need to set this callback. Terminate task without using this callback may cause memory leak. This method must be called before calling tio_updater_start().

In case checking cancellation flag in continue_cb, the flag might be set by other task/ thread. Implementation must ensure consistency of the flag by using Mutex, etc.

Parameters

[out]	updater	tio_updater_t instances
[in]	cb_continue	Callback determines whether to continue or discontinue task. If cb_continue returns KII_TRUE, task continues. Otherwise the task exits the infinite loop and calls KII_CB_TASK_EXIT callback if set. task_info argument of the cb_continue (defined as void* in KII_CB_TASK_CONTINUE) is always NULL.
[in]	userdata	Context data pointer passed as second argument when cb_continue is called.

tio_updater_set_cb_task_create()

void tio_updater_set_cb_task_create	(	tio_updater_t *	updater,
		KII_CB_TASK_CREATE	cb_task_create,
		void *	userdata
	)

Set callback creates task.

Parameters

[out]	updater	tio_updater_t instance.
[in]	cb_task_create	Callback function pointer.
[in]	userdata	Context object pointer passed to cb_task_create.

tio_updater_set_cb_task_exit()

void tio_updater_set_cb_task_exit	(	tio_updater_t *	updater,
		KII_CB_TASK_EXIT	cb_exit,
		void *	userdata
	)

Callback called right before exit of tio_updater task.

Task exits when the task is discontinued by KII_CB_TASK_CONTINUE callback. In exit_cb, you'll need to free memory used for buffers set by following APIs

• tio_updater_set_buff(),
• tio_updater_set_stream_buff(),
• tio_updater_set_resp_header_buff() and memory used for the userdata passed to following callbacks in case not yet freed.
• tio_updater_set_cb_sock_connect()
• tio_updater_set_cb_sock_send()
• tio_updater_set_cb_sock_recv()
• tio_updater_set_cb_sock_close()
• tio_updater_set_cb_task_continue()
• tio_updater_set_cb_task_exit()

In addition, you may need to call task/ thread termination API. It depends on the task/ threading framework you used to create task/ thread. After the exit_cb returned, task function immediately returns.

If this API is not called or set NULL, task function immediately returns when task is discontinued or un-recoverble error occurs.

Parameters

[out]	updater	tio_updater_t instance
[in]	cb_exit	Callback called right befor exit. task_info argument of the cb_exit (defind as void* in KII_CB_TASK_EXIT) function is always NULL.
[in]	userdata	Context data pointer passed as second argument when cb_exit is called.

tio_updater_set_interval()

void tio_updater_set_interval	(	tio_updater_t *	updater,
		size_t	update_interval_sec
	)

Set interval of updating state.

Parameters

[out]	updater	tio_updater_t instance.
[in]	update_interval_sec	Interval in seconds.

tio_updater_set_json_parser_resource()

void tio_updater_set_json_parser_resource	(	tio_updater_t *	updater,
		jkii_resource_t *	resource
	)

tio_updater_set_resp_header_buff()

void tio_updater_set_resp_header_buff	(	tio_updater_t *	updater,
		char *	buff,
		size_t	buff_size
	)

Set response header buffer.

The buffer is used to store single HTTP response header. If this method is not called or set NULL to the buffer, tio_updater allocates memory of response header buffer when the HTTP session started and free when the HTTP session ends. The buffer allocated by tio_updater is 256 bytes.

If header is larger than the buffer, the header is skipped and not parsed. tio_handler needs to parse Status Line, Content-Length and Transfer-Encoding header. The buffer must have enough size to store those headers. 256 bytes would be enough. If you set the buffer by the method, the method must be called before calling tio_updater_start() and memory used by the buffer can be safely freed after you've terminated tio_updater task.

Parameters

[out]	updater	tio_updater_t instance.
[in]	buff	pointer to the buffer.
[in]	buff_size	size of the buffer.

tio_updater_set_stream_buff()

void tio_updater_set_stream_buff	(	tio_updater_t *	updater,
		char *	buff,
		size_t	buff_size
	)

Set stream buffer. Stream buffer is used store part of HTTP body when reading/ writing it from the network.

If this method is not called or set NULL to the buffer, tio_updater allocates memory of stream buffer when the HTTP session started and free when the HTTP session ends. The buffer allocated by tio_updater is 1024 bytes.

You can change the size of buffer depending on your request/ response size. It must be enough large to store size line in chunked encoded message. However, you may use much larger buffer since size line might require very small buffer as it consists of HEX size and CRLF for the better performance.

If you set the buffer by the method, the method must be called before tio_updater_start(). and memory used by the buffer can be safely freed after you've terminated tio_updater task.

Parameters

[out]	updater	tio_updater_t instance.
[in]	buff	pointer to the buffer.
[in]	buff_size	size of the buffer.

tio_updater_start()

tio_code_t tio_updater_start	(	tio_updater_t *	updater,
		const tio_author_t *	author,
		TIO_CB_SIZE	cb_state_size,
		void *	state_size_data,
		TIO_CB_READ	cb_read_state,
		void *	read_state_data
	)

Start tio_updater task.

You can start tio_updater task by this method. If the API returns TIO_ERR_OK, asynchronous task is started successfully and callbacks set by tio_updater setter methods and this method is called when corresponding event occurs.

Parameters

[in]	updater	tio_updater_t instance.
[in]	author	API author.
[in]	cb_state_size	Callback asking for size of the state to be uploaded.
[in]	state_size_data	Context object pointer passed to cb_state_size.
[in]	cb_read_state	Callback read state of the device.
[in]	read_state_data	Context object pointer passed to cb_read_state.

Returns

TIO_ERR_OK when succeeded to start task.

Variable Documentation

TIO_TASK_NAME_UPDATE_STATE

const char TIO_TASK_NAME_UPDATE_STATE[]

tio_updater Task name.

Name can be referenced from task create callback set by tio_updater_set_cb_task_create().