ステートの登録と確認

Thing の状態を表すステートを Thing Interaction Framework にアップロードできます。また、アップロードされた最新のステートを確認できます。

このガイドでは Thing よりステートをアップロードする方法と、アップロードされたステートを開発者ポータル上で確認する方法を説明します。

ステートの登録
ステートの確認

ステートの登録

ステートのアップロードが実行されるタイミングには、コマンドの実行完了時と、一定間隔での自動実行の 2 つがあります。ステートは、Thing 機能の登録で追加したトレート定義の形式に基づいて JSON 形式で生成します。これらの機能概要はステートの登録と取得をご覧ください。

SDK の初期化と Thing の初期登録では、ステートを返すコールバック関数（ステートハンドラー）のポインタを 2 件登録します。この関数には、ステートを JSON 文字列の形で組み立てる処理を記述します。初期化処理のサンプルコードでは 2 件とも同じ関数を登録していますが、別の関数を割り当てることもできます。

コマンドの実行完了時に対するステートハンドラー

SDK は MQTT のコマンド受信タスクでコマンドを受信した際、アクションをすべて処理した後でステートハンドラーを呼び出します。コマンド中にアクションが複数個含まれる場合、コマンドの受信ごとに 1 回だけ呼び出します。
一定間隔での自動実行に対するステートハンドラー

SDK は、内部でステート更新用のタスク（スレッド）を生成し、そのタスクからステートハンドラーを一定間隔で呼び出します。呼び出し間隔は初期化の際に関数ポインタと同時に指定します。

いずれの場合も、ステートの更新のタイミングは、SDK 側が制御しているため、Thing 側のプログラムから自発的に更新することはできません。

コールバック関数内の処理によっては、排他処理の実装が必要になる場合があります。タスクの詳細はこちらをご覧ください。

ステートハンドラー

ステートハンドラーのコールバック関数のプロトタイプは以下のとおりです。

typedef kii_bool_t
  (*KII_THING_IF_STATE_HANDLER)
    (kii_t* kii,
     KII_THING_IF_WRITER writer);

このプロトタイプに基づいて以下のようなステートハンドラーを記述します。SDK の初期化では、command_handler_resource 構造体の state_handler メンバー、および、state_updater_resource 構造体の state_handler メンバーとしてこのコールバック関数のポインタを渡します。

kii_bool_t state_handler(
        kii_t* kii,
        KII_THING_IF_WRITER writer)
{
  char buf[256];

  /* Set the JSON string to the buffer. */
  sprintf(buf,
      "{\"LiquidLevelMeterAlias\":{\"level\":%d}}",
      get_currentLevel());

  /* If the writer failed to write the JSON string */
  if ((*writer)(kii, buf) == KII_FALSE) {
    return KII_FALSE;
  }

  return KII_TRUE;
}

この例では、以下のような JSON 文字列を作成しています。この JSON 文字列は、トレイトの追加で例示したトレート定義に対応しています。

{"LiquidLevelMeterAlias":{"level":40}}

コールバック関数の各パラメータの意味は以下のとおりです。

kii：ステートの実装に使用する SDK 内部の構造体ポインタです。初期化の際、kii_thing_if_t として初期化した構造体の一部で、下記の writer を使用するために必要です。
writer：結果の JSON を出力する際に使用する関数へのポインタです。SDK が提供する文字列出力用 API です。詳細は下記 KII_THING_IF_WRITER をご覧ください。

コールバック関数の実行（ステートの取得）が成功した場合は KII_TRUE を、それ以外の場合は KII_FALSE を戻り値として返します。KII_FALSE を返した場合、ステートの更新（Thing Interaction Framework へのステートのアップロード）は行われません。

KII_THING_IF_WRITER

ステートの更新を行うコールバック関数では、引数に KII_THING_IF_WRITER が渡されます。これは、文字列を書き込むための API です。ステートハンドラーでは、書き込んだ文字列がステートの JSON 文字列として Thing Interaction Framework にアップロードされます。

KII_THING_IF_WRITER のプロトタイプは以下のとおりです。

typedef kii_bool_t (*KII_THING_IF_WRITER)(kii_t* kii, const char* buff);

kii：ステートハンドラーに渡された kii をそのまま指定します。ステートの書き込み先を識別するため、KII_THING_IF_WRITER 内部で使用されます。
buff：出力したい文字列へのポインタです。

書き込みに成功したときは、戻り値として KII_TRUE を、それ以外は KII_FALSE を返します。

書き込み先のバッファ容量が不足した場合には KII_FALSE を返します。ここでの書き込み先は、SDK の初期化の際に kii_thing_if_state_updater_resource_t 構造体の buffer メンバーで指定したバッファです。

使用例は上記のステートハンドラーの実装例をご覧ください。

ステートの確認

ステートは、開発者ポータルの Thing コンソールで確認できます。

操作方法の詳細はステートの管理をご覧ください。