MQTT接入 - - 阿里雲

本文介紹使用C Link SDK配置MQTT協議的裝置接入物聯網平台時，需調用的API。

IOT_MQTT_Construct

介面原型

void *IOT_MQTT_Construct(iotx_mqtt_param_t *pInitParams)

介面說明
與雲端建立MQTT串連，輸入參數pInitParams為NULL時將使用預設參數建連。
參數說明
參數
資料類型
方向
說明
pInitParams
iotx_mqtt_param_t *
輸入
MQTT初始化參數，填寫NULL將以預設參數建連。

參數附加說明

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;

參數	說明
port	雲端伺服器連接埠。
host	雲端伺服器位址。
client_id	MQTT用戶端ID。
username	登入MQTT伺服器使用者名稱。
password	登入MQTT伺服器密碼。
pub_key	MQTT串連的加密方式及密鑰。
clean_session	選擇是否使用MQTT協議的clean session特性。
request_timeout_ms	MQTT訊息發送的逾時時間。
keepalive_interval_ms	MQTT心跳逾時時間。
write_buf_size	MQTT訊息發送buffer的最大長度。
read_buf_size	MQTT訊息接收buffer的最大長度。
handle_event	使用者回呼函數，用於接收MQTT模組的事件資訊。
customize_info	使用者自訂的上報資訊，以英文逗號為分隔字元的kv字串，如使用者的廠商資訊，模組資訊自訂字串為`"pid=123456,mid=abcd";`。

說明

pInitParams結構體的成員配置為0或NULL時將使用內部預設參數。

傳回值說明
值
說明
NULL
失敗
非NULL
MQTT控制代碼

IOT_MQTT_Destroy

介面原型
```
int IOT_MQTT_Destroy(void **phandle);
```
介面說明
銷毀指定MQTT串連並釋放資源。
參數說明
參數
資料類型
方向
說明
phandle
void **
輸入
MQTT控制代碼，可為NULL。
傳回值說明
值
說明
0
成功
< 0
失敗

IOT_MQTT_Yield

介面原型

int IOT_MQTT_Yield(void *handle, int timeout_ms);

介面說明
用於接收網路報文並將訊息分發到使用者的回呼函數中。
參數說明
參數
資料類型
方向
說明
handle
void *
輸入
MQTT控制代碼，可為NULL。
timeout_ms
int
輸入
嘗試接收報文的逾時時間。
傳回值說明
值
說明
0
成功

IOT_MQTT_CheckStateNormal

介面原型

int IOT_MQTT_CheckStateNormal(void *handle);

介面說明
擷取當前MQTT串連狀態。
參數說明
參數
資料類型
方向
說明
handle
void *
輸入
MQTT控制代碼，可為NULL。
傳回值說明
值
說明
0
未串連
1
已串連

IOT_MQTT_Subscribe

介面原型

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);

介面說明
向雲端訂閱指定的MQTT Topic。

參數說明

參數	資料類型	方向	說明
handle	void *	輸入	MQTT控制代碼，可為NULL。
topic_filter	const char *	輸入	需要訂閱的Topic。
qos	iotx_mqtt_qos_t	輸入	採用的QoS策略。
topic_handle_func	iotx_mqtt_event_handle_func_fpt	輸入	用於接收MQTT訊息的回呼函數。
pcontext	void *	輸入	使用者Context，會通過回呼函數返回。

傳回值說明
值
說明
0
成功
< 0
失敗

IOT_MQTT_Subscribe_Sync

介面原型

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);

介面說明
向雲端訂閱指定的MQTT Topic，該介面為同步介面。

參數說明

參數	資料類型	方向	說明
handle	void *	輸入	MQTT控制代碼，可為NULL。
topic_filter	const char *	輸入	需要訂閱的Topic。
qos	iotx_mqtt_qos_t	輸入	採用的QoS策略。
topic_handle_func	iotx_mqtt_event_handle_func_fpt	輸入	用於接收MQTT訊息的回呼函數。
pcontext	void *	輸入	使用者Context，會通過回呼函數返回。
timeout_ms	int	輸入	該同步介面的逾時時間。

傳回值說明
值
說明
0
成功
< 0
失敗

IOT_MQTT_Unsubscribe

介面原型

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

介面說明
向雲端取消訂閱指定的Topic。
參數說明
參數
資料類型
方向
說明
handle
void *
輸入
MQTT控制代碼，可為NULL。
topic_filter
const char *
輸入
需要取消訂閱的Topic。
傳回值說明
值
說明
0
成功
< 0
失敗

IOT_MQTT_Publish

介面原型

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

介面說明
向指定的Topic推送訊息。

參數說明

參數	資料類型	方向	說明
handle	void *	輸入	MQTT控制代碼，可為NULL。
topic_name	const char *	輸入	接收此推送訊息的目標Topic。
topic_msg	iotx_mqtt_topic_info_pt	輸入	需要推送的訊息。

傳回值說明
值
說明
> 0
成功（訊息是QoS1時，傳回值為上報報文的MQTT訊息ID，對應協議裡的messageId）
0
成功（訊息是QoS0時）
< 0
失敗

IOT_MQTT_Publish_Simple

介面原型

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

介面說明
向指定的Topic推送訊息。
說明
- IOT_MQTT_Publish：普通訊息發送。
- IOT_MQTT_Publish_Simple：帶更多配置選項的訊息發送。
的普通訊息發送，該介面可以帶更多配置選項發送訊息。

參數說明

參數	資料類型	方向	說明
handle	void *	輸入	MQTT控制代碼，可為NULL。
topic_name	const char *	輸入	接收此推送訊息的目標Topic。
qos	int	輸入	採用的QoS策略。
data	void *	輸入	需要發送的資料。
len	int	輸入	資料長度。

傳回值說明
值
說明
> 0
成功（訊息是QoS1時，傳回值為上報報文的MQTT訊息ID，對應協議裡的messageId）
0
成功（訊息是QoS0時）
< 0
失敗

值	說明
> 0	成功（訊息是QoS1時，傳回值為上報報文的MQTT訊息ID，對應協議裡的`messageId`）
0	成功（訊息是QoS0時）
< 0	失敗

值	說明
NULL	失敗
非NULL	MQTT控制代碼

值	說明
0	未串連
1	已串連