Implement HAL functions to connect to IoT Platform over MQTT - IoT Platform

This topic describes the hardware abstraction layer (HAL) functions that you must implement when you connect devices to IoT Platform over Message Queuing Telemetry Transport (MQTT).

HAL_SSL_Destroy

Prototype

int32_t HAL_SSL_Destroy(_IN_ uintptr_t handle);

Description
Destroys a Transport Layer Security (TLS) connection that is specified by the handle parameter.
Parameters
Parameter
Type
Category
Description
handle
uintptr_t
Input
The TLS connection handle.
Return value description
Value
Description
< 0
The operation failed.
= 0
The operation was successful.

HAL_SSL_Establish

Prototype

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

Description
Establishes a TLS connection based on the IP address, port number, and certificate of a specified TLS server and returns a connection handle.

Parameters

Parameter	Type	Category	Description
host	const char	Input	The IP address of the TLS server.
port	uint16_t	Input	The port number of the TLS server.
ca_crt	const char	Input	The pointer that links to an X.509 certificate encoded in Privacy-Enhanced Mail (PEM).
ca_crt_len	uint32_t	Input	The length of the certificate. Unit: bytes.

Return value description
Value
Description
NULL
The connection failed to be established.
!NULL
The connection was established. The returned TLS connection handle.

HAL_SSL_Read

Prototype

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

Description
Reads data from a specified TLS connection. The operation is synchronous. If the operation reads data of a length that is specified by the len parameter within a specified timeout period, the operation returns the data. Otherwise, the operation does not unblock a thread or return a value until the timeout period ends.

Parameters

Parameter	Type	Category	Description
handle	uintptr_t	Input	The TLS connection handle.
buf	char *	Output	The pointer that links to the buffer that receives data.
len	int	Input	The size of the buffer. Unit: bytes.
timeout_ms	int	Input	Timeout period

Return value description

Value	Description
-2	The system failed to establish the TLS connection.
-1	The TLS connection was closed by a remote device.
0	The request timed out and no data was read.
> 0	The request was successful and the number of characters that were read was returned.

HAL_SSL_Write

Prototype

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

Description
Writes data to a specified TLS connection. The operation is synchronous. If the operation writes data of a length that is specified by the len parameter within a specified timeout period, the operation returns the data. Otherwise, the operation does not unblock a thread or return a value until the timeout period ends.

Parameters

Parameter	Data types	Direction	Description
handle	uintptr_t	Input	The TLS connection handle.
buf	char *	Input	The pointer that links to the buffer from which you want to send data.
len	int	Input	The size of the buffer. Unit: bytes.
timeout_ms	int	Input	The timeout period.

Return value description

Value	Description
< 0	The system failed to establish the TLS connection.
0	The request timed out and no data was written.
> 0	The request was successful and the number of characters that were written was returned.

HAL_TCP_Destroy

Prototype

int32_t HAL_TCP_Destroy(_IN_ uintptr_t fd);

Description
Destroys a TCP connection that is specified by the fd parameter and releases the related resources.
Parameters
Parameter
Type
Category
Description
fd
uintptr_t
Input
The TCP connection handle.
Return value description
Value
Description
< 0
The operation failed.
= 0
The operation was successful.

HAL_TCP_Establish

Prototype

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

Description
Establishes a TCP connection based on the IP address and port number of a specified server and returns a connection handle.
Parameters
Parameter
Type
Category
Description
host
const char *
Input
The IP address of the TCP server.
port
uint16_t
Input
The port number of the TCP server.
Return value description
Value
Description
(uint_ptr)(-1)
The system failed to establish the TCP connection.
Other values including 0
The TCP connection was established and a connection handle was returned.

HAL_TCP_Read

Prototype

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

Description
Reads data from a specified TCP connection. The operation is synchronous. If the operation reads data of a length that is specified by the len parameter within a specified timeout period, the operation returns the data. Otherwise, the operation does not unblock a thread or return a value until the timeout period ends.

Parameters

Parameter	Type	Category	Description
fd	uintptr_t	Input	The TCP connection handle.
buf	char *	Output	The pointer that links to the buffer that receives data.
len	int	Input	The size of the buffer. Unit: bytes.
timeout_ms	int	Input	The timeout period.

Return value description

Value	Description
-2	The system failed to establish the TCP connection.
-1	The TCP connection was closed by a remote device.
0	The request timed out and no data was read.
> 0	The request was successful and the number of characters that were read was returned.

HAL_TCP_Write

Prototype

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

Description
Writes data to a specified TCP connection. The operation is synchronous. If the operation writes data of a length that is specified by the len parameter within a specified timeout period, the operation returns the data. Otherwise, the operation does not unblock a thread or return a value until the timeout period ends.

Parameters

Parameter	Type	Category	Description
fd	uintptr_t	Input	The TCP connection handle.
buf	char *	Input	The pointer that links to the buffer from which you want to send data.
len	int	Input	The size of the buffer. Unit: bytes.
timeout_ms	int	Input	The timeout period.

Return value description

Value	Description
< 0	The system failed to establish the TCP connection.
0	The request timed out and no data was written.
> 0	The request was successful and the number of characters that were written was returned.

Value	Description
< 0	The operation failed.
= 0	The operation was successful.

Value	Description
NULL	The connection failed to be established.
!NULL	The connection was established. The returned TLS connection handle.

Value	Description
(uint_ptr)(-1)	The system failed to establish the TCP connection.
Other values including 0	The TCP connection was established and a connection handle was returned.