Pushメッセージの受信とコマンドの遅延実行

SDK には受信した Push メッセージの確認用コールバック関数を設定することが出来ます。確認したメッセージがコマンドの場合、そのコマンドの実行を保留することが出来ます。保留されたコマンドはアプリ側で適切に処理をしなければなりません。一度保留されたコマンドはサーバーから再送されない限り SDK が処理することはありません。

保留しない場合は SDK が適切に処理を行います。どのような処理がされるかはコマンドの実行を参照ください。

Push メッセージ確認用コールバック関数

Push メッセージの確認用コールバック関数のプロトタイプは以下のとおりです。

typedef tio_bool_t (*TIO_CB_PUSH)(
        const char* message,
        size_t message_length,
        void* userdata);

このプロトタイプに基づいて以下のようなコールバック関数を記述します。

tio_bool_t tio_cb_push (
        const char* message,
        size_t message_length,
        void* userdata)
{
    /* Do something. */

    return KII_FALSE;
}

message で渡された内容がコマンドの際に、その実行を保留する場合は KII_TRUE を、それ以外は KII_FALSE を戻り値として返します。

このコールバック関数を tio_handler_t インスタンスの初期化時にセット関数を使用して設定してください。

tio_handler_set_cb_push(&handler, tio_cb_push, &cb_push_userdata);

このコールバック関数は必須ではありません。必要な場合にのみセットしてください。

コマンドの実行を保留する際の簡単なサンプルコードは以下のようになります。

void message_enqueue(const char* msg, size_t len);

tio_bool_t tio_cb_push(
        const char* message,
        size_t message_length,
        void* userdata)
{
    if (strstr(message, "\"commandID\"") != NULL) {
        message_enqueue(message, message_length);
        return KII_TRUE;
    }
    return KII_FALSE;
}

message で渡された内容を任意(ここではメッセージキューを想定)の方法で保存し、 KII_TRUE を返すだけです。このサンプルコードでは内容がコマンドかどうかを "commandID" の有無で見ていますが、判定の方法は様々ですので注意してください。

コマンドの実行

コマンドの実行には tio_handler_parse_command APIを使用します。このAPIにコマンド文字列とコマンド内のアクションごとに解析結果を渡してくれるコールバック関数を渡すことでコマンド内のアクションごとに実行を行うことができます。後述の実行結果をサーバに返すために、アクションの実行の際に実行結果を保存することを忘れないように注意してください。

アクションごとの解析結果通知用コールバック関数のプロトタイプは以下の通りです。

typedef void (*TIO_CB_PARSED_ACTION)(
        char* command_id,
        tio_action_t* action,
        void* userdata);

このプロトタイプに基づいて以下のようなコールバック関数を記述します。

void cb_parsed_action(
        char* command_id,
        tio_action_t* action,
        void* userdata)
{
   // DO action and memory result.
}

tio_handler_parse_command の呼び出し方は以下のようになります。

tio_code_t res = tio_handler_parse_command(
        handler,
        command,
        command_length,
        cb_parsed_action,
        cb_parsed_action_userdata);

if (res != TIO_ERR_OK) {
    // error handle.
}

TIO_CB_PARSED_ACTION コールバック関数でアクションごとに action の各パラメータを使用して目的の処理を実行します。

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

alias パラメータのチェック

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

次に、以下のチェックを行い目的のアクションを識別した後、指定されたアクションを実行します。

action_name パラメータのチェック

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

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

alias と action_name の組でアクションの実行結果を保存するのが良いと思われます。場合によっては command_id での選り分けも必要になるかもしれませんので、その場合は command_id 値を使用してください。

コマンド実行結果の送信

コマンドの実行結果の送信には tio_handler_handle_command APIを使用します。このAPIにコマンド文字列とアクションごとの実行結果設定用コールバック関数で実行結果を設定することでサーバーへ実行結果を送信することが出来ます。

アクションごとの実行結果設定用コールバック関数のプロトタイプは以下の通りです。

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

このプロトタイプに基づいて以下のようなコールバック関数を記述します。

tio_bool_t cb_action_result(
        tio_action_t* action,
        tio_action_err_t* err,
        tio_action_result_data_t* data,
        void* userdata)
{
    // Set result of parsed_action_cb.
    return KII_TRUE/* or KII_FALSE */;
}

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

tio_handler_handle_command の呼び出し方は以下のようになります。

tio_code_t res = tio_handler_handle_command(
        handler,
        command,
        command_length,
        cb_action_result,
        cb_action_result_userdata);

if (res != TIO_ERR_OK) {
    // error handle.
}

サンプルコード

Push コールバック関数でメッセージキューに保存したコマンドをアプリ側で用意したタスクで実行する想定のサンプルコードを以下に記述します。

void other_application_task(tio_handler_t* handler) {
   char msg_buff[MAX_MSG_SIZE];

   while(1) {
       size_t msg_len = message_dequeue(msg_buff, MAX_MSG_SIZE);
       if (msg_len > 0) {
           tio_code_t res = tio_handler_parse_command(
                   handler,
                   msg_buff,
                   msg_len,
                   cb_parsed_action,
                   cb_parsed_action_userdata);

           if (res != TIO_ERR_OK) {
               // error handle.
           }

           res = tio_handler_handle_command(
                   handler,
                   msg_buff,
                   msg_len,
                   cb_action_result,
                   cb_action_result_userdata);

           if (res != TIO_ERR_OK) {
               // error handle.
           }
       }
       sleep(1);
   }
}

メッセージキューからコマンド文字列を取り出しそれが有効なら tio_handler_parse_command でコマンド内の各アクションの実行を行い、 tio_handler_handle_command でコマンドの実行結果をサーバーへ送信しています。