Methods

To enable Device Cloud to call a method from a trigger, the thing details page, or a campaign, client applications implement and register actions with the agent.

Methods are referred to as actions in the agent API.

The method and parameters are defined in the thing definition and methods appear under the Methods tab on the thing details page. Input and output parameters are specified as notification and completion variables, respectively. Valid data types are integer, float, string, and Boolean. For more information about defining methods, see Device Cloud Management Portal User's Guide: Defining Methods.

Method history appears in the things mailbox, which you can access from the Actions menu on the thing details page. For more info about viewing the history, see Device Cloud Management Portal User's Guide: Things: Viewing the Command History in the Mailbox of a Thing.

An application must register a handler to call when Device Cloud sends the method to the device. The handler can be either a function or any executable program on the device (a command).

Python provides functions that the callback function can optionally call to send progress updates that appear in the mailbox of the thing.

A command is any executable program on the device, including operating system commands. You might want to register a script as the command if you do not want to write code or if you want to reuse an existing script.

When the method is initiated from Device Cloud, the agent runs the command under the application process, but the application is not notified of the script execution. Parameters are passed to the script through stdin and the script is responsible for parsing the parameter data types and values correctly. Output is sent to stdout; commands cannot return a response to Device Cloud.

VxWorks only supports registering a command as a custom action for applications that run in kernel mode (DKMs).

The C action APIs have the following limits:

• seven parameters or fewer for a method

• maximum 255 methods

You can change the limits to a maximum value of 255 in the build.yml file in the agent source code you download from GitHub.

Table 1. Python Method APIs

Function	Description
action_deregister	Deregister a method from Device Cloud.
action_progress_update	Send a progress update to Device Cloud.
action_register_callback	Register a function to call when a method is called from Device Cloud.
action_register_command	Register a method with Device Cloud.

Table 2. C Method APIs

Function	Description
iot_action_allocate	Create a method and allocate the required memory.
iot_action_check	Adds an action check operation for tr50_mailbox_check. Note: The mailbox check size is limited to 1. An additional mailbox check is done on completion of an action.
iot_action_deregister	Deregister a method from the agent.
iot_action_free	Destroy a method and free the associated memory.
iot_action_parameter_add	Add a parameter to a method.
iot_action_parameter_get	Retrieve the value of a parameter.
iot_action_parameter_get_raw	Retrieve the value of a raw (base64-encoded) parameter.
iot_action_parameter_set	Return a value in response to the method.
iot_action_parameter_set_raw	Return a raw (base64-encoded) value in response to the method.
iot_action_register	Register a method with the agent.
iot_action_register_callback	Register a callback function to call when the specified method is called from Device Cloud.
iot_action_register_command	Register a system command to call when the specified method is called from Device Cloud.