Receiving Push Message and Delaying Command Execution
You can set a callback function for checking received push messages in the SDK. If the confirmed message is a command, you can delay its execution. Your application must handle the pending commands appropriately. Once a command is pended, the SDK will not process it unless it is resent from the server.
If the command execution is not delayed, the SDK will handle the command appropriately. See Executing Commands to check how the command is handled.
Callback function for checking push message
A prototype of a callback function for checking push message is as follows:
typedef tio_bool_t (*TIO_CB_PUSH)(
const char* message,
size_t message_length,
void* userdata);
You will define the callback function on the basis of this prototype.
tio_bool_t tio_cb_push (
const char* message,
size_t message_length,
void* userdata)
{
/* Do something. */
return KII_FALSE;
}
If the content passed in message
is a command, you can delay its execution. Return KII_TRUE
if you want to delay the execution. Return KII_FALSE
otherwise.
Set this callback function using the setter function when you initialize the tio_handler_t
instance.
tio_handler_set_cb_push(&handler, tio_cb_push, &cb_push_userdata);
This callback function is optional. You only need to set it when you need it.
Here is a simple sample for delaying the command execution.
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;
}
You just need to save the content passed in message
in some way (a message queue, as shown in this example) and return KII_TRUE
. Note that this sample code only uses the existence of commandID
for judging if the content is a command or not. You might want to use a more appropriate method.
Executing commands
We use the tio_handler_parse_command
API for executing commands. You can execute each action in the command by setting the command string and the callback function for passing the parsed result.
Do not forget to save the action execution result so that you can later return the result to the server.
A prototype of a callback function for notifying the parsed result per action is as follows:
typedef void (*TIO_CB_PARSED_ACTION)(
char* command_id,
tio_action_t* action,
void* userdata);
You will define the callback function on the basis of this prototype.
void cb_parsed_action(
char* command_id,
tio_action_t* action,
void* userdata)
{
// DO action and memory result.
}
You will execute the tio_handler_parse_command
as follows:
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.
}
In the TIO_CB_PARSED_ACTION
callback function, use the action
parameters for each action to execute the requested actions.
Before start parsing the JSON, please check the following:
Check the
alias
parameter.Check if the value matches with a known trait name. You can check its length with the
alias_length
parameter.
Then, identify and execute the designated action as follows.
Check the
action_name
parameterIdentify the target action by checking the string in the
action_name
parameter. You can check its length with thealias_length
parameter. The action name specified in the trait definition is stored in theaction_name
parameter. For example, the string liketurnPower
andsetPresetTemperature
are contained in the parameter. By making the string comparison, the action handler can determine which action to execute.Check the
action_value
parameterParse the parameter and execute the requested action. The
action_value
stores thetio_action_value_t
union containing various values.
It is probably a good idea to save the action results in the alias
and action_name
pairs. In some cases, you may also need to sort the action results by command_id
. If this is the case, you should use the command_id
value.
Sending command execution result
Use the tio_handler_handle_command
API to send the command execution result.
You can send the execution result to the server by setting the command string and the callback function for setting the execution result per action in this API.
A prototype of the callback function for setting the execution result per action is as follows:
typedef void (*TIO_CB_ACTION)(
tio_action_t* action,
tio_action_err_t* err,
tio_action_result_data_t* data,
void* userdata);
You will define the callback function on the basis of this prototype.
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 */;
}
The callback should return KII_TRUE
when the action specified in action
is successfully executed. Otherwise, it should return KII_FALSE
. In case when the action execution failed, you can put an error message in theerr
. You can also put an arbitrary message in the data
regardless of if the action execution succeeded or failed.
You will execute the tio_handler_handle_command
as follows:
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.
}
Sample code
Here is a sample code of the delayed command execution. In this sample, we assume that commands are stored in a message queue by the push callback function. The app creates a task to execute the commands in the queue.
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);
}
}
The code gets a command string from the message queue. If the string is valid, actions in the command are executed with the tio_handler_parse_command
method. The command execution result is sent to the server with the tio_handler_handle_command
method.