Implementing the Reception Handler

The Thing SDK Embedded has a functionality of an MQTT client to enable MQTT push notification. You can have the SDK call a function registered as a handler to execute custom processes when the SDK receives a push message.

The implementation method varies according to whether the Thing-IF SDK is used with the Thing SDK Embedded.

If the Thing-IF SDK is used together

If you use the Thing-IF SDK with the Thing SDK Embedded, you can hook a push message with a custom push handler.

The Thing-IF SDK can receive MQTT messages. It receives both the push messages of the Kii Cloud SDK and the commands of Thing Interaction Framework as push notifications. The Thing-IF SDK relays all the push messages to the custom push handler. The custom push handler processes only the push messages which are recognizable to it and returns the remaining messages to the Thing-IF SDK. The Thing-IF SDK checks if it can interpret the messages as commands and then calls the action handler.

The custom push handler returns a value which indicates whether the handler processed the push message.

  • If KII_TRUE is returned: The user program has processed the push message. The Thing-IF SDK does not need to parse it further.
  • If KII_FALSE is returned: The user program has not processed the push message. The Thing-IF SDK needs to interpret it as a Thing Interaction Framework message such as a command.

See the below sample code for the custom push handler. The handler parses the content of message with the if condition. If message is recognizable, the handler processes message and returns KII_TRUE.

kii_bool_t custom_push_handler(
        kii_t *kii,
        const char* message,
        size_t message_length)
{
  /* If the message is recognized by the custom push handler */
  if (...) {
    /* Do something. */
    return KII_TRUE;
  }

  /* Let the Thing-IF SDK process the message. */
  return KII_FALSE;
}
  • kii receives the kii_t structure of the command handler. When the custom push handler sends a request to Kii Cloud, limits such as the maximum message size are the same as the values specified for the command handler at the initialization.
  • message receives the pointer to the entire JSON string of the push message and message_length receives the length of the push message. Bear in mind that the buffer for message is not null-terminated.

See the examples of Push to App and Push to User notifications for sample JSON strings received with message. You can use the kii_json library to parse JSON strings.

Specify the custom push handler as custom_push_handler of the kii_thing_if_command_handler_resource_t structure when you initialize the Thing-IF SDK. If you do not specify this handler, no custom push handler is used and all the push messages are interpreted as commands of Thing Interaction Framework.

kii_thing_if_command_handler_resource_t command_handler_resource;
......
command_handler_resource.custom_push_handler = custom_push_handler;
......
result = init_kii_thing_if(&kii_thing_if, EX_APP_ID, EX_APP_KEY, EX_APP_SITE,
        &command_handler_resource, &state_updater_resource, NULL);

If the Thing-IF SDK is not used together

If you do not use the Thing-IF SDK with the Thing SDK Embedded, create a new push handler. At the same time, create threads to process push notifications via MQTT.

See the below sample code for the push handler.

void received_callback(kii_t* kii, char* buffer, size_t buffer_size)
{
    char copy[1024];
    memset(copy, 0x00, sizeof(copy));
    strncpy(copy, buffer, sizeof(copy) - 1);
    printf("buffer_size: %lu\n", buffer_size);
    printf("recieve message: %s\n", copy);
}
  • kii receives the kii_t structure from kii_push_start_routine, which will be explained in this topic later.
  • buffer receives the pointer to the entire JSON string of the push message and buffer_size receives the length of the push message. Bear in mind that the buffer for buffer is not null-terminated.

See the examples of Push to App and Push to User notifications for sample JSON strings received with buffer. You can use the kii_json library to parse JSON strings.

Specify the push handler with kii_push_start_routine. This API creates an MQTT reception thread and a thread which periodically sends the MQTT PINGREQ command. The push handler is called from the MQTT reception thread.

/* Set MQTT processing parameters. */
#define TASK_PRIORITY 0
#define PING_REQ_TASK_PRIO 0

/* Start the push notification receiving routine. */
ret = kii_push_start_routine(&kii_for_push, TASK_PRIORITY, PING_REQ_TASK_PRIO, received_callback);
if (ret != 0) {
  /* Handle the error. */
  return;
}

See below for the arguments specified in the above sample code.

  • &kii_for_push

    Specify the kii_t structure for push notification.

    The kii_t structure specified as the first argument here is used for the MQTT reception thread. Therefore, the caller thread of kii_push_start_routine should not use it any longer. Using the kii_t structure in multiple threads at the same time might cause a defect which is difficult to reproduce because the structure contains send/receive buffers and so on. See Initializing the SDK for more information.

  • TASK_PRIORITY

    Specify the priority of the MQTT reception thread. This value is relayed to task_create_cb, which creates a thread, through its sixth argument priority. This parameter is supposed to be used for specifying the priority of threads and tasks, but the eventual use of the parameter is determined by the OS-dependent processes. See kii/Linux/kii_task_impl.c for a sample implementation. This file is one of the source files of the Linux reference implementation with the Thing SDK Embedded.

  • PING_REQ_TASK_PRIO

    Specify the priority of the thread to periodically send the PINGREQ command in the MQTT reception process. Specify this parameter in the same way as you specify TASK_PRIORITY.

  • received_callback

    Specify the function pointer of the push handler.