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

This topic describes the device shadow APIs of the C Link SDK.

IOT_Shadow_Construct

Syntax

void *IOT_Shadow_Construct(iotx_shadow_para_pt pparams);

Description
Connects to the cloud and creates a device shadow.
Parameters
Parameter
Data type
Direction
Description
pparams
iotx_shadow_para_pt
Input
The initialization parameters for the Shadow module.
Return value
Value
Description
NULL
Failed
Not NULL
The Shadow handle.

IOT_Shadow_Destroy

API prototype

iotx_err_t IOT_Shadow_Destroy(void *handle);

Description
Disconnects from the network and destroys all resources of the device shadow module.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The Shadow handle.
Return value
For more information, see include/exports/iot_export_errno.h.

IOT_Shadow_Yield

Function Prototype

void IOT_Shadow_Yield(void *handle, uint32_t timeout_ms);

Description
Retrieves messages from the network. This function must be called periodically.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The Shadow handle.
timeout
uint32_t
Input
The timeout period for retrieving a message from the network.
Return value
None.

IOT_Shadow_RegisterAttribute

API Prototype

iotx_err_t IOT_Shadow_RegisterAttribute(void *handle, iotx_shadow_attr_pt pattr);

Description
This function registers a callback function for a specific property ID in the Thing Specification Language (TSL). When an operation on the property is received, the corresponding callback function is triggered.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The Shadow handle.
pattr
iotx_shadow_attr_pt
Input
The information about the property to register.
Return value
For more information, see include/exports/iot_export_errno.h.

IOT_Shadow_DeleteAttribute

Interface Prototype

iotx_err_t IOT_Shadow_DeleteAttribute(void *handle, iotx_shadow_attr_pt pattr);

Description
This function deletes a property from the device shadow.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The Shadow handle.
pattr
iotx_shadow_attr_pt
Input
The information about the property to delete.
Return value
For more information, see include/exports/iot_export_errno.h.

IOT_Shadow_PushFormat_Init

Function Prototype

iotx_err_t IOT_Shadow_PushFormat_Init(void *pshadow,
                                      format_data_pt pformat,
                                      char *buf,
                                      uint16_t size);

Description
Initializes the message handle before reporting device shadow information.

Parameters

Parameter	Data type	Direction	Description
handle	void *	Input	The shadow handle.
pformat	format_data_pt	Input	The message handle to initialize.
buf	char *	Input	The buffer to store the message.
size	uint16_t	Input	The length of `buf`.

Return value
For more information, see include/exports/iot_export_errno.h.

IOT_Shadow_PushFormat_Add

API Prototype

iotx_err_t IOT_Shadow_PushFormat_Add(void *pshadow,
                                     format_data_pt pformat,
                                     iotx_shadow_attr_pt pattr)

Description
Adds device shadow information to the message handle after the handle is initialized by IOT_Shadow_PushFormat_Init.

Parameters

Parameter	Data type	Direction	Description
pshadow	void *	Input	The Shadow handle.
pformat	format_data_pt	Input	The message handle to be initialized.
pattr	iotx_shadow_attr_pt	Input	The shadow information to add to the message handle.

Return value
For more information, see include/exports/iot_export_errno.h.

IOT_Shadow_PushFormat_Finalize

Interface Prototype

iotx_err_t IOT_Shadow_PushFormat_Finalize(void *pshadow, format_data_pt pformat);

Description
Encapsulates the message handle to generate the final message after all shadow information is added.
Parameters
Parameter
Data type
Direction
Description
pshadow
void *
Input
The Shadow handle.
pformat
format_data_pt
Input
The message handle to encapsulate.
Return value
For more information, see include/exports/iot_export_errno.h.

IOT_Shadow_Push

Interface Prototype

iotx_err_t IOT_Shadow_Push(void *handle, char *data, uint32_t data_len, uint16_t timeout_s);

Description
This is a synchronous function that sends a message to the cloud to operate on the device shadow.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The Shadow handle.
data
char *
Input
The message payload to send to the cloud.
data_len
uint32_t
Input
The length of the data.
Return value
For more information, see include/exports/iot_export_errno.h.

IOT_Shadow_Push_Async

Interface Prototype

int IOT_Shadow_Push_Async(void *handle,
                            char *data,
                            size_t data_len,
                            uint16_t timeout_s,
                            iotx_push_cb_fpt cb_fpt,
                            void *pcontext);

Description
This is an asynchronous function that sends a message to the cloud to operate on the device shadow.

Parameters

Parameter	Data type	Direction	Description
handle	void *	Input	The Shadow handle.
data	char *	Input	The message payload to send to the cloud.
data_len	uint32_t	Input	The length of the `data`.
timeout_s	uint16_t	Input	The timeout period, in seconds, to wait for a message acknowledgement.
cb_fpt	iotx_push_cb_fpt	Input	The callback function that is triggered when a message acknowledgement is received.
pcontext	void *	Input	The user context. It is returned to the user through the callback function when a message acknowledgement is received.

Return value
Value
Description
0
Success
< 0
Failed

IOT_Shadow_Pull

Function Prototype

iotx_err_t IOT_Shadow_Pull(void *handle);

Description
This function retrieves the device shadow from the cloud.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The Shadow handle.
Return value
For more information, see include/exports/iot_export_errno.h.

Value	Description
NULL	Failed
Not NULL	The Shadow handle.

Value	Description
0	Success
< 0	Failed