MQTT-C: Platform abstraction layer

MQTT-C

Functions
Platform abstraction layer

Documentation of the types and calls required to port MQTT-C to a new platform. More...

## Functions
ssize_t | mqtt_pal_sendall (mqtt_pal_socket_handle fd, const void *buf, size_t len, int flags)
| Sends all the bytes in a buffer. More...
ssize_t | mqtt_pal_recvall (mqtt_pal_socket_handle fd, void *buf, size_t bufsz, int flags)
| Non-blocking receive all the byte available. More...

## Detailed Description

Documentation of the types and calls required to port MQTT-C to a new platform.

mqtt_pal.h is the only header file included in mqtt.c. Therefore, to port MQTT-C to a new platform the following types, functions, constants, and macros must be defined in mqtt_pal.h:

- Types:
  - `size_t`, `ssize_t`
  - `uint8_t`, `uint16_t`, `uint32_t`
  - `va_list`
  - `mqtt_pal_time_t` : return type of `MQTT_PAL_TIME()`
  - `mqtt_pal_mutex_t` : type of the argument that is passed to `MQTT_PAL_MUTEX_LOCK` and `MQTT_PAL_MUTEX_RELEASE`
- Functions:
  - `memcpy`, `strlen`
  - `va_start`, `va_arg`, `va_end`
- Constants:
  - `INT_MIN`

Additionally, three macro's are required:

- `MQTT_PAL_HTONS(s)` : host-to-network endian conversion for uint16_t.
- `MQTT_PAL_NTOHS(s)` : network-to-host endian conversion for uint16_t.
- `MQTT_PAL_TIME()` : returns [type: `mqtt_pal_time_t`] current time in seconds.
- `MQTT_PAL_MUTEX_LOCK(mtx_pointer)` : macro that locks the mutex pointed to by `mtx_pointer`.
- `MQTT_PAL_MUTEX_RELEASE(mtx_pointer)` : macro that unlocks the mutex pointed to by `mtx_pointer`.

Lastly, mqtt_pal_sendall and mqtt_pal_recvall, must be implemented in mqtt_pal.c for sending and receiving data using the platforms socket calls.

## Function Documentation

## ◆ mqtt_pal_recvall()

ssize_t mqtt_pal_recvall | ( | mqtt_pal_socket_handle | fd,
|  | void * | buf,
|  | size_t | bufsz,
|  | int | flags
| ) |  |

Non-blocking receive all the byte available.

Parameters

  [in] | fd | The file-descriptor (or handle) of the socket.
  [in] | buf | A pointer to the receive buffer.
  [in] | bufsz | The max number of bytes that can be put into `buf`.
  [in] | flags | Flags which are passed to the underlying socket.

Returns
  The number of bytes received if successful, an MQTTErrors otherwise.

## ◆ mqtt_pal_sendall()

ssize_t mqtt_pal_sendall | ( | mqtt_pal_socket_handle | fd,
|  | const void * | buf,
|  | size_t | len,
|  | int | flags
| ) |  |

Sends all the bytes in a buffer.

Parameters

  [in] | fd | The file-descriptor (or handle) of the socket.
  [in] | buf | A pointer to the first byte in the buffer to send.
  [in] | len | The number of bytes to send (starting at `buf`).
  [in] | flags | Flags which are passed to the underlying socket.

Returns
  The number of bytes sent if successful, an MQTTErrors otherwise.