コマンドの実行

Thing では受信したコマンドの内容を解釈することで、様々なサービスを提供できます。機能概要はこちらをご覧ください。

Thing 上のプログラムは、初期化の際に指定したコールバック関数（アクションハンドラー）によってコマンドの受信を知ることができます。コマンドは、Thing Interaction Framework から MQTT のプッシュ通知によって Thing に届きます。MQTT でプッシュ通知を受け取ると、SDK からアクションハンドラーが呼び出されます。

コマンドに複数のアクションが含まれる場合、アクションハンドラーはアクションごとに複数回呼び出されます。このときの呼び出し順は、モバイルアプリ側でアクションの配列に格納した順番となります。

アクションハンドラーのコールバック関数はプッシュ通知の受信タスク（スレッド）から呼び出されます。処理によっては、他のタスクとの排他処理が必要になる場合があります。タスクの詳細はこちらをご覧ください。

なお、MQTT の初期化処理などは SDK の内部で自動的に実行されます。リファレンス実装を使用する場合、特別な作業は不要です。

アクションハンドラー

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

typedef kii_bool_t
  (*KII_THING_IF_ACTION_HANDLER)
    (const char* schema,
     int schema_version,
     const char* action_name,
     const char* action_params,
     char error[EMESSAGE_SIZE + 1]);

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

kii_bool_t action_handler(const char* schema,
    int schema_version,
    const char* action_name,
    const char* action_params,
    char error[EMESSAGE_SIZE + 1]) {

  /* Do something. */

  return KII_TRUE;
}

コールバック関数の実行（指定されたアクションの実行）が成功したときは KII_TRUE を、それ以外は KII_FALSE を戻り値として返します。この戻り値はアクションリザルトとしてモバイルアプリに通知されます。

各パラメータの意味は以下のとおりです。

schema：スキーマ名を指定します。スキーマ定義（Android, iOS）で使用したものを使用します。
schema_version：スキーマのバージョンを指定します。スキーマ定義で使用したものを使用します。
action_name：コマンドに含まれるアクションの名前です。スキーマ定義で使用したものを使用します。
action_params：コマンドのパラメータが JSON 文字列で渡されます。
error：エラーメッセージを返す領域へのポインタが渡されます。この引数は out パラメータです。戻り値が KII_TRUE の場合、操作は不要です。KII_FALSE の場合、最大 EMESSAGE_SIZE + 1 バイト（終端の NULL 文字込みで 51 バイト）の文字列をエラー情報として返却できます。

アクションの解析

コールバック関数内では、アクションごとに action_params の JSON を解析して目的の処理を実行します。

まず、以下のチェックを行います。

schema、schema_version パラメータのチェック

スキーマとスキーマバージョンが想定どおりかどうかを確認することをお勧めします。モバイルアプリのプログラムと Thing のプログラムは、バージョンが不一致になることがあります。詳細は概要をご覧ください。

必要に応じて、古いモバイルアプリからのコマンドを互換リクエストとして受け付けたり、知っているバージョンより新しいモバイルアプリからのコマンドをエラーにしたりする必要があります。

次に、以下のチェックを行い目的のアクションを識別した後、指定されたアクションを実行します（実行結果はコールバック関数の戻り値として返します）。

action_name パラメータのチェック

action_name パラメータの文字列によって、目的のアクションを検出します。action_name には、スキーマ定義（Android, iOS）で指定したアクション名が格納されています。たとえば、turnPower、 setPresetTemperature などの文字列が格納されているため、文字列の比較によって電源操作処理や温度設定処理に分岐します。
action_params パラメータのチェック

アクションごとにパラメータを解析して目的の処理を行います。action_params には、たとえば以下のような JSON 文字列が格納されています。
```
{"turnPower":true}
```
JSON 文字列の解析方法はアクションハンドラーの実装次第です。安全に処理できるのであればどのような解析処理を使用しても問題ありませんが、リファレンス実装に組み込まれている kii_json ライブラリを使用する方法が確実です。

アクションリザルト

Thing でコマンドを受信した際は、コマンドの各アクションに対する応答をアクションリザルトとしてモバイルアプリ側に返します。

アクションリザルトは、SDK によってアクションハンドラーの戻り値から自動的に生成されます。コールバック関数の戻り値の kii_bool_t と error パラメータの値は SDK によって、自動的にコマンドリザルトとしてアップロードされます。コマンドリザルトが登録されると、Thing Interaction Framework は、プッシュ通知ネットワークを通してモバイルアプリに通知するため、すぐに Thing の実行結果を知ることができます。