Writing Methods in C

A client application uses the action APIs to implement methods to call from Device Cloud.

When a method is executed from Device Cloud, the agent processes the registered action callback or command in a worker thread.

The function parameters max_time_out and txn are for future use.

The thing definition that corresponds to your application must have the method defined, including the notification variables (parameters). For more information about defining methods, see Device Cloud Management Portal User's Guide: Defining Methods.

You must have previously initialized your application (see Initializing Your C Application).

You need to know the method key defined in the thing definition.

For notification variables, you need to know the key and the data type.

To receive methods, the application must be connected to Device Cloud.

  1. Allocate the memory for the method.

    For the handle parameter, specify the value returned from the iot_initialize function, which you called when you registered your application.

    For the name parameter, specify the method key defined in the thing definition.

    iot_action_t* myAction;
myAction = iot_action_allocate(agentLib, "myAction" );
  2. Optionally, add one or more parameters to the method.

    For the name parameter, specify the notification variable key defined for the method in the thing definition.

    For the data_type parameter, specify the data type that matches the notification variable type defined for the method in the thing definition.

    For the max_time_out parameter, specify zero.

    For the param_type parameter, specify IOT_PARAMETER_IN for optional parameters and IOT_PARAMETER_IN_REQUIRED for required parameters.

    To specify that a parameter is both an input parameter and an action response, specify either (IOT_PARAMETER_IN | IOT_PARAMETER_OUT) or (IOT_PARAMETER_IN_REQUIRED | IOT_PARAMETER_OUT_REQUIRED). The parameter must be defined as both a notification variable and a completion variable in the thing definition.

    If you use a script as the action handler, ensure that the parameter name contains only alphanumeric characters, period (., and hyphen (-).

    result = iot_action_parameter_add( myAction, "parm_int", 
                                   IOT_PARAMETER_IN_REQUIRED, IOT_TYPE_UINT32, 0);
result = iot_action_parameter_add( myAction, "parm_string", 
                                   IOT_PARAMETER_IN_REQUIRED, IOT_TYPE_STRING, 0);
  3. Optionally, add one or more parameters to return as an action response.

    For the name parameter, specify the completion variable key defined for the method in the thing definition.

    For the data_type parameter, specify the data type that matches the completion variable type defined for the method in the thing definition.

    For the max_time_out, specify zero.

    For the param_type parameter, specify IOT_PARAMETER_OUT for optional parameters and IOT_PARAMETER_OUT_REQUIRED for required parameters.

    iot_action_parameter_add( myAction, "boolean_response", 
                          IOT_PARAMETER_OUT_REQUIRED, IOT_TYPE_BOOL, 0u );
  4. If you use a C function as the action handler, write the function as follows:
    1. Use the following function signature: 
      iot_action_status_t myActionCallback( iot_action_request_t *request, void* user_data )
    2. If you registered parameters with the action, retrieve the parameter values sent from Device Cloud.

      Specify the parameter name and memory to store the returned value.

      For the convert parameter, specify IOT_FALSE.

      iot_status_t result;
const char* param_name_int = "parm_int";
const char* param_name_string = "parm_string";
int32_t value_int = 0;
const char* value_string = NULL; 
result = iot_action_parameter_get( request, param_name_int, IOT_FALSE, 
                                   IOT_TYPE_UINT32, &value_int );
result = iot_action_parameter_get( request, param_name_string, IOT_FALSE, 
                                   IOT_TYPE_STRING,
                                   &value_string);
    3. Optionally, send a response to Device Cloud. 
      result = iot_action_parameter_set( &request, "boolean_response", IOT_TYPE_BOOL, IOT_TRUE);
  5. Register an action handler for the method.
    OptionDescription

    Register a callback function.

    Specify the address of the C function you created.

    For the txn parameter, specify NULL, and for the max_time_out parameter, specify zero.

    void* user_data;

user_data = malloc( 1u );
result = iot_action_register_callback( myAction, 
                                       &myActionCallback, 
                                       user_data, NULL, 0 );

    You can also specify NULL for the user_data parameter.

    Register a script.

    Specify the command, including the full path, to execute.

    For the txn parameter, specify NULL, and for the max_time_out parameter, specify zero.

    result = iot_action_register_command( myAction, 
                                      "/pathTo/test.sh", 
                                      NULL, 0 );

    If you register more than one action handler (for example, a callback function and a script), the register function returns an error.

When your application runs, the method appears on the thing details page under the Methods tab.

When a method is executed, the return status and the value of any output parameters appear in the mailbox logs, and the output parameter values appear in the Output box when the method is called from the thing page.

Examples

The iot-app-simple-actions sample application provided with the agent shows example code for methods.

When you no longer need the command, call iot_action_deregister and iot_action_free to free the memory allocated for the action.