Utilities

Developer documentation for the utilities used to implement the MQTT-C client. More...

Data Structures
struct	mqtt_queued_message
	A message in a mqtt_message_queue. More...
struct	mqtt_message_queue
	A message queue. More...
struct	mqtt_client
	An MQTT client. More...

Macros
#define	mqtt_mq_get(mq_ptr, index)   (((struct mqtt_queued_message*) ((mq_ptr)->mem_end)) - 1 - index)
	Returns the mqtt_queued_message at index. More...
#define	mqtt_mq_length(mq_ptr)   (((struct mqtt_queued_message*) ((mq_ptr)->mem_end)) - (mq_ptr)->queue_tail)
	Returns the number of messages in the message queue, mq_ptr.
#define	mqtt_mq_currsz(mq_ptr)   (mq_ptr->curr >= (uint8_t*) ((mq_ptr)->queue_tail - 1)) ? 0 : ((uint8_t*) ((mq_ptr)->queue_tail - 1)) - (mq_ptr)->curr
	Used internally to recalculate the curr_sz.

Enumerations
enum	MQTTQueuedMessageState { MQTT_QUEUED_UNSENT, MQTT_QUEUED_AWAITING_ACK, MQTT_QUEUED_COMPLETE }
	An enumeration of queued message states.

Functions
uint16_t	__mqtt_next_pid (struct mqtt_client *client)
	Generate a new next packet ID.Packet ID's are generated using a max-length LFSR. More...
ssize_t	__mqtt_send (struct mqtt_client *client)
	Handles egress client traffic. More...
ssize_t	__mqtt_recv (struct mqtt_client *client)
	Handles ingress client traffic. More...
ssize_t	__mqtt_puback (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==1. More...
ssize_t	__mqtt_pubrec (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==2. More...
ssize_t	__mqtt_pubrel (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREC packet. More...
ssize_t	__mqtt_pubcomp (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREL packet. More...
void	mqtt_mq_init (struct mqtt_message_queue *mq, void *buf, size_t bufsz)
	Initialize a message queue. More...
void	mqtt_mq_clean (struct mqtt_message_queue *mq)
	Clear as many messages from the front of the queue as possible. More...
struct mqtt_queued_message *	mqtt_mq_register (struct mqtt_message_queue *mq, size_t nbytes)
	Register a message that was just added to the buffer. More...
struct mqtt_queued_message *	mqtt_mq_find (struct mqtt_message_queue *mq, enum MQTTControlPacketType control_type, uint16_t *packet_id)
	Find a message in the message queue. More...

Detailed Description

Developer documentation for the utilities used to implement the MQTT-C client.

Note

To deserialize a packet from a buffer use mqtt_unpack_response (it's the only function you need).

Macro Definition Documentation

mqtt_mq_get

#define mqtt_mq_get	(		mq_ptr,
			index
	)		(((struct mqtt_queued_message*) ((mq_ptr)->mem_end)) - 1 - index)

Returns the mqtt_queued_message at index.

Parameters

mq_ptr	A pointer to the message queue.
index	The index of the message.

Returns

The mqtt_queued_message at index.

Function Documentation

__mqtt_next_pid()

uint16_t __mqtt_next_pid

(

struct mqtt_client *

client

)

Generate a new next packet ID.Packet ID's are generated using a max-length LFSR.

Parameters

client

The MQTT client.

Returns

The new packet ID that should be used.

__mqtt_puback()

ssize_t __mqtt_puback	(	struct mqtt_client *	client,
		uint16_t	packet_id
	)

Acknowledge an ingree publish with QOS==1.

Parameters

[in,out]	client	The MQTT client.
[in]	packet_id	The packet ID of the ingress publish being acknowledged.

Returns

MQTT_OK upon success, an MQTTErrors otherwise.

__mqtt_pubcomp()

ssize_t __mqtt_pubcomp	(	struct mqtt_client *	client,
		uint16_t	packet_id
	)

Acknowledge an ingree PUBREL packet.

Parameters

[in,out]	client	The MQTT client.
[in]	packet_id	The packet ID of the ingress PUBREL being acknowledged.

Returns

MQTT_OK upon success, an MQTTErrors otherwise.

__mqtt_pubrec()

ssize_t __mqtt_pubrec	(	struct mqtt_client *	client,
		uint16_t	packet_id
	)

Acknowledge an ingree publish with QOS==2.

Parameters

[in,out]	client	The MQTT client.
[in]	packet_id	The packet ID of the ingress publish being acknowledged.

Returns

MQTT_OK upon success, an MQTTErrors otherwise.

__mqtt_pubrel()

ssize_t __mqtt_pubrel	(	struct mqtt_client *	client,
		uint16_t	packet_id
	)

Acknowledge an ingree PUBREC packet.

Parameters

[in,out]	client	The MQTT client.
[in]	packet_id	The packet ID of the ingress PUBREC being acknowledged.

Returns

MQTT_OK upon success, an MQTTErrors otherwise.

__mqtt_recv()

ssize_t __mqtt_recv

(

struct mqtt_client *

client

)

Handles ingress client traffic.

Parameters

client

The MQTT client.

Returns

MQTT_OK upon success, an MQTTErrors otherwise.

__mqtt_send()

ssize_t __mqtt_send

(

struct mqtt_client *

client

)

Handles egress client traffic.

Parameters

client

The MQTT client.

Returns

MQTT_OK upon success, an MQTTErrors otherwise.

mqtt_mq_clean()

void mqtt_mq_clean ( struct mqtt_message_queue *  mq )

related

Clear as many messages from the front of the queue as possible.

Note

Calls to this function are the only way to remove messages from the queue.

Parameters

mq	The message queue.

mqtt_mq_find()

struct mqtt_queued_message * mqtt_mq_find ( struct mqtt_message_queue *  mq, enum MQTTControlPacketType  control_type, uint16_t *  packet_id  )

related

Find a message in the message queue.

Parameters

	mq	The message queue.
[in]	control_type	The control type of the message you want to find.
[in]	packet_id	The packet ID of the message you want to find. Set to NULL if you don't want to specify a packet ID.

Returns

The found message. NULL if the message was not found.

mqtt_mq_init()

void mqtt_mq_init ( struct mqtt_message_queue *  mq, void *  buf, size_t  bufsz  )

related

Initialize a message queue.

Parameters

[out]	mq	The message queue to initialize.
[in]	buf	The buffer for this message queue.
[in]	bufsz	The number of bytes in the buffer.

mqtt_mq_register()

struct mqtt_queued_message * mqtt_mq_register ( struct mqtt_message_queue *  mq, size_t  nbytes  )

related

Register a message that was just added to the buffer.

Note

This function should be called immediately following a call to a packer function that returned a positive value. The positive value (number of bytes packed) should be passed to this function.

Parameters

	mq	The message queue.
[in]	nbytes	The number of bytes that were just packed.

Note

This function will step mqtt_message_queue::curr and update mqtt_message_queue::curr_sz.

Returns

The newly added struct mqtt_queued_message.