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.
#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.
#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.

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.
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.
ssize_t	mqtt_pack_publish_request (uint8_t *buf, size_t bufsz, const char *topic_name, uint16_t packet_id, const void *application_message, size_t application_message_size, uint8_t publish_flags)
	Serialize a PUBLISH request and put it in buf.
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.
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.
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.
ssize_t	mqtt_pack_ping_request (uint8_t *buf, size_t bufsz)
	Serialize a PINGREQ and put it into buf.
ssize_t	mqtt_pack_disconnect (uint8_t *buf, size_t bufsz)
	Serialize a DISCONNECT and put it into buf.

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

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 can be NULL or an empty string for Anonymous clients.
[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,
		const 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.