API reference-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

The Alink protocol is a data exchange specification for Internet of Things (IoT) development. It uses the JSON data format to enable bidirectional communication between devices and IoT Platform. This topic describes the Alink protocol APIs.

Note

In a JSON message, the value of a message ID ranges from 0 to 4294967295. The ID is a string that represents a number, such as "12345".

IOT_Linkkit_Open

Function prototype

int IOT_Linkkit_Open(iotx_linkkit_dev_type_t dev_type, iotx_linkkit_dev_meta_info_t *meta_info);

Description
Initializes device resources. You must call this function before you perform any operations on a device. If the call is successful, a device ID is returned.
You can use the returned device ID as an input parameter for other functions to perform operations on the specified device.

Parameters

Parameter	Data type	Direction	Description
dev_type	iotx_linkkit_dev_type_t	Input	The type of the device for which you want to create resources.
meta_info	iotx_linkkit_dev_meta_info_t	Input	The device certificate.

Additional parameter information

typedef enum {
    IOTX_LINKKIT_DEV_TYPE_MASTER,
    IOTX_LINKKIT_DEV_TYPE_SLAVE,
    IOTX_LINKKIT_DEV_TYPE_MAX
} iotx_linkkit_dev_type_t;

Parameter	Description
IOTX_LINKKIT_DEV_TYPE_MASTER	The device to create is a master device. You can create a master device only once.
IOTX_LINKKIT_DEV_TYPE_SLAVE	The device to create is a sub-device.
IOTX_LINKKIT_DEV_TYPE_MAX	The maximum enumeration value for the device type.

typedef struct {
    char product_key[PRODUCT_KEY_MAXLEN];
    char product_secret[PRODUCT_SECRET_MAXLEN];
    char device_name[DEVICE_NAME_MAXLEN];
    char device_secret[DEVICE_SECRET_MAXLEN];
} iotx_linkkit_dev_meta_info_t;

Parameter	Description
product_key	The product key. The maximum length is 20 bytes.
product_secret	The product secret. The maximum length is 64 bytes.
device_name	The device name. The maximum length is 32 bytes.
device_secret	The device secret. The maximum length is 64 bytes.

Return values
Value
Description
>= 0
The device is created.
< 0
The device failed to be created.

IOT_Linkkit_Connect

Prototype
```
int IOT_Linkkit_Connect(int devid);
```
Description
- For a master device, this function establishes communication between the device and IoT Platform.
- For a sub-device, this function registers the sub-device with IoT Platform if registration is required and adds the topology relationship between the master device and the sub-device.
Parameters
Parameter
Data type
Direction
Description
devid
int
Input
The device ID.
Return values
Value
Description
0
Success.
< 0
Failure.

IOT_Linkkit_Yield

Prototype
```
void IOT_Linkkit_Yield(int timeout_ms);
```
Description
If the software development kit (SDK) runs in a dedicated thread, this function dispatches received network messages to your callback functions. Otherwise, this function yields the CPU to the SDK to receive network messages and dispatch them to your callback functions.
Parameters
Parameter
Data type
Direction
Description
timeout_ms
int
Input
In single-threaded mode, the timeout period for each attempt to receive network messages.
Return values
None.

IOT_Linkkit_Close

Prototype
```
int IOT_Linkkit_Close(int devid);
```
Description
- If the device ID belongs to a master device, this function closes the network connection and releases all resources that are used by the Linkkit SDK.
- If the device ID corresponds to a sub-device, the sub-device is disconnected from the cloud platform.
Parameters
Parameter
Data type
Direction
Description
devid
int
Input
The device ID.
Return values
Value
Description
0
Success.
< 0
Failure.

IOT_Linkkit_TriggerEvent

Prototype

int IOT_Linkkit_TriggerEvent(int devid, char *eventid, int eventid_len, char *payload, int payload_len);

Description
Reports a device event to IoT Platform.

Parameters

Parameter	Data type	Direction	Description
devid	int	Input	The device ID.
eventid	char *	Input	The event ID defined in the Thing Specification Language (TSL).
eventid_len	int	Input	The length of the event ID.
payload	char *	Input	The event payload.
payload_len	int	Input	The length of the event payload.

Return values
Value
Description
>= 1
The message ID.
< 0
Failure.

IOT_Linkkit_Report

Prototype

int IOT_Linkkit_Report(int devid,
                        iotx_linkkit_msg_type_t msg_type,
                        unsigned char *payload,
                        int payload_len);

Description
Sends a message to IoT Platform. The message can be a property report, a device tag update report, a device tag deletion report, a pass-through data report, a sub-device logon request, or a sub-device logout request.

Parameters

Parameter	Data type	Direction	Description
devid	int	Input	The device ID.
msg_type	iotx_linkkit_msg_type_t	Input	The type of the message to report.
payload	unsigned char *	Input	The message payload.
payload_len	int	Input	The length of the message payload.

Additional parameter information

typedef enum {
    ITM_MSG_POST_PROPERTY,
    ITM_MSG_DEVICEINFO_UPDATE,
    ITM_MSG_DEVICEINFO_DELETE,
    ITM_MSG_POST_RAW_DATA,
    ITM_MSG_LOGIN,
    ITM_MSG_LOGOUT,
    ...
    ...

    IOTX_LINKKIT_MSG_MAX
} iotx_linkkit_msg_type_t;

Parameter	Description
ITM_MSG_POST_PROPERTY	Reports device property data.
ITM_MSG_DEVICEINFO_UPDATE	Reports device tag update information.
ITM_MSG_DEVICEINFO_DELETE	Reports device tag deletion information.
ITM_MSG_POST_RAW_DATA	Reports pass-through data from a device.
ITM_MSG_LOGIN	A sub-device logs on.
ITM_MSG_LOGOUT	A sub-device logs out.
ITM_MSG_DELETE_TOPO	Deletes the topology relationship between a sub-device and a gateway.
ITM_MSG_REPORT_SUBDEV_FIRMWARE_VERSION	Reports the firmware version number of a sub-device. This is used for the over-the-air (OTA) update feature of the sub-device.
ITM_MSG_PROPERTY_DESIRED_GET	Retrieves the desired property values cached in the cloud. This is used for the device shadow of the Premium Edition.
ITM_MSG_PROPERTY_DESIRED_DELETE	Deletes the desired property values cached in the cloud. This is used for the device shadow of the Premium Edition.

Return values
Value
Description
0
Success.
>= 1
The message ID.
< 0
Failure.

IOT_Linkkit_Query

API prototype

int IOT_Linkkit_Query(int devid,
                        iotx_linkkit_msg_type_t msg_type,
                        unsigned char *payload,
                        int payload_len);

Description
Queries data from IoT Platform. The data can be a timestamp, a list of device topology relationships, firmware data for a COTA update, configuration file data for a COTA update, information about whether new firmware is available, or information about whether a configuration file is available.

Parameters

Parameter	Data type	Direction	Description
devid	int	Input	The device ID.
msg_type	iotx_linkkit_msg_type_t	Input	The type of the message to report.
payload	unsigned char *	Input	The message payload.
payload_len	int	Input	The length of the message payload.

Additional parameter information

typedef enum {
    ...
    ...
    ITM_MSG_QUERY_TIMESTAMP,
    ITM_MSG_QUERY_TOPOLIST,
    ITM_MSG_QUERY_FOTA_DATA,
    ITM_MSG_QUERY_COTA_DATA,
    ITM_MSG_REQUEST_COTA,
    ITM_MSG_REQUEST_FOTA_IMAGE,

    IOTX_LINKKIT_MSG_MAX
} iotx_linkkit_msg_type_t;

Parameter	Description
ITM_MSG_QUERY_TIMESTAMP	Queries a timestamp.
ITM_MSG_QUERY_TOPOLIST	Queries the list of device topology relationships.
ITM_MSG_QUERY_FOTA_DATA	Queries firmware data for a FOTA update.
ITM_MSG_QUERY_COTA_DATA	Queries remote configuration data for a COTA update.
ITM_MSG_REQUEST_FOTA_IMAGE	Queries whether new firmware is available.
ITM_MSG_REQUEST_COTA	Queries whether remote configuration data is available.

Return values
Value
Description
0
Success.
>= 1
The message ID.
< 0
Failure.

IOT_RegisterCallback

Prototype

define IOT_RegisterCallback(evt, cb)           iotx_register_for_##evt(cb);

Description
This function registers a callback function for an event. When the Linkkit SDK triggers an event, the corresponding callback function is called.
Parameters
Parameter
Data type
Direction
Description
evt
iotx_ioctl_event_t
Input
The event name.
cb
Varies based on the value of evt.
Input
The callback function.

Event list

typedef enum {
    ...
    ITE_CONNECT_SUCC,
    ...
    ITE_DISCONNECTED,
    ITE_RAWDATA_ARRIVED,
    ITE_SERVICE_REQUEST,
    ITE_PROPERTY_SET,
    ITE_PROPERTY_GET,
    ITE_REPORT_REPLY,
    ITE_TRIGGER_EVENT_REPLY,
    ITE_TIMESTAMP_REPLY,
    ITE_TOPOLIST_REPLY,
    ITE_PERMIT_JOIN,
    ITE_INITIALIZE_COMPLETED,
    ITE_FOTA,
    ITE_COTA
} iotx_ioctl_event_t;

Events

Event	Callback function prototype	Event trigger condition
ITE_CONNECT_SUCC	int callback(void);	A successful connection to the cloud is established.
ITE_DISCONNECTED	int callback(void);	Disconnected from the cloud.
ITE_RAWDATA_ARRIVED	int callback(const int devid, const unsigned char *payload, const int payload_len);	The Linkkit SDK receives `raw data`.
ITE_SERVICE_REQUEST	int callback(const int devid, const char serviceid, const int serviceid_len, const char request, const int request_len, char *response, int response_len);	The Linkkit SDK receives a synchronous or asynchronous service call request.
ITE_PROPERTY_SET	int callback(const int devid, const char *request, const int request_len);	The Linkkit SDK receives a request to set properties.
ITE_PROPERTY_GET	int callback(const int devid, const char *request, const int request_len, char response, int response_len);	The Linkkit SDK receives a request to query properties.
ITE_REPORT_REPLY	int callback(const int devid, const int msgid, const int code, const char *reply, const int reply_len);	The Linkkit SDK receives an acknowledgement for a reported message.
ITE_TRIGGER_EVENT_REPLY	int callback(const int devid, const int msgid, const int code, const char eventid, const int eventid_len, const char message, const int message_len);	The Linkkit SDK receives an acknowledgement for a reported event.
ITE_TIMESTAMP_REPLY	int callback(const char *timestamp);	The Linkkit SDK receives an acknowledgement for a timestamp query request.
ITE_TOPOLIST_REPLY	int callback(const int devid, const int msgid, const int code, const char * payload, const int payload_len);	The Linkkit SDK receives an acknowledgement for a topology relationship query request.
ITE_PERMIT_JOIN	int callback(const char * product_key, const int time);	The Linkkit SDK receives a request to allow a sub-device to join the network.
ITE_INITIALIZE_COMPLETED	int callback(const int devid);	Device initialization is complete.
ITE_FOTA	int callback(int type, const char *version);	The Linkkit SDK receives a notification that new firmware is available.
ITE_COTA	int callback(int type, const char config_id, int config_size, const char get_type, const char sign, const char sign_method, const char *url);	The Linkkit SDK receives a notification that a remote configuration file is available.

Return values
None.

IOT_Ioctl

Function Prototype
```
int IOT_Ioctl(int option, void *data);
```
Description
Configures global options for the SDK. If you use the Linkkit Premium Edition, you must call this function before you call IOT_Linkkit_Connect.
Parameters
Parameter
Data type
Direction
Description
option
int
Input
The operation to perform.
data
void *
Input/Output
The input or output parameter required for the option.

Additional parameter information

The following values are available for the option parameter:

typedef enum {
    IOTX_IOCTL_SET_REGION,
    IOTX_IOCTL_GET_REGION,
    IOTX_IOCTL_SET_MQTT_DOMAIN,
    IOTX_IOCTL_SET_HTTP_DOMAIN,
    IOTX_IOCTL_SET_DYNAMIC_REGISTER,
    IOTX_IOCTL_GET_DYNAMIC_REGISTER,
    IOTX_IOCTL_RECV_PROP_REPLY,
    IOTX_IOCTL_RECV_EVENT_REPLY,
    IOTX_IOCTL_SEND_PROP_SET_REPLY,
    IOTX_IOCTL_SET_SUBDEV_SIGN,
    IOTX_IOCTL_GET_SUBDEV_LOGIN
} iotx_ioctl_option_t;

Parameter	Description
IOTX_IOCTL_SET_REGION	Sets the region of the logon server. The data type of `data` is `int *`. For more information about the valid values, see the `iotx_cloud_region_types_t` enumeration in `iot_export.h`.
IOTX_IOCTL_GET_REGION	Gets the current region of the logon server. The data type of `data` is `int *`.
IOTX_IOCTL_SET_MQTT_DOMAIN	If the desired server region is not available for `IOTX_IOCTL_SET_REGION`, set the region of the ApsaraMQ for MQTT client. The data type of `data` is `char *`.
IOTX_IOCTL_SET_HTTP_DOMAIN	If the desired server region is not available for `IOTX_IOCTL_SET_REGION`, set the region of the HTTP server. The data type of `data` is `char *`.
IOTX_IOCTL_SET_DYNAMIC_REGISTER	Specifies whether to use a per-device secret. The data type of `data` is `int *`. A value of 1 specifies the one-device-one-secret method. The one-device-one-secret feature is disabled when the `data` value is 0.
IOTX_IOCTL_GET_DYNAMIC_REGISTER	Checks whether One-Device-One-Secret is in use.
IOTX_IOCTL_RECV_PROP_REPLY	This option is deprecated. It has the same function as `IOTX_IOCTL_RECV_EVENT_REPLY`.
IOTX_IOCTL_RECV_EVENT_REPLY	Controls whether an acknowledgement from the cloud is required when you report properties and events. The data type of `data` is `int *`. If the value of data is 1, an acknowledgement from the cloud is required. If the value of data is 0, an acknowledgement from the cloud is not required.
IOTX_IOCTL_SEND_PROP_SET_REPLY	Controls whether the SDK sends an acknowledgement to the cloud when it receives a message to set properties. The data type of `data` is `int *`. If the value of data is 1, the SDK sends an acknowledgement. If the value of data is 0, the SDK does not send an acknowledgement.
IOTX_IOCTL_SET_SUBDEV_SIGN	Reserved.
IOTX_IOCTL_GET_SUBDEV_LOGIN	Reserved.
IOTX_IOCTL_QUERY_DEVID	Gets the Devid of the sub-device that corresponds to a ProductKey and DeviceName. The input is a pointer to data of the `iotx_linkkit_dev_meta_info_t` type. The output is the Devid. If the sub-device does not exist, -1 is returned. For example, in `linkkit_example_gateway.c`, the following code gets the devid that corresponds to subdevArr[2] in the sub-device array. `int subdev_id = 0; subdev_id = IOT_Ioctl(IOTX_IOCTL_QUERY_DEVID, (void *)&subdevArr[2]);`

Return values
Value
Description
>= 0
Success.
< 0
Failure.

Value	Description
>= 0	The device is created.
< 0	The device failed to be created.

Value	Description
0	Success.
< 0	Failure.

Parameter	Data type	Direction	Description
timeout_ms	int	Input	In single-threaded mode, the timeout period for each attempt to receive network messages.

Value	Description
0	Success.
< 0	Failure.

Value	Description
>= 0	Success.
< 0	Failure.