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.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MQTT_PROTOCOL_LEVEL

◆ MQTT_SUBSCRIBE_REQUEST_MAX_NUM_TOPICS

◆ MQTT_UNSUBSCRIBE_REQUEST_MAX_NUM_TOPICS

Enumeration Type Documentation

◆ MQTTConnectFlags

◆ MQTTPublishFlags

Function Documentation

◆ mqtt_pack_connection_request()

◆ mqtt_pack_disconnect()

◆ mqtt_pack_fixed_header()

◆ mqtt_pack_ping_request()

◆ mqtt_pack_publish_request()

◆ mqtt_pack_pubxxx_request()

◆ mqtt_pack_subscribe_request()

◆ mqtt_pack_unsubscribe_request()