MQTT-C: Control Packet Serialization

MQTT-C

Macros | Enumerations | Functions
Control Packet Serialization

Developer documentation of the functions and datastructures used for serializing MQTT control packets. More...

## Macros
#define | MQTT_PROTOCOL_LEVEL 0x04
| The protocol identifier for MQTT v3.1.1. More...
#define | MQTT_SUBSCRIBE_REQUEST_MAX_NUM_TOPICS 8
| The maximum number topics that can be subscribed to in a single call to mqtt_pack_subscribe_request. More...
#define | MQTT_UNSUBSCRIBE_REQUEST_MAX_NUM_TOPICS 8
| The maximum number topics that can be subscribed to in a single call to mqtt_pack_unsubscribe_request. More...

## Enumerations
enum | MQTTConnectFlags { MQTT_CONNECT_RESERVED = 1u, MQTT_CONNECT_CLEAN_SESSION = 2u, MQTT_CONNECT_WILL_FLAG = 4u, MQTT_CONNECT_WILL_QOS_0 = (0u & 0x03) << 3, MQTT_CONNECT_WILL_QOS_1 = (1u & 0x03) << 3, MQTT_CONNECT_WILL_QOS_2 = (2u & 0x03) << 3, MQTT_CONNECT_WILL_RETAIN = 32u, MQTT_CONNECT_PASSWORD = 64u, MQTT_CONNECT_USER_NAME = 128u }
| An enumeration of CONNECT packet flags. More...
enum | MQTTPublishFlags { MQTT_PUBLISH_DUP = 8u, MQTT_PUBLISH_QOS_0 = ((0u << 1) & 0x06), MQTT_PUBLISH_QOS_1 = ((1u << 1) & 0x06), MQTT_PUBLISH_QOS_2 = ((2u << 1) & 0x06), MQTT_PUBLISH_QOS_MASK = ((3u << 1) & 0x06), MQTT_PUBLISH_RETAIN = 0x01 }
| An enumeration of the PUBLISH flags. More...

## Functions
ssize_t | mqtt_pack_fixed_header (uint8_t *buf, size_t bufsz, const struct mqtt_fixed_header *fixed_header)
| Serialize an mqtt_fixed_header and write it to `buf`. More...
ssize_t | mqtt_pack_connection_request (uint8_t *buf, size_t bufsz, const char *client_id, const char *will_topic, const void *will_message, size_t will_message_size, const char *user_name, const char *password, uint8_t connect_flags, uint16_t keep_alive)
| Serialize a connection request into a buffer. More...
ssize_t | mqtt_pack_publish_request (uint8_t *buf, size_t bufsz, const char *topic_name, uint16_t packet_id, void *application_message, size_t application_message_size, uint8_t publish_flags)
| Serialize a PUBLISH request and put it in `buf`. More...
ssize_t | mqtt_pack_pubxxx_request (uint8_t *buf, size_t bufsz, enum MQTTControlPacketType control_type, uint16_t packet_id)
| Serialize a PUBACK, PUBREC, PUBREL, or PUBCOMP packet and put it in `buf`. More...
ssize_t | mqtt_pack_subscribe_request (uint8_t *buf, size_t bufsz, unsigned int packet_id,...)
| Serialize a SUBSCRIBE packet and put it in `buf`. More...
ssize_t | mqtt_pack_unsubscribe_request (uint8_t *buf, size_t bufsz, unsigned int packet_id,...)
| Serialize a UNSUBSCRIBE packet and put it in `buf`. More...
ssize_t | mqtt_pack_ping_request (uint8_t *buf, size_t bufsz)
| Serialize a PINGREQ and put it into `buf`. More...
ssize_t | mqtt_pack_disconnect (uint8_t *buf, size_t bufsz)
| Serialize a DISCONNECT and put it into `buf`. More...

## Detailed Description

Developer documentation of the functions and datastructures used for serializing MQTT control packets.

## Macro Definition Documentation

## ◆ MQTT_PROTOCOL_LEVEL

#define MQTT_PROTOCOL_LEVEL 0x04

The protocol identifier for MQTT v3.1.1.

See also
  MQTT v3.1.1: CONNECT Variable Header.

## ◆ MQTT_SUBSCRIBE_REQUEST_MAX_NUM_TOPICS

#define MQTT_SUBSCRIBE_REQUEST_MAX_NUM_TOPICS 8

The maximum number topics that can be subscribed to in a single call to mqtt_pack_subscribe_request.

See also
  mqtt_pack_subscribe_request

## ◆ MQTT_UNSUBSCRIBE_REQUEST_MAX_NUM_TOPICS

#define MQTT_UNSUBSCRIBE_REQUEST_MAX_NUM_TOPICS 8

The maximum number topics that can be subscribed to in a single call to mqtt_pack_unsubscribe_request.

See also
  mqtt_pack_unsubscribe_request

## Enumeration Type Documentation

## ◆ MQTTConnectFlags

enum MQTTConnectFlags

An enumeration of CONNECT packet flags.

See also
  MQTT v3.1.1: CONNECT Variable Header.

## ◆ MQTTPublishFlags

enum MQTTPublishFlags

An enumeration of the PUBLISH flags.

See also
  MQTT v3.1.1: PUBLISH - Publish Message.

## Function Documentation

## ◆ mqtt_pack_connection_request()

ssize_t mqtt_pack_connection_request | ( | uint8_t * | buf,
|  | size_t | bufsz,
|  | const char * | client_id,
|  | const char * | will_topic,
|  | const void * | will_message,
|  | size_t | will_message_size,
|  | const char * | user_name,
|  | const char * | password,
|  | uint8_t | connect_flags,
|  | uint16_t | keep_alive
| ) |  |

Serialize a connection request into a buffer.

Parameters

  [out] | buf | the buffer to pack the connection request packet into.
  [in] | bufsz | the number of bytes left in `buf`.
  [in] | client_id | the ID that identifies the local client. `client_id` is a required parameter.
  [in] | will_topic | the topic under which the local client's will message will be published. Set to `NULL` for no will message. If `will_topic` is not `NULL` a `will_message` must also be provided.
  [in] | will_message | the will message to be published upon a unsuccessful disconnection of the local client. Set to `NULL` if `will_topic` is `NULL`. `will_message` must not be `NULL` if `will_topic` is not `NULL`.
  [in] | will_message_size | The size of `will_message` in bytes.
  [in] | user_name | the username to be used to connect to the broker with. Set to `NULL` if no username is required.
  [in] | password | the password to be used to connect to the broker with. Set to `NULL` if no password is required.
  [in] | connect_flags | additional MQTTConnectFlags to be set. The only flags that need to be set manually are `MQTT_CONNECT_CLEAN_SESSION`, `MQTT_CONNECT_WILL_QOS_X` (for `X` ∈ {0, 1, 2}), and `MQTT_CONNECT_WILL_RETAIN`. Set to 0 if no additional flags are required.
  [in] | keep_alive | the keep alive time in seconds. It is the responsibility of the clinet to ensure packets are sent to the server {at least} this frequently.

Note
  If there is a `will_topic` and no additional `connect_flags` are given, then by default `will_message` will be published at QoS level 0.

See also
  MQTT v3.1.1: CONNECT - Client Requests a Connection to a Server.

Returns
  The number of bytes put into `buf`, 0 if `buf` is too small to fit the CONNECT packet, a negative value if there was a protocol violation.

## ◆ mqtt_pack_disconnect()

ssize_t mqtt_pack_disconnect | ( | uint8_t * | buf,
|  | size_t | bufsz
| ) |  |

Serialize a DISCONNECT and put it into `buf`.

Parameters

  [out] | buf | the buffer to put the DISCONNECT packet in.
  [in] | bufsz | the maximum number of bytes that can be put into `buf`.

See also
  MQTT v3.1.1: DISCONNECT - Disconnect Notification.

Returns
  The number of bytes put into `buf`, 0 if `buf` is too small to fit the DISCONNECT packet, a negative value if there was a protocol violation.

## ◆ mqtt_pack_fixed_header()

ssize_t mqtt_pack_fixed_header | ( | uint8_t * | buf,
|  | size_t | bufsz,
|  | const struct mqtt_fixed_header * | fixed_header
| ) |  |

Serialize an mqtt_fixed_header and write it to `buf`.

Note
  This function performs complete error checking and a positive return value guarantees the entire packet will fit into the given buffer.

Parameters

  [out] | buf | the buffer to write to.
  [in] | bufsz | the maximum number of bytes that can be put in to `buf`.
  [in] | fixed_header | the fixed header that will be serialized.

Returns
  The number of bytes written to `buf`, or 0 if `buf` is too small, or a negative value if there was a protocol violation.

## ◆ mqtt_pack_ping_request()

ssize_t mqtt_pack_ping_request | ( | uint8_t * | buf,
|  | size_t | bufsz
| ) |  |

Serialize a PINGREQ and put it into `buf`.

Parameters

  [out] | buf | the buffer to put the PINGREQ packet in.
  [in] | bufsz | the maximum number of bytes that can be put into `buf`.

See also
  MQTT v3.1.1: PINGREQ - Ping Request.

Returns
  The number of bytes put into `buf`, 0 if `buf` is too small to fit the PINGREQ packet, a negative value if there was a protocol violation.

## ◆ mqtt_pack_publish_request()

ssize_t mqtt_pack_publish_request | ( | uint8_t * | buf,
|  | size_t | bufsz,
|  | const char * | topic_name,
|  | uint16_t | packet_id,
|  | void * | application_message,
|  | size_t | application_message_size,
|  | uint8_t | publish_flags
| ) |  |

Serialize a PUBLISH request and put it in `buf`.

Parameters

  [out] | buf | the buffer to put the PUBLISH packet in.
  [in] | bufsz | the maximum number of bytes that can be put into `buf`.
  [in] | topic_name | the topic to publish `application_message` under.
  [in] | packet_id | this packets packet ID.
  [in] | application_message | the application message to be published.
  [in] | application_message_size | the size of `application_message` in bytes.
  [in] | publish_flags | The flags to publish `application_message` with. These include the `MQTT_PUBLISH_DUP` flag, `MQTT_PUBLISH_QOS_X` (`X` ∈ {0, 1, 2}), and `MQTT_PUBLISH_RETAIN` flag.

Note
  The default QoS is level 0.

See also
  MQTT v3.1.1: PUBLISH - Publish Message.

Returns
  The number of bytes put into `buf`, 0 if `buf` is too small to fit the PUBLISH packet, a negative value if there was a protocol violation.

## ◆ mqtt_pack_pubxxx_request()

ssize_t mqtt_pack_pubxxx_request | ( | uint8_t * | buf,
|  | size_t | bufsz,
|  | enum MQTTControlPacketType | control_type,
|  | uint16_t | packet_id
| ) |  |

Serialize a PUBACK, PUBREC, PUBREL, or PUBCOMP packet and put it in `buf`.

Parameters

  [out] | buf | the buffer to put the PUBXXX packet in.
  [in] | bufsz | the maximum number of bytes that can be put into `buf`.
  [in] | control_type | the type of packet. Must be one of: `MQTT_CONTROL_PUBACK`, `MQTT_CONTROL_PUBREC`, `MQTT_CONTROL_PUBREL`, or `MQTT_CONTROL_PUBCOMP`.
  [in] | packet_id | the packet ID of the packet being acknowledged.

See also
  MQTT v3.1.1: PUBACK - Publish Acknowledgement.
  MQTT v3.1.1: PUBREC - Publish Received.
  MQTT v3.1.1: PUBREL - Publish Released.
  MQTT v3.1.1: PUBCOMP - Publish Complete.

Returns
  The number of bytes put into `buf`, 0 if `buf` is too small to fit the PUBXXX packet, a negative value if there was a protocol violation.

## ◆ mqtt_pack_subscribe_request()

ssize_t mqtt_pack_subscribe_request | ( | uint8_t * | buf,
|  | size_t | bufsz,
|  | unsigned int | packet_id,
|  |  | ...
| ) |  |

Serialize a SUBSCRIBE packet and put it in `buf`.

Parameters

  [out] | buf | the buffer to put the SUBSCRIBE packet in.
  [in] | bufsz | the maximum number of bytes that can be put into `buf`.
  [in] | packet_id | the packet ID to be used.
  [in] | ... | `NULL` terminated list of (`{const` char *topic_name}, `{int` max_qos_level}) pairs.

Note
  The variadic arguments, ``..., must be followed by a `NULL`. For example:
  ssize_t n = mqtt_pack_subscribe_request(buf, bufsz, 1234, "topic_1", 0, "topic_2", 2, NULL);

See also
  MQTT v3.1.1: SUBSCRIBE - Subscribe to Topics.

Returns
  The number of bytes put into `buf`, 0 if `buf` is too small to fit the SUBSCRIBE packet, a negative value if there was a protocol violation.

## ◆ mqtt_pack_unsubscribe_request()

ssize_t mqtt_pack_unsubscribe_request | ( | uint8_t * | buf,
|  | size_t | bufsz,
|  | unsigned int | packet_id,
|  |  | ...
| ) |  |

Serialize a UNSUBSCRIBE packet and put it in `buf`.

Parameters

  [out] | buf | the buffer to put the UNSUBSCRIBE packet in.
  [in] | bufsz | the maximum number of bytes that can be put into `buf`.
  [in] | packet_id | the packet ID to be used.
  [in] | ... | `NULL` terminated list of `{const` char *topic_name}'s to unsubscribe from.

Note
  The variadic arguments, ``..., must be followed by a `NULL`. For example:
  ssize_t n = mqtt_pack_unsubscribe_request(buf, bufsz, 4321, "topic_1", "topic_2", NULL);

See also
  MQTT v3.1.1: UNSUBSCRIBE - Unsubscribe from Topics.

Returns
  The number of bytes put into `buf`, 0 if `buf` is too small to fit the UNSUBSCRIBE packet, a negative value if there was a protocol violation.