kii.h File Reference

This is a file defining Kii Cloud APIs. More...

#include "kii_core.h"
#include "kii_task_callback.h"
#include <kii_json.h>

Go to the source code of this file.

Classes
struct	kii_t
struct	kii_chunk_data_t

Macros
#define	KII_OBJECTID_SIZE   36
#define	KII_UPLOADID_SIZE   64
#define	M_KII_LOG(x)
#define	KII_TASK_NAME_RECV_MSG   "recv_msg_task"

Typedefs
typedef void(*	KII_PUSH_RECEIVED_CB )(struct kii_t *kii, char *message, size_t message_length)
typedef struct kii_t	kii_t
typedef struct kii_chunk_data_t	kii_chunk_data_t

Functions
int	kii_init (kii_t *kii, const char *site, const char *app_id, const char *app_key)
int	kii_thing_authenticate (kii_t *kii, const char *vendor_thing_id, const char *password)
int	kii_thing_register (kii_t *kii, const char *vendor_thing_id, const char *thing_type, const char *password)
int	kii_thing_upload_state (kii_t *kii, const char *thing_id, const char *thing_state, const size_t content_length, const char *content_type, const char *content_encoding, const char *normalizer_host)
int	kii_thing_patch_state (kii_t *kii, const char *thing_id, const char *thing_state, const size_t content_length, const char *content_type, const char *content_encoding, const char *normalizer_host)
int	kii_object_create (kii_t *kii, const kii_bucket_t *bucket, const char *object_data, const char *object_content_type, char *out_object_id)
int	kii_object_create_with_id (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, const char *object_data, const char *object_content_type)
int	kii_object_patch (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, const char *patch_data, const char *opt_etag)
int	kii_object_replace (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, const char *replacement_data, const char *opt_etag)
int	kii_object_delete (kii_t *kii, const kii_bucket_t *bucket, const char *object_id)
int	kii_object_get (kii_t *kii, const kii_bucket_t *bucket, const char *object_id)
int	kii_object_upload_body_at_once (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, const char *body_content_type, const void *data, size_t data_length)
int	kii_object_init_upload_body (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, char *out_upload_id)
int	kii_object_upload_body (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, const char *upload_id, const kii_chunk_data_t *chunk)
int	kii_object_commit_upload (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, const char *upload_id, unsigned int commit)
int	kii_object_download_body_at_once (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, unsigned int *out_data_length)
int	kii_object_download_body (kii_t *kii, const kii_bucket_t *bucket, const char *object_id, unsigned int position, unsigned int length, unsigned int *out_actual_length, unsigned int *out_total_length)
int	kii_push_subscribe_bucket (kii_t *kii, const kii_bucket_t *bucket)
int	kii_push_unsubscribe_bucket (kii_t *kii, const kii_bucket_t *bucket)
int	kii_push_subscribe_topic (kii_t *kii, const kii_topic_t *topic)
int	kii_push_unsubscribe_topic (kii_t *kii, const kii_topic_t *topic)
int	kii_push_create_topic (kii_t *kii, const kii_topic_t *topic)
int	kii_push_delete_topic (kii_t *kii, const kii_topic_t *topic)
int	kii_push_start_routine (kii_t *kii, KII_PUSH_RECEIVED_CB callback)
int	kii_server_code_execute (kii_t *kii, const char *endpoint_name, const char *params)
int	kii_api_call_start (kii_t *kii, const char *http_method, const char *resource_path, const char *content_type, kii_bool_t set_authentication_header)
int	kii_api_call_append_body (kii_t *kii, const void *body_data, size_t body_size)
int	kii_api_call_append_header (kii_t *kii, const char *key, const char *value)
int	kii_api_call_run (kii_t *kii)

Detailed Description

This is a file defining Kii Cloud APIs.

Typedef Documentation

typedef struct kii_chunk_data_t kii_chunk_data_t

represents chunk data

Function Documentation

int kii_api_call_append_body	(	kii_t *	kii,
		const void *	body_data,
		size_t	body_size
	)

append request body.

This function must be called between kii_api_call_start(kii_t*, const char*, const char*, const char*, kii_bool_t) and kii_api_call_run(kii_t*).

Parameters

[in]	kii	SDK object.
[in]	body_data	appended body data.
[in]	body_size	appended body data size.

Returns

result of appending. if 0 appending is succeeded, otherwise failed.

int kii_api_call_append_header	(	kii_t *	kii,
		const char *	key,
		const char *	value
	)

append request header.

This function must be called between kii_api_call_start(kii_t*, const char*, const char*, const char*, kii_bool_t) and kii_api_call_run(kii_t*).

Parameters

[in]	kii	SDK object.
[in]	key	key of http header.
[in]	value	value of http header.

Returns

result of appending. if 0 appending is succeeded, otherwise failed.

int kii_api_call_run

(

kii_t *

kii

)

run with created request for REST API.

HTTP request is created with following APIs:

• kii_api_call_start(kii_t*, const char*,const char*, const char*, kii_bool_t)
• kii_api_call_append_body(kii_t*, const char*, size_t)
• kii_api_call_append_header(kii_t*, const char*, const char*)

After creation of HTTP request, this function calls REST API with created request. As a result, HTTP response is set to kii_t::kii_core::response_body and kii_t::kii_core::response_code.

Parameters

[in]

kii

SDK object.

Returns

result of closing request creation if 0 it is succeeded, otherwise failed.

int kii_api_call_start	(	kii_t *	kii,
		const char *	http_method,
		const char *	resource_path,
		const char *	content_type,
		kii_bool_t	set_authentication_header
	)

start to create request for REST API.

Between this function and kii_api_call_run(kii_t*), you can call kii_api_call_append_body(kii_t*, const char* size_t) and kii_api_call_append_header(kii_t*, const char*, const char*) any number of times.

Parameters

[in]	kii	SDK object.
[in]	http_method	method of http request.
[in]	resource_path	resource path of http request.
[in]	content_type	content type of http_body.
[in]	set_authentication_header	a flag to set or not authentication header.

Returns

result of preparation. if 0, preparation is succeeded, otherwise failed

int kii_init	(	kii_t *	kii,
		const char *	site,
		const char *	app_id,
		const char *	app_key
	)

Initializes Kii SDK

Parameters

[in,out]	kii	sdk instance.
[in]	site	the input of site name, should be one of "CN", "CN3", "JP", "US", "SG" or "EU"
[in]	app_id	the input of Application ID
[in]	app_key	the input of Application Key

Returns

0:success, -1: failure

int kii_object_commit_upload	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		const char *	upload_id,
		unsigned int	commit
	)

Commit and finalize upload. After successfully upload all the chunk of the body by kii_object_upload_body() call this api to finalize upload. or in cancel upload can be called after the kii_object_init_upload_body() succeeded. Basically no need to cancel upload since Kii Cloud cleanups the impcompleted uploads periodically.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object of which body is added.
[in]	upload	id obtained by kii_object_init_upload_body().
	]in]	commit 0: cancell upload, >0: commit upload

Returns

0:success, -1: failure

int kii_object_create	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_data,
		const char *	object_content_type,
		char *	out_object_id
	)

Create new object

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_data	key-value pair of the object in json format.
[in]	object_content_type	content-type of the object. If null, application/json will be applied.
[out]	object_id	output of the created object ID. Supplied when succeeded to create new object. Must be allocated by application with the size of KII_OBJECTID_SIZE + 1 before this api call.

Returns

0:success, -1: failure

int kii_object_create_with_id	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		const char *	object_data,
		const char *	object_content_type
	)

Create new object with the specified ID

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object.
[in]	object_data	key-value pair of the object in json format.
[in]	object_content_type	content-type of the object. If null, application/json will be applied.

Returns

0:success, -1: failure

int kii_object_delete	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id
	)

Delete the object

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object.

Returns

0:success, -1: failure

int kii_object_download_body	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		unsigned int	position,
		unsigned int	length,
		unsigned int *	out_actual_length,
		unsigned int *	out_total_length
	)

Download object body chunk by chunk. Downloaded data is cached in kii_core_t::response_body after the download chunk is succeeded.

IMPORTANT: This API uses Range request which is defined in HTTP 1.1. You may need to turn on KII_USE_CUSTOM_ HTTP_CLIENT and switch the client implementation since the reference client is HTTP 1.0.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object of which body is added.
[in]	position	starting position of the download (in bytes)
[in]	length	length to download (in bytes)
[out]	out_actual_length	actual length downloaded. (in bytes)
[out]	out_total_length	total length of whole object body (in bytes)

Returns

0:success, -1: failure

int kii_object_download_body_at_once	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		unsigned int *	out_data_length
	)

Download object body at one time. If the data size is large or unknown, consider use kii_object_download_body() instead. The result is cached in kii_core_t::response_body when succeeded.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object of which body is added.
[out]	out_data_length	length of the downloaded body. (in bytes)

Returns

0:success, -1: failure

int kii_object_get	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id
	)

Get the object When succeeded, obtained object data is cached in kii_core_t::response_body.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object.

Returns

0:success, -1: failure

int kii_object_init_upload_body	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		char *	out_upload_id
	)

Initiate chunked object body upload.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object of which body is added.
[out]	out_upload_id	upload id to be used to continue chunked upload. Must be allocated by application with the size of KII_UPLOADID_SIZE + 1 before this api call.

Returns

0:success; -1: failure

int kii_object_patch	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		const char *	patch_data,
		const char *	opt_etag
	)

Partial update of the object Only the specified key-value is updated and other key-values won't be updated/ removed.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object.
[in]	patch_data	key-value pair of the object in json format.
[in]	opt_etag	etag of the object. if specified, update will be failed if there is updates on cloud. if NULL, forcibly updates.

Returns

0:success, -1: failure

int kii_object_replace	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		const char *	replacement_data,
		const char *	opt_etag
	)

Full update of the object Replace the object with specified key-values. Existing key-value pair which is not included in the replacement_data will be removed.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object.
[in]	replacement_data	key-value pair of the object in json format.
[in]	opt_etag	etag of the object. if specified, update will be failed if there is updates on cloud. if NULL, forcibly updates.

Returns

0:success, -1: failure

int kii_object_upload_body	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		const char *	upload_id,
		const kii_chunk_data_t *	chunk
	)

Upload object body chunk by chunk. You need to obtain upload id before execute this method by calling kii_object_init_upload_body().

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object of which body is added.
[in]	upload	id obtained by kii_object_init_upload_body().
[in]	chunk	chunk of the body to upload.

Returns

0:success, -1: failure

int kii_object_upload_body_at_once	(	kii_t *	kii,
		const kii_bucket_t *	bucket,
		const char *	object_id,
		const char *	body_content_type,
		const void *	data,
		size_t	data_length
	)

Upload object body at once. Upload object body at one time. If the data is large, consider use chunk upload with kii_object_upload_body().

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket of which object is stored.
[in]	object_id	specify the id of the object of which body is added.
[in]	body_content_type	content-type of the body.
[in]	data	object body data.
[in]	data_length	length of the data.

Returns

0:success, -1: failure

int kii_push_create_topic	(	kii_t *	kii,
		const kii_topic_t *	topic
	)

Create new topic.

Parameters

[in,out]	kii	sdk instance.
[in]	topic	specify the topic to create.

Returns

0:success, -1: failure

int kii_push_delete_topic	(	kii_t *	kii,
		const kii_topic_t *	topic
	)

Delete existing topic.

Parameters

[in,out]	kii	sdk instance.
[in]	topic	specify the topic to delete.

Returns

0:success, -1: failure

int kii_push_start_routine	(	kii_t *	kii,
		KII_PUSH_RECEIVED_CB	callback
	)

Start push notification receiving routine. After succeeded, callback is called when push message is delivered to this thing.

Parameters

[in,out]	kii	sdk instance.
[in]	callback	callback function called when push message delivered.

Returns

0:success, -1: failure

int kii_push_subscribe_bucket	(	kii_t *	kii,
		const kii_bucket_t *	bucket
	)

Subscribe to specified bucket. After succeeded, Event happened on the bucket will be notified via push notification.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket to subscribe.

Returns

0:success, -1: failure

int kii_push_subscribe_topic	(	kii_t *	kii,
		const kii_topic_t *	topic
	)

Subscribe to specified topic. After succeeded, Message sent to the topic will be notified via push notification.

Parameters

[in,out]	kii	sdk instance.
[in]	topic	specify the topic to subscribe.

Returns

0:success, -1: failure

int kii_push_unsubscribe_bucket	(	kii_t *	kii,
		const kii_bucket_t *	bucket
	)

Unsubscribe specified bucket.

Parameters

[in,out]	kii	sdk instance.
[in]	bucket	specify the bucket to subscribe.

Returns

0:success, -1: failure

int kii_push_unsubscribe_topic	(	kii_t *	kii,
		const kii_topic_t *	topic
	)

Unsubscribe specified topic.

Parameters

[in,out]	kii	sdk instance.
[in]	topic	specify the topic to subscribe.

Returns

0:success, -1: failure

int kii_server_code_execute	(	kii_t *	kii,
		const char *	endpoint_name,
		const char *	params
	)

Execute server code.

Parameters

[in,out]	kii	sdk instance.
[in]	endpoint_name	name of the endpoint to be executed.
[in]	params	parameters given to endpoint. should be formatted in json.

Returns

0:success, -1: failure

int kii_thing_authenticate	(	kii_t *	kii,
		const char *	vendor_thing_id,
		const char *	password
	)

Authorize thing with vendor thing id and password. After the authentication, access token is used to call APIs access to Kii Cloud so that the thing can access private data.

Parameters

[in,out]	kii	sdk instance.
[in]	vendor_thing_id	the thing identifier given by vendor.
[in]	password	the password of the thing given by vendor.

Returns

0:success, -1: failure

int kii_thing_patch_state	(	kii_t *	kii,
		const char *	thing_id,
		const char *	thing_state,
		const size_t	content_length,
		const char *	content_type,
		const char *	content_encoding,
		const char *	normalizer_host
	)

Patch state of thing

Parameters

[in,out]	kii	sdk instance.
[in]	thing_id	the thing identifier given by kii cloud.
[in]	state	state to upload.
[in]	content_length	length of body.
[in]	content_type	type of state, if NULL provided, sdk used defaulted application/vnd.kii.MultipleTraitStatePatch+json.
[in]	content_encoding	encoding of state used. If NULL provided, sdk not add Content-encoding header
[in]	normalizer_host	host name of data normalizer, can be NULL.

Returns

0:success, -1: failure

int kii_thing_register	(	kii_t *	kii,
		const char *	vendor_thing_id,
		const char *	thing_type,
		const char *	password
	)

Register new thing After the registtration, access token is used to call APIs access to Kii Cloud so that the thing can access private data.

Parameters

[in,out]	kii	sdk instance.
[in]	vendor_thing_id	the thing identifier given by vendor.
[in]	thing_type	the type of the thing given by vendor.
[in]	password	- the password of the thing given by vendor.

Returns

0:success, -1: failure

int kii_thing_upload_state	(	kii_t *	kii,
		const char *	thing_id,
		const char *	thing_state,
		const size_t	content_length,
		const char *	content_type,
		const char *	content_encoding,
		const char *	normalizer_host
	)

Upload state of thing

Parameters

[in,out]	kii	sdk instance.
[in]	thing_id	the thing identifier given by kii cloud.
[in]	state	state to upload.
[in]	content_length	length of body.
[in]	content_type	type of state, if NULL provided, sdk used defaulted CONTENT_UPDATE_STATE(application/vnd.kii.MultipleTraitState+json).
[in]	content_encoding	encoding of state used. If NULL provided, sdk not add Content-encoding header
[in]	normalizer_host	host name of data normalizer, can be NULL.

Returns

0:success, -1: failure