Downloading an Object Body

To download an object body, you use a different API from that for getting a KiiObject. For the overview of the object body, see Accessing an Object Body.

The Thing SDK Embedded offers the following two methods for downloading an object body:

Be careful with the buffer size specified at initialization if you increase the data size per transfer. The total size of transferred data per API call including command options such as HTTP headers must be less than or equal to the buffer size specified at initialization.

Downloading an object body in multiple pieces

The following sample code shows how to download an object body.

/* Set object body parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"
#define LENGTH_CHUNK 4000

int i;
unsigned int position, actualLength, totalLength;

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

position = 0;
do {
  /* Download the object body in chunks. */
  ret = kii_object_download_body(&kii, &bucket, OBJECT_ID, position, LENGTH_CHUNK, &actualLength, &totalLength);
  if (ret != 0) {
    /* Handle the error. */
    return;
  }

  for (i = 0; i < (int)actualLength; i++) {
    printf("%02x, ", kii.kii_core.response_body[i]);
  }
  printf("\n");
  position += actualLength;
} while (position < totalLength);

When you download an object body in multiple pieces, you download the object body by repeatedly calling the kii_object_download_body function.

The target KiiObject is identified with the kii_bucket_t structure and KiiObject ID. The other arguments, position, LENGTH_CHUNK, &actualLength, and &totalLength have the following meanings:

  • position

    The position to start downloading the entire object body. This sample code retains the start position of the next download by initializing this argument with 0 at the start and adding the size of transferred data for each download.

  • LENGTH_CHUNK

    The maximum size of data to be downloaded in bytes by one API call.

  • &actualLength

    The pointer to the space which stores the actual size of data retrieved by the API call. The size is returned in bytes.

  • &totalLength

    The pointer to the space which stores the size of the entire object body. The size is returned in bytes.

The kii.kii_core.response_body stores the retrieved data.

The sample code achieves downloading in multiple pieces with the do while loop. It calls the kii_object_download_body function and repeats downloads while the position for the size of the transferred data is smaller than the totalLength for the size of the entire object body. It dumps the retrieved data to the kii.kii_core.response_body with printf after the chunks are downloaded.

Downloading an object body at once

You can download an entire object body with one API call without splitting data into chunks (We recommend downloading an object body in multiple pieces, especially when you are downloading a big file from Kii Cloud).

Check the following sample code to see how you can do this.

/* Set object body parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"

int i;
unsigned int dataLength;

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

/* Download the object body. */
ret = kii_object_download_body_at_once(&kii, &bucket, OBJECT_ID, &dataLength);
if (ret != 0) {
  /* Handle the error. */
  return;
}

for (i = 0; i < (int)dataLength; i++) {
  printf("%02x, ", kii.kii_core.response_body[i]);
}

Use the kii_object_download_body_at_once function to download the entire object body with one API call.

The target KiiObject is identified with the kii_bucket_t structure and KiiObject ID. See Creating a KiiObject to learn how to specify the bucket.

As the fourth argument, specify the pointer to the space which stores the actual size of downloaded data. The kii.kii_core.response_body stores the data.

The sample code dumps the downloaded data with printf.