Updating a KiiObject

You can use the following two methods when updating a KiiObject:

Full update

This method overwrites the data on the server with the key-value pairs sent from the thing (the data on the server will be lost). See Full update versus partial update in the Function Guide for the illustrated example.

Here is the sample code:

/* Set KiiObject parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"
#define OBJECT_REPLACEMENT_DATA "{\"power\":false, \"status\":\"ERROR\"}"
#define OBJECT_ETAG "1"

/* 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";

/* Fully update the KiiObject. */
ret = kii_object_replace(&kii, &bucket, OBJECT_ID, OBJECT_REPLACEMENT_DATA, OBJECT_ETAG);
if (ret != 0) {
  /* Handle the error. */
  return;
}

Specify the target bucket with the kii_bucket_t structure. See Creating a KiiObject to learn how to specify it.

Use the last argument OBJECT_ETAG to perform update check with optimistic locking.

  • If NULL is specified:

    When the argument is NULL, update check with the optimistic lock is not performed. The KiiObject is overwritten with the specified values in JSON format.

  • If non-NULL value is specified:

    When the argument is not NULL, update check with the optimistic lock is performed. Kii Cloud compares the _version field of the target KiiObject between the thing and the server, and then updates the KiiObject only if the field value is the same. The field value on the thing is the one obtained when the KiiObject was retrieved most recently.

    If any other client has updated the KiiObject after the last time the thing retrieved it, the server has automatically incremented the value of the _version field. It makes the field value different between the thing and the server. Kii Cloud determines that the update conflicts and rejects to update the KiiObject.

Partial update

This method merges the data on the server with the key-value pairs sent from the thing. You will send a JSON string which contains the only difference between the thing and the server. See Full update versus partial update in the Function Guide for the illustrated example. Note that you cannot delete the keys on the server side with this method.

Here is the sample code:

/* Set KiiObject parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"
#define OBJECT_REPLACEMENT_DATA "{\"power\":false, \"status\":\"ERROR\"}"
#define OBJECT_ETAG "1"

/* 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";

/* Partially update the KiiObject. */
ret = kii_object_patch(&kii, &bucket, OBJECT_ID, OBJECT_REPLACEMENT_DATA, OBJECT_ETAG);
if (ret != 0) {
  /* Handle the error. */
  return;
}

Specify parameters in the same way as with the full update.

To safely update KiiObjects, you might need to consider errors which could happen while a thing updates multiple KiiObjects. See Transactions for some hints.