MQTT連雲HAL介面說明-物聯網平台-阿里雲

本文介紹MQTT連雲相關的HAL介面。

HAL_SSL_Destroy

介面原型

int32_t HAL_SSL_Destroy(_IN_ uintptr_t handle);

介面說明
銷毀由參數handle指定的TLS串連。
參數說明
參數
資料類型
方向
說明
handle
uintptr_t
輸入
TLS串連控制代碼
傳回值說明
值
說明
< 0
操作失敗
= 0
操作成功

HAL_SSL_Establish

介面原型

uintptr_t HAL_SSL_Establish(
            _IN_ const char *host,
            _IN_ uint16_t port,
            _IN_ const char *ca_crt,
            _IN_ uint32_t ca_crt_len);

介面說明
根據指定的伺服器網路地址、伺服器連接埠號碼和認證檔案建立TLS串連，返回對應的串連控制代碼。

參數說明

參數	資料類型	方向	說明
host	const char	輸入	指定的TLS伺服器網路地址
port	uint16_t	輸入	指定的TLS伺服器連接埠
ca_crt	const char	輸入	指向PEM編碼的X.509認證的指標
ca_crt_len	uint32_t	輸入	認證位元組長度

傳回值說明
值
說明
NULL
建立失敗
!NULL
建立成功，返回TLS串連控制代碼

HAL_SSL_Read

介面原型

int32_t HAL_SSL_Read(_IN_ uintptr_t handle, _OU_ char *buf, _OU_ int len, _IN_ int timeout_ms);int32_t HAL_SSL_Destroy(_IN_ uintptr_t handle);

介面說明
從指定的TLS串連中讀取資料，此介面為同步介面，如果在逾時時間內讀取到參數len指定長度的資料則立即返回，否則在逾時時間到時才解除阻塞返回。

參數說明

參數	資料類型	方向	說明
handle	uintptr_t	輸入	TLS串連控制代碼
buf	char *	輸出	指向資料接收緩衝區的指標
len	int	輸入	資料接收緩衝區的位元組大小
timeout_ms	int	輸入	逾時時間

傳回值說明
值
說明
-2
TLS串連發生錯誤。
-1
TLS串連被遠程裝置關閉。
0
TLS讀逾時, 且沒有接收到任何資料。
> 0
TLS讀取到的位元組數，TLS讀取成功。

HAL_SSL_Write

介面原型

int32_t HAL_SSL_Write(_IN_ uintptr_t handle, _IN_ const char *buf, _IN_ int len, _IN_ int timeout_ms);

介面說明
向指定的TLS串連中寫入資料，此介面為同步介面，如果在逾時時間內寫入了參數len指定長度的資料則立即返回，否則在逾時時間到時才解除阻塞返回。

參數說明

參數	資料類型	方向	說明
handle	uintptr_t	輸入	TLS串連控制代碼
buf	char *	輸入	指向資料發送緩衝區的指標
len	int	輸入	資料發送緩衝區的位元組大小
timeout_ms	int	輸入	逾時時間

傳回值說明
值
說明
< 0
TLS串連發生錯誤。
0
TLS寫逾時，且沒有寫入任何資料。
> 0
TLS寫入的位元組數，TLS寫入成功。

HAL_TCP_Destroy

介面原型

int32_t HAL_TCP_Destroy(_IN_ uintptr_t fd);

介面說明
銷毀由參數fd指定的TCP串連，釋放資源。
參數說明
參數
資料類型
方向
說明
fd
uintptr_t
輸入
TCP串連控制代碼
傳回值說明
值
說明
< 0
操作失敗
= 0
操作成功

HAL_TCP_Establish

介面原型

uintptr_t HAL_TCP_Establish(_IN_ const char *host, _IN_  uint16_t port);

介面說明
根據指定的伺服器網路地址和連接埠號碼建立TCP串連，並返回對應串連控制代碼。
參數說明
參數
資料類型
方向
說明
host
const char *
輸入
指定TCP伺服器的網路地址
port
uint16_t
輸入
指定TCP伺服器的連接埠號碼
傳回值說明
值
說明
(uint_ptr)(-1)
TCP串連建立失敗。
其它值（包括0）
TCP串連建立成功，返回對應的串連控制代碼。

HAL_TCP_Read

介面原型

int32_t HAL_TCP_Read(_IN_ uintptr_t fd, _OU_ char *buf, _IN_ uint32_t len, _IN_ uint32_t timeout_ms);

介面說明
從指定的TCP串連中讀取資料，此介面為同步介面，如果在逾時時間內讀取到參數len指定長度的資料則立即返回，否則在逾時時間到時才解除阻塞返回。

參數說明

參數	資料類型	方向	說明
fd	uintptr_t	輸入	TCP串連控制代碼
buf	char *	輸出	指向資料接收緩衝區的指標
len	int	輸入	資料接收緩衝區的位元組大小
timeout_ms	int	輸入	逾時時間

傳回值說明
值
說明
-2
TCP串連發生錯誤。
-1
TCP串連被遠程裝置關閉。
0
TCP讀逾時，且沒有接收到任何資料。
> 0
TCP讀取成功，返回讀取到的位元組數。

HAL_TCP_Write

介面原型

int32_t HAL_TCP_Write(_IN_ uintptr_t fd, _IN_ const char *buf, _IN_ uint32_t len, _IN_ uint32_t timeout_ms);int32_t HAL_TCP_Read(_IN_ uintptr_t fd, _OU_ char *buf, _IN_ uint32_t len, _IN_ uint32_t timeout_ms);

介面說明
從指定的TCP串連中寫入資料，此介面為同步介面，如果在逾時時間內寫入了參數len指定長度的資料則立即返回，否則在逾時時間到時才解除阻塞返回。

參數說明

參數	資料類型	方向	說明
fd	uintptr_t	輸入	TCP串連控制代碼
buf	char *	輸入	指向資料發送緩衝區的指標
len	int	輸入	資料發送緩衝區的位元組大小
timeout_ms	int	輸入	逾時時間

傳回值說明
值
說明
< 0
TCP串連發生錯誤。
0
TCP寫逾時，且沒有寫入任何資料。
> 0
TCP入成功，返回TCP寫入的位元組數。

值	說明
NULL	建立失敗
!NULL	建立成功，返回TLS串連控制代碼

值	說明
-2	TLS串連發生錯誤。
-1	TLS串連被遠程裝置關閉。
0	TLS讀逾時, 且沒有接收到任何資料。
> 0	TLS讀取到的位元組數，TLS讀取成功。

值	說明
< 0	TLS串連發生錯誤。
0	TLS寫逾時，且沒有寫入任何資料。
> 0	TLS寫入的位元組數，TLS寫入成功。

值	說明
(uint_ptr)(-1)	TCP串連建立失敗。
其它值（包括0）	TCP串連建立成功，返回對應的串連控制代碼。

值	說明
-2	TCP串連發生錯誤。
-1	TCP串連被遠程裝置關閉。
0	TCP讀逾時，且沒有接收到任何資料。
> 0	TCP讀取成功，返回讀取到的位元組數。

值	說明
< 0	TCP串連發生錯誤。
0	TCP寫逾時，且沒有寫入任何資料。
> 0	TCP入成功，返回TCP寫入的位元組數。

值	說明
< 0	操作失敗
= 0	操作成功

值	說明
< 0	操作失敗
= 0	操作成功