设备影子

更新时间：2018-10-24 21:53:40

背景信息

设备影子是指通过特别的Topic在云端构建一个设备的影子，设备同步状态至云端。当设备离线时，云端仍可以快速通过影子获取到设备的状态。</span>

注：对于支持物模型的产品，上报的信息在云端均有保存，因此设备影子只适用于阿里云IoT物联网平台基础版的产品。

操作步骤

• 设备C-SDK提供接口IOT_Shadow_Construct ，创建设备影子。</span>函数声明如下：

/**

* @brief Construct the Device Shadow.

* This function initialize the data structures, establish MQTT connection.

* and subscribe the topic: "/shadow/get/${YourProduct_key}/${YourDevice_name}".

*
* @param [in] pparam: The specific initial parameter.

* @retval NULL : Construct shadow failed.

* @retval NOT_NULL : Construct success.

* @see None.

*/
void *IOT_Shadow_Construct(iotx_shadow_para_pt pparam);

• 使用IOT_Shadow_RegisterAttribute接口，注册设备影子的属性。</span>函数声明如下：

/**

* @brief Create a data type registered to the server.

*
* @param [in] handle: The handle of device shaodw.

* @param [in] pattr: The parameter which registered to the server.

* @retval SUCCESS_RETURN : Success.

* @retval other : See iotx_err_t.

* @see None.

*/
iotx_err_t IOT_Shadow_RegisterAttribute(void *handle, iotx_shadow_attr_pt pattr);

• 设备影子在每次开机时，设备C-SDK提供IOT_Shadow_Pull接口，从云端同步设备状态。</span>函数声明如下：

/**

* @brief Synchronize device shadow data from cloud.

* It is a synchronous interface.

* @param [in] handle: The handle of device shaodw.

* @retval SUCCESS_RETURN : Success.

* @retval other : See iotx_err_t.

* @see None.

*/
iotx_err_t IOT_Shadow_Pull(void *handle);

• 当设备端状态发生变化时，设备C-SDK提供接口IOT_Shadow_PushFormat_Init、IOT_Shadow_PushFormat_Add和IOT_Shadow_PushFormat_Finalize接口更新状态，通过接口IOT_Shadow_Push将状态同步到云端。</span>函数声明如下：

/**

* @brief Start a process the structure of the data type format.

*
* @param [in] handle: The handle of device shaodw.

* @param [out] pformat: The format struct of device shadow.

* @param [in] buf: The buf which store device shadow.

* @param [in] size: Maximum length of device shadow attribute.

* @retval SUCCESS_RETURN : Success.

* @retval other : 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 update.

*
* @param [in] handle: The handle of device shaodw.

* @param [in] pformat: The format struct of device shadow.

* @param [in] pattr: To have created the data type of the format in the add member attributes.

* @retval SUCCESS_RETURN : Success.

* @retval other : 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 a process the structure of the data type format.

*
* @param [in] handle: The handle of device shaodw.

* @param [in] pformat: The format struct of device shadow.

* @retval SUCCESS_RETURN : Success.

* @retval other : See iotx_err_t.

* @see None.

*/
iotx_err_t IOT_Shadow_PushFormat_Finalize(void *handle, format_data_pt pformat);

• 当设备需要与云端断开连接时，设备C-SDK提供接口IOT_Shadow_DeleteAttribute和IOT_Shadow_Destroy，删除云端创建的属性并释放设备影子。</span>函数声明如下：

/**

* @brief Deconstruct the specific device shadow.

*
* @param [in] handle: The handle of device shaodw.

* @retval SUCCESS_RETURN : Success.

* @retval other : See iotx_err_t.

* @see None.

*/
iotx_err_t IOT_Shadow_Destroy(void *handle);