コマンドの実行

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

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

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

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

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

コマンド受信タスクの開始

アクションハンドラー用のコールバック関数とユーザデータ(サンプル内では action_handler_userdata)を引数に tio_handler_start を呼び出すことでコマンド受信タスクが生成され実行されるようになります。

呼び出しの際 kii_author_t が必要になります。これは初期登録を行ったインスタンスから取得してください。ここでは tio_handler_t インスタンスから取得しています。 tio_updater_t インスタンスで初期登録を行った場合は tio_updater_get_author を使用してください。

const kii_author_t* author = tio_handler_get_author(&handler);

tio_handler_start(
    &handler,
    author,
    tio_action_handler,
    &action_handler_userdata);

アクションハンドラーコールバック関数

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

typedef tio_bool_t (*TIO_CB_ACTION)(
    tio_action_t* action,
    tio_action_err_t* err,
    tio_action_result_data_t* data,
    void* userdata);

このプロトタイプに基づいて以下のようなアクションハンドラーを記述します。

tio_bool_t tio_action_handler(
    tio_action_t* action,
    tio_action_err_t* err,
    tio_action_result_data_t* data,
    void* userdata)
{
   /* Do something. */

  return KII_TRUE;
}

action で渡されたアクションの実行が成功したら KII_TRUE を、それ以外は KII_FALSE を戻り値として返します。また、アクションを実行して失敗した場合は err にエラーメッセージを入れてください。また、成功、失敗にかかわらず何らかのメッセージを設定したい場合は data にメッセージを入れてください。

アクションの解析

アクションごとに action の各パラメータを使用して目的の処理を実行します。

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

alias パラメータのチェック

既知のトレイトエイリアスであるか確認します。文字列長は alias_length パラメータで確認できます。

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

action_name パラメータのチェック

action_name パラメータの文字列によって、目的のアクションを検出します。文字列長は action_name_length パラメータで確認できます。 action_name には、トレイト定義で指定したアクション名が格納されています。たとえば、turnPower、 setPresetTemperature などの文字列が格納されているため、文字列の比較によって電源操作処理や温度設定処理に分岐します。
action_value パラメータのチェック

アクションごとにパラメータを解析して目的の処理を行います。action_value には、tio_action_value_t 共用体で色々な値が格納されています。

アクションリザルト

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

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