背景信息

設備影子是指通過特別的Topic在云端構建一個設備的影子，設備同步狀態至云端。當設備離線時，云端仍可以快速通過影子獲取到設備的狀態。

說明 對于使用物模型在物聯網平臺進行定義的產品，其屬性會保存在云端，無需使用設備影子來告知物聯網平臺保存其數據。

操作步驟

  1. 設備C-SDK提供接口IOT_Shadow_Construct ，創建設備影子。函數聲明如下：
    /**
* @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);
  2. 使用IOT_Shadow_RegisterAttribute接口，注冊設備影子的屬性。函數聲明如下：
    /**
* @brief Create a data type registered to the server.
*
* @param [in] handle: The handle of device shadow.
* @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);
  3. 設備影子在每次開機時，設備C-SDK提供IOT_Shadow_Pull接口，從云端同步設備狀態。函數聲明如下：
    /**
* @brief Synchronize device shadow data from cloud.
* It is a synchronous interface.
* @param [in] handle: The handle of device shadow.
* @retval SUCCESS_RETURN : Success.
* @retval other : See iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_Pull(void *handle);
  4. 當設備端狀態發生變化時，設備C-SDK提供接口IOT_Shadow_PushFormat_Init、IOT_Shadow_PushFormat_Add和IOT_Shadow_PushFormat_Finalize接口更新狀態，通過接口IOT_Shadow_Push將狀態同步到云端。函數聲明如下：
    /**
* @brief Start a process the structure of the data type format.
*
* @param [in] handle: The handle of device shadow.
* @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 shadow.
* @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 shadow.
* @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);
  5. 當設備需要與云端斷開連接時，設備C-SDK提供接口IOT_Shadow_DeleteAttribute和IOT_Shadow_Destroy，刪除云端創建的屬性并釋放設備影子。函數聲明如下：
    /**
* @brief Deconstruct the specific device shadow.
*
* @param [in] handle: The handle of device shadow.
* @retval SUCCESS_RETURN : Success.
* @retval other : See iotx_err_t.
* @see None.
*/
iotx_err_t IOT_Shadow_Destroy(void *handle);