Object Body のダウンロード

Object Body のダウンロードは、Object の取得とは別の API で行います。Object Body の機能概要については、Object Body のアクセスをご覧ください。

Thing SDK Embedded は、以下の 2 種類の Object Body ダウンロード方法を提供しています。

分割ダウンロード
一括ダウンロード

1 回の転送サイズを大きくする場合、初期化の際に指定したバッファーサイズにご注意ください。1 回の API 呼び出しでの転送サイズと、HTTP ヘッダー等のリクエストに必要なサイズの合計は、初期化で指定したバッファーサイズ以下である必要があります。

分割ダウンロード

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);

分割ダウンロードでは、kii_object_download_body 関数を繰り返して呼ぶことによって Object Body をダウンロードします。

引数ではダウンロード対象の Object を kii_bucket_t 構造体と Object の ID で識別します。その他の position、LENGTH_CHUNK、&actualLength、&totalLength は以下の意味を持ちます。

position

Object Body 全体に対するダウンロード開始位置をバイト単位で指定します。このサンプルコードでは初め 0 で初期化しておき、1 回のダウンロードごとに、実際に転送したサイズ actualLength を積算することで Object Body 全体に対する次のダウンロード開始位置を保持しています。
LENGTH_CHUNK

1 回の API 呼び出しでダウンロードする最大サイズをバイト単位で指定します。
&actualLength

API を呼び出した結果、実際の取得サイズを返す領域へのポインタを指定します。取得できたサイズはバイト単位で返されます。
&totalLength

Object Body の全体サイズを返す領域へのポインタを指定します。サイズはバイト単位で返されます。

取得できたデータは、kii.kii_core.response_body に格納されます。

サンプルコードでは、do～while で分割ダウンロードを実現します。kii_object_download_body 関数を呼び出し、転送済みのサイズ position が、Object Body の全体サイズ totalLength より小さい場合に、ダウンロードを繰り返します。分割単位ごとのダウンロード後、kii.kii_core.response_body に取得したデータサイズまでを printf によってダンプしています。

一括ダウンロード

分割を行わず、1 回の API 呼び出しですべての Object Body をダウンロードすることも可能です（ただし、特にサイズの大きなファイルを Kii Cloud よりダウンロードするケースなどにおいては分割ダウンロードを利用することを推奨します）。

一括ダウンロードを行う例を以下に挙げます。

/* 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]);
}

kii_object_download_body_at_once 関数を使用すると、Object Body の全体を一度の API 呼び出しでダウンロードします。

ダウンロード対象の Object は、kii_bucket_t 構造体と Object の ID で指定します。Bucket の指定方法は、Object の作成をご覧ください。

第 4 引数には、実際にダウンロードしたサイズを返す領域へのポインタを指定します。データの本体は、kii.kii_core.response_body に格納されます。

サンプルコードでは、ダウンロードしたデータを printf によってダンプしています。