MQTT-C: Utilities

MQTT-C

Data Structures | Macros | Enumerations | Functions
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.