Creating a KiiObject

To create a KiiObject, call the API with a JSON string to store in the KiiObject. You can select any scope for a bucket where the KiiObject is to be stored. However, note that the thing needs to have the permission to add KiiObjects to the destination bucket.

The bucket is automatically created when the first KiiObject is created.

Kii supports two methods for assigning IDs to KiiObjects: automatic ID assignment by Kii Cloud and explicit ID assignment by the program on the thing.

Creating a KiiObject with automatic ID assignment

See below for the sample code to create a KiiObject.

/* Set KiiObject parameters. */
#define OBJECT_DATA "{\"power\":true, \"temperature\":25, \"status\":\"NORMAL\"}"
#define CONTENT_TYPE NULL

char object_id[KII_OBJECTID_SIZE + 1];

int ret;

/* Set bucket parameters. */
kii_bucket_t bucket;
memset(&bucket, 0x00, sizeof(kii_bucket_t));
bucket.scope = KII_SCOPE_THING;
bucket.bucket_name = "myBucket";
bucket.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";

/* Create a KiiObject. */
ret = kii_object_create(&kii, &bucket, OBJECT_DATA, CONTENT_TYPE, object_id);
if (ret != 0) {
  /* Handle the error. */
  return;
}

printf("object ID:%s\n", object_id);

Specify the destination bucket of the KiiObject with the kii_bucket_t structure. See below to learn how to set the structure.

The sample code above specifies myBucket in the thing scope as the destination bucket. This example assumes that the access token has been obtained by vendorThingID rBnvSPOXBDF9r29GJeGS and the kii_t structure has been initialized. The scope_id member of the kii_bucket_t structure specifies VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS as the scope ID. So, the KiiObject is created in the bucket in the thing scope of the thing of which you obtained the access token.

When the kii_object_create function is called, it communicates with Kii Cloud and creates an KiiObject which contains the JSON string specified with the OBJECT_DATA. The function returns the KiiObject ID in the object_id.

The maximum size of the data to be stored in a KiiObject is 65534 characters in Unicode in JSON format, including fields internally used in Kii Cloud.

Specify the media type of the KiiObject as the fourth argument of the kii_object_create function. You can specify "application/json" or "application/vnd.{APPID}.{DATATYPE}" as the media type of the KiiObject. For the latter case, you can set any value for {DATA_TYPE}. You can skip setting the media type by specifying NULL to the fourth argument.

Hints for accessing KiiObjects

• Cannot read a KiiObject that has been written in a bucket

  Please double check if the scope of the bucket is correct. Remember that two buckets that have the same name but have different scopes are treated differently.

  For example, KiiObjects created in a bucket named myBucket in the application scope are not readable through a bucket with the same name in the user scope.

Hint for creating a bucket list

If you need to get a list of buckets, you need to implement the feature in your application.

Usually, buckets are created statically with their names in your code, so you should not need to get a list of buckets. If you do need to get the bucket list for some reasons (e.g., your code dynamically create buckets), your application can use a dedicated application scope bucket to store all bucket names. See Hint for creating a user list to learn how to implement it.

Using location data

You can use GeoPoint as the data type to save location data. See GeoPoint in the REST Guide to learn how to specify GeoPoint.

GeoPoint is not only a data representation in JSON but supports searching KiiObjects within a specified distance or range. See Querying KiiObjects in the REST Guide to learn how to use the search function.

Creating KiiObjects with explicit ID assignment

You can create KiiObjects with explicitly specified ID.

See below for the sample code to create a KiiObject with specified ID.

/* Set KiiObject parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"
#define OBJECT_DATA "{\"power\":true, \"temperature\":25, \"status\":\"NORMAL\"}"
#define CONTENT_TYPE NULL

int ret;

/* Set bucket parameters. */
kii_bucket_t bucket;
memset(&bucket, 0x00, sizeof(kii_bucket_t));
bucket.scope = KII_SCOPE_THING;
bucket.bucket_name = "myBucket";
bucket.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";

/* Create a KiiObject. */
ret = kii_object_create_with_id(&kii, &bucket, OBJECT_ID, OBJECT_DATA, CONTENT_TYPE);
if (ret != 0) {
  /* Handle the error. */
  return;
}

Specify the KiiObject ID as the third argument of the kii_object_create_with_id function. In this example, a KiiObject is created with the static ID, STATUS_TEMPERATURE. See Javadoc for the Kii Cloud SDK for Android for the valid patterns of KiiObject ID.

The usage of the other parameters is the same as that of the kii_object_create function.