Utilities

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

Collaboration diagram for Utilities:

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)
	Returns the mqtt_queued_message at index.
#define	mqtt_mq_length(mq_ptr)
	Returns the number of messages in the message queue, mq_ptr.
#define	mqtt_mq_currsz(mq_ptr)
	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.
ssize_t	__mqtt_send (struct mqtt_client *client)
	Handles egress client traffic.
ssize_t	__mqtt_recv (struct mqtt_client *client)
	Handles ingress client traffic.
ssize_t	__mqtt_puback (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==1.
ssize_t	__mqtt_pubrec (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree publish with QOS==2.
ssize_t	__mqtt_pubrel (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREC packet.
ssize_t	__mqtt_pubcomp (struct mqtt_client *client, uint16_t packet_id)
	Acknowledge an ingree PUBREL packet.
void	mqtt_mq_init (struct mqtt_message_queue *mq, void *buf, size_t bufsz)
	Initialize a message queue.
void	mqtt_mq_clean (struct mqtt_message_queue *mq)
	Clear as many messages from the front of the queue as possible.
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.
struct mqtt_queued_message *	mqtt_mq_find (const struct mqtt_message_queue *mq, enum MQTTControlPacketType control_type, const uint16_t *packet_id)
	Find a message in the message queue.

Detailed Description

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

Macro Definition Documentation

mqtt_mq_currsz

#define mqtt_mq_currsz

(

mq_ptr

)

Value:

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

mqtt_mq_get

#define mqtt_mq_get	(		mq_ptr,
			index )

Value:

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

mqtt_mq_length

#define mqtt_mq_length

(

mq_ptr

)

Value:

(((struct mqtt_queued_message*) ((mq_ptr)->mem_end)) - (mq_ptr)->queue_tail)

Returns the number of messages in the message queue, mq_ptr.

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 ( const struct mqtt_message_queue * mq, enum MQTTControlPacketType control_type, const 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.