Connect to IoT Platform over MQTT - - Alibaba Cloud Documentation Center

This topic describes the API operations that you must call when you use Link SDK for C to connect a device to IoT Platform over Message Queuing Telemetry Transport (MQTT).

IOT_MQTT_Construct

Prototype

void *IOT_MQTT_Construct(iotx_mqtt_param_t *pInitParams)

Description
If you set the pInitParams parameter to NULL when you call the operation to connect to IoT Platform over MQTT, the default values are used for other parameters.

Parameter

Parameter	Type	Category	Description
pInitParams	iotx_mqtt_param_t *	Request	The MQTT initialization parameter. If you specify NULL for the request parameter, the default values are used for the parameters in the struct.

Parameters in the struct

typedef struct {
    uint16_t                   port;
    const char                 *host;
    const char                 *client_id;
    const char                 *username;
    const char                 *password;
    const char                 *pub_key;
    const char                 *customize_info;
    uint8_t                    clean_session;
    uint32_t                   request_timeout_ms;
    uint32_t                   keepalive_interval_ms;
    uint32_t                   write_buf_size;
    uint32_t                   read_buf_size;
    iotx_mqtt_event_handle_t    handle_event;
} iotx_mqtt_param_t, *iotx_mqtt_param_pt;

Parameter	Description
port	The port number of the MQTT server.
host	The endpoint of the MQTT server.
client_id	The ID of the MQTT client.
username	The username that is used to log on to the MQTT server.
password	The password that is used to log on to the MQTT server.
pub_key	The encryption method and key for the MQTT connection.
clean_session	Specifies whether to use the clean session feature of MQTT.
request_timeout_ms	The timeout period for MQTT messages.
keepalive_interval_ms	The timeout period for MQTT heartbeats.
write_buf_size	The maximum size of the buffer that is used to store MQTT messages to be sent.
read_buf_size	The maximum size of the buffer that is used to store received MQTT messages.
handle_event	The custom callback function that you want to use to receive event data from an MQTT module.
customize_info	The custom data to be reported. Separate key-value pairs in a string with commas (,). For example, `"pid=123456,mid=abcd";` is used to describe the information about a manufacturer and a module.

Note

If you set the elements in the pInitParams struct to 0 or set the pInitParams parameter to NULL, the default predefined parameters are used.

Return values
Value
Description
NULL
Failed
Non-NULL
MQTT handle

IOT_MQTT_Destroy

Prototype
```
int IOT_MQTT_Destroy(void **phandle);
```
Description
You can call this operation to close an MQTT connection and release the related resources.
Parameters
Parameter
Type
Category
Description
phandle
void **
Request
The MQTT handle. You can set the parameter to NULL.
Return values
Value
Description
0
Successful
< 0
Failed

IOT_MQTT_Yield

Prototype

int IOT_MQTT_Yield(void *handle, int timeout_ms);

Description
You can call this operation to receive network packets and forward the messages in the network packets to a custom callback function.
Parameters
Parameter
Type
Category
Description
handle
void *
Request
The MQTT handle. You can set the parameter to NULL.
timeout_ms
int
Request
The timeout period for the requests to receive packets.
Return value description
Value
Description
0
Successful

IOT_MQTT_CheckStateNormal

Prototype

int IOT_MQTT_CheckStateNormal(void *handle);

Description
You can call this operation to query the status of an MQTT connection.
Parameters
Parameter
Type
Category
Description
handle
void *
Request
The MQTT handle. You can set the parameter to NULL.
Return value description
Value
Description
0
Disconnected
1
Connected

IOT_MQTT_Subscribe

Prototype

int IOT_MQTT_Subscribe(void *handle,
                        const char *topic_filter,
                        iotx_mqtt_qos_t qos,
                        iotx_mqtt_event_handle_func_fpt topic_handle_func,
                        void *pcontext);

Description
You can call this operation to subscribe to an MQTT topic of IoT Platform.

Parameters

Parameter	Type	Category	Description
handle	void *	Request	The MQTT handle. You can set the parameter to NULL.
topic_filter	const char *	Request	The topic to which you want to subscribe.
qos	iotx_mqtt_qos_t	Request	The quality of service (QoS) policy.
topic_handle_func	iotx_mqtt_event_handle_func_fpt	Request	The callback function that you want to use to receive MQTT messages.
pcontext	void *	Request	The custom context. The context is returned from the callback function.

Return value description
Value
Description
0
Successful
< 0
Failed

IOT_MQTT_Subscribe_Sync

Prototype

int IOT_MQTT_Subscribe_Sync(void *handle,
                            const char *topic_filter,
                            iotx_mqtt_qos_t qos,
                            iotx_mqtt_event_handle_func_fpt topic_handle_func,
                            void *pcontext,
                            int timeout_ms);

Description
You can call this operation to subscribe to an MQTT topic of IoT Platform. This operation works in a synchronous manner.

Parameters

Parameter	Type	Category	Description
handle	void *	Request	The MQTT handle. You can set the parameter to NULL.
topic_filter	const char *	Request	The topic to which you want to subscribe.
qos	iotx_mqtt_qos_t	Request	The QoS policy.
topic_handle_func	iotx_mqtt_event_handle_func_fpt	Request	The callback function that you want to use to receive MQTT messages.
pcontext	void *	Request	The custom context. The context is returned from the callback function.
timeout_ms	int	Request	The timeout period for the synchronous call.

Return value description
Value
Description
0
Successful
< 0
Failed

IOT_MQTT_Unsubscribe

Prototype

int IOT_MQTT_Unsubscribe(void *handle, const char *topic_filter);

Description
You can call this operation to unsubscribe from a topic of IoT Platform.
Parameters
Parameter
Type
Category
Description
handle
void *
Request
The MQTT handle. You can set the parameter to NULL.
topic_filter
const char *
Request
The topic from which you want to unsubscribe.
Return value description
Value
Description
0
Successful
< 0
Failed

IOT_MQTT_Publish

Prototype

int IOT_MQTT_Publish(void *handle, const char *topic_name, iotx_mqtt_topic_info_pt topic_msg);

Description
You can call this operation to push messages to a topic.

Parameters

Parameter	Type	Category	Description
handle	void *	Request	The MQTT handle. You can set the parameter to NULL.
topic_name	const char *	Request	The topic to which you want to push messages.
topic_msg	iotx_mqtt_topic_info_pt	Request	The messages that you want to push.

Return value description

Value	Description
> 0	Successful. The value is returned when QoS 1 messages are received. The value is the ID of the MQTT message that is contained in the reported packet. The value corresponds to the value of the `messageId` field in the MQTT protocol.
0	Successful. The value is returned when QoS 0 messages are received.
< 0	Failed

IOT_MQTT_Publish_Simple

Prototype

int IOT_MQTT_Publish_Simple(void *handle, const char *topic_name, int qos, void *data, int len)

Description
You can call this operation to push messages to a topic.
Note
- IOT_MQTT_Publish: sends common messages.
- IOT_MQTT_Publish_Simple: sends messages with more configuration options.
You can call the IOT_MQTT_Publish operation to send common messages. You can call the IOT_MQTT_Publish_Simple operation to send messages with more configuration options.

Parameters

Parameter	Type	Category	Description
handle	void *	Request	The MQTT handle. You can set the parameter to NULL.
topic_name	const char *	Request	The topic to which you want to push messages.
qos	int	Request	The QoS policy.
data	void *	Request	The messages that you want to push.
len	int	Request	The length of the messages.

Return value description

Value	Description
> 0	Successful. The value is returned when QoS 1 messages are received. The value is the ID of the MQTT message that is contained in the reported packet. The value corresponds to the value of the `messageId` field in the MQTT protocol.
0	Successful. The value is returned when QoS 0 messages are received.
< 0	Failed

Value	Description
0	Disconnected
1	Connected