Kii Thing SDK Embedded
 All Classes Files Functions Variables Typedefs
Classes | Macros | Typedefs | Functions
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

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]kiiSDK object.
[in]body_dataappended body data.
[in]body_sizeappended 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]kiiSDK object.
[in]keykey of http header.
[in]valuevalue 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:

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]kiiSDK 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]kiiSDK object.
[in]http_methodmethod of http request.
[in]resource_pathresource path of http request.
[in]content_typecontent type of http_body.
[in]set_authentication_headera 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]kiisdk instance.
[in]sitethe input of site name, should be one of "CN", "CN3", "JP", "US", "SG" or "EU"
[in]app_idthe input of Application ID
[in]app_keythe 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object of which body is added.
[in]uploadid 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_datakey-value pair of the object in json format.
[in]object_content_typecontent-type of the object. If null, application/json will be applied.
[out]object_idoutput 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object.
[in]object_datakey-value pair of the object in json format.
[in]object_content_typecontent-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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object of which body is added.
[in]positionstarting position of the download (in bytes)
[in]lengthlength to download (in bytes)
[out]out_actual_lengthactual length downloaded. (in bytes)
[out]out_total_lengthtotal 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object of which body is added.
[out]out_data_lengthlength 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object of which body is added.
[out]out_upload_idupload 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object.
[in]patch_datakey-value pair of the object in json format.
[in]opt_etagetag 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object.
[in]replacement_datakey-value pair of the object in json format.
[in]opt_etagetag 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object of which body is added.
[in]uploadid obtained by kii_object_init_upload_body().
[in]chunkchunk 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]kiisdk instance.
[in]bucketspecify the bucket of which object is stored.
[in]object_idspecify the id of the object of which body is added.
[in]body_content_typecontent-type of the body.
[in]dataobject body data.
[in]data_lengthlength 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]kiisdk instance.
[in]topicspecify 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]kiisdk instance.
[in]topicspecify 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]kiisdk instance.
[in]callbackcallback 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]kiisdk instance.
[in]bucketspecify 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]kiisdk instance.
[in]topicspecify 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]kiisdk instance.
[in]bucketspecify 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]kiisdk instance.
[in]topicspecify 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]kiisdk instance.
[in]endpoint_namename of the endpoint to be executed.
[in]paramsparameters 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]kiisdk instance.
[in]vendor_thing_idthe thing identifier given by vendor.
[in]passwordthe 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]kiisdk instance.
[in]thing_idthe thing identifier given by kii cloud.
[in]statestate to upload.
[in]content_lengthlength of body.
[in]content_typetype of state, if NULL provided, sdk used defaulted application/vnd.kii.MultipleTraitStatePatch+json.
[in]content_encodingencoding of state used. If NULL provided, sdk not add Content-encoding header
[in]normalizer_hosthost 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]kiisdk instance.
[in]vendor_thing_idthe thing identifier given by vendor.
[in]thing_typethe 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]kiisdk instance.
[in]thing_idthe thing identifier given by kii cloud.
[in]statestate to upload.
[in]content_lengthlength of body.
[in]content_typetype of state, if NULL provided, sdk used defaulted CONTENT_UPDATE_STATE(application/vnd.kii.MultipleTraitState+json).
[in]content_encodingencoding of state used. If NULL provided, sdk not add Content-encoding header
[in]normalizer_hosthost name of data normalizer, can be NULL.
Returns
0:success, -1: failure