Device shadow-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

Background information

A device shadow is a virtual representation of a device's state stored in the cloud. Devices use a specific topic to create a shadow and sync their state to it. When a device is offline, you can retrieve its last known state from the shadow.

Note For products in IoT Platform that use a Thing Specification Language (TSL) model, their properties are stored in the cloud. You do not need to use a device shadow to save their data.

Procedure

Use the `IOT_Shadow_Construct` interface from the device C-SDK to create a device shadow. The function declaration is as follows:

/**
* @brief Construct the Device Shadow.
* This function initializes the data structures, establishes an MQTT connection,
* and subscribes to the topic: "/shadow/get/${YourProduct_key}/${YourDevice_name}".
*
* @param [in] pparam: The initial parameters.
* @retval NULL : Failed to construct the shadow.
* @retval NOT_NULL : The handle to the constructed shadow.
* @see None.
*/
void *IOT_Shadow_Construct(iotx_shadow_para_pt pparam);

Use the `IOT_Shadow_RegisterAttribute` interface to register the properties of the device shadow. The function declaration is as follows:

/**
* @brief Register a data type with the server.
*
* @param [in] handle: The handle of the device shadow.
* @param [in] pattr: The parameter to register with the server.
* @retval SUCCESS_RETURN : The operation was successful.
* @retval other : An error occurred. For details, see iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_RegisterAttribute(void *handle, iotx_shadow_attr_pt pattr);

Each time the device starts, use the `IOT_Shadow_Pull` interface to sync the state from the cloud. The function declaration is as follows:

/**
* @brief Sync device shadow data from the cloud.
* This is a synchronous interface.
* @param [in] handle: The handle of the device shadow.
* @retval SUCCESS_RETURN : The operation was successful.
* @retval other : An error occurred. For details, see iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_Pull(void *handle);

When the device state changes, use the `IOT_Shadow_PushFormat_Init`, `IOT_Shadow_PushFormat_Add`, and `IOT_Shadow_PushFormat_Finalize` interfaces to update the state. Then, use the `IOT_Shadow_Push` interface to sync the state to the cloud. The function declarations are as follows:

/**
* @brief Start the process of structuring the data type format.
*
* @param [in] handle: The handle of the device shadow.
* @param [out] pformat: The format struct of the device shadow.
* @param [in] buf: The buffer that stores the device shadow.
* @param [in] size: The maximum length of the device shadow attribute.
* @retval SUCCESS_RETURN : The operation was successful.
* @retval other : An error occurred. For details, see iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_PushFormat_Init(
                    void *handle,
                    format_data_pt pformat,
                    char *buf,
                    uint16_t size);


/**
* @brief Format the attribute name and value for the update.
*
* @param [in] handle: The handle of the device shadow.
* @param [in] pformat: The format struct of the device shadow.
* @param [in] pattr: The attribute to add to the formatted data payload.
* @retval SUCCESS_RETURN : The operation was successful.
* @retval other : An error occurred. For details, see iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_PushFormat_Add(
                    void *handle,
                    format_data_pt pformat,
                    iotx_shadow_attr_pt pattr);


/**
* @brief Complete the process of structuring the data type format.
*
* @param [in] handle: The handle of the device shadow.
* @param [in] pformat: The format struct of the device shadow.
* @retval SUCCESS_RETURN : The operation was successful.
* @retval other : An error occurred. For details, see iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_PushFormat_Finalize(void *handle, format_data_pt pformat);

When the device needs to disconnect from the cloud, use the `IOT_Shadow_DeleteAttribute` and `IOT_Shadow_Destroy` interfaces to delete the properties from the cloud and release the device shadow. The function declaration is as follows:

/**
* @brief Deconstruct the specified device shadow.
*
* @param [in] handle: The handle of the device shadow.
* @retval SUCCESS_RETURN : The operation was successful.
* @retval other : An error occurred. For details, see iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_Destroy(void *handle);