MQTT-C: include/mqtt.h File Reference

MQTT-C

Data Structures | Macros | Enumerations | Functions
mqtt.h File Reference

Declares all the MQTT-C functions and datastructures. More...

`#include <mqtt_pal.h>`
Include dependency graph for mqtt.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | mqtt_fixed_header
| The fixed header of an MQTT control packet. More...
struct | mqtt_response_connack
| A connection response datastructure. More...
struct | mqtt_response_publish
| A publish packet received from the broker.A publish packet is received from the broker when a client publishes to a topic that the {local client} is subscribed to. More...
struct | mqtt_response_puback
| A publish acknowledgement for messages that were published with QoS level 1. More...
struct | mqtt_response_pubrec
| The response packet to a PUBLISH packet with QoS level 2. More...
struct | mqtt_response_pubrel
| The response to a PUBREC packet. More...
struct | mqtt_response_pubcomp
| The response to a PUBREL packet. More...
struct | mqtt_response_suback
| The response to a subscription request. More...
struct | mqtt_response_unsuback
| The brokers response to a UNSUBSCRIBE request. More...
struct | mqtt_response_pingresp
| The response to a ping request. More...
struct | mqtt_response
| A struct used to deserialize/interpret an incoming packet from the broker. More...
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_PROTOCOL_LEVEL 0x04
| The protocol identifier for MQTT v3.1.1. More...
#define | __ALL_MQTT_ERRORS(MQTT_ERROR)
| A macro used to declare the enum MQTTErrors and associated error messages (the members of the num) at the same time. More...
#define | GENERATE_ENUM(ENUM) ENUM,
| A macro used to generate the enum MQTTErrors from __ALL_MQTT_ERRORS. More...
#define | GENERATE_STRING(STRING) #STRING,
| A macro used to generate the error messages associated with MQTTErrors from __ALL_MQTT_ERRORS. More...
#define | __mqtt_packed_cstrlen(x) (2 + strlen(x))
| A macro to get the MQTT string length from a c-string.
#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...
#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 | MQTTControlPacketType { MQTT_CONTROL_CONNECT =1u, MQTT_CONTROL_CONNACK =2u, MQTT_CONTROL_PUBLISH =3u, MQTT_CONTROL_PUBACK =4u, MQTT_CONTROL_PUBREC =5u, MQTT_CONTROL_PUBREL =6u, MQTT_CONTROL_PUBCOMP =7u, MQTT_CONTROL_SUBSCRIBE =8u, MQTT_CONTROL_SUBACK =9u, MQTT_CONTROL_UNSUBSCRIBE =10u, MQTT_CONTROL_UNSUBACK =11u, MQTT_CONTROL_PINGREQ =12u, MQTT_CONTROL_PINGRESP =13u, MQTT_CONTROL_DISCONNECT =14u }
| An enumeration of the MQTT control packet types. More...
enum | MQTTErrors { MQTT_ERROR_UNKNOWN =INT_MIN, MQTT_ERROR_NULLPTR, MQTT_ERROR_CONTROL_FORBIDDEN_TYPE, MQTT_ERROR_CONTROL_INVALID_FLAGS, MQTT_ERROR_CONTROL_WRONG_TYPE, MQTT_ERROR_CONNECT_NULL_CLIENT_ID, MQTT_ERROR_CONNECT_NULL_WILL_MESSAGE, MQTT_ERROR_CONNECT_FORBIDDEN_WILL_QOS, MQTT_ERROR_CONNACK_FORBIDDEN_FLAGS, MQTT_ERROR_CONNACK_FORBIDDEN_CODE, MQTT_ERROR_PUBLISH_FORBIDDEN_QOS, MQTT_ERROR_SUBSCRIBE_TOO_MANY_TOPICS, MQTT_ERROR_MALFORMED_RESPONSE, MQTT_ERROR_UNSUBSCRIBE_TOO_MANY_TOPICS, MQTT_ERROR_RESPONSE_INVALID_CONTROL_TYPE, MQTT_ERROR_CONNECT_NOT_CALLED, MQTT_ERROR_SEND_BUFFER_IS_FULL, MQTT_ERROR_SOCKET_ERROR, MQTT_ERROR_MALFORMED_REQUEST, MQTT_ERROR_RECV_BUFFER_TOO_SMALL, MQTT_ERROR_ACK_OF_UNKNOWN, MQTT_ERROR_NOT_IMPLEMENTED, MQTT_ERROR_CONNECTION_REFUSED, MQTT_ERROR_SUBSCRIBE_FAILED, MQTT_ERROR_CONNECTION_CLOSED, MQTT_ERROR_INITIAL_RECONNECT, MQTT_ERROR_INVALID_REMAINING_LENGTH, MQTT_OK = 1 }
| An enumeration of error codes. Error messages can be retrieved by calling mqtt_error_str. More...
enum | MQTTConnackReturnCode { MQTT_CONNACK_ACCEPTED = 0u, MQTT_CONNACK_REFUSED_PROTOCOL_VERSION = 1u, MQTT_CONNACK_REFUSED_IDENTIFIER_REJECTED = 2u, MQTT_CONNACK_REFUSED_SERVER_UNAVAILABLE = 3u, MQTT_CONNACK_REFUSED_BAD_USER_NAME_OR_PASSWORD = 4u, MQTT_CONNACK_REFUSED_NOT_AUTHORIZED = 5u }
| An enumeration of the return codes returned in a CONNACK packet. More...
enum | MQTTSubackReturnCodes { MQTT_SUBACK_SUCCESS_MAX_QOS_0 = 0u, MQTT_SUBACK_SUCCESS_MAX_QOS_1 = 1u, MQTT_SUBACK_SUCCESS_MAX_QOS_2 = 2u, MQTT_SUBACK_FAILURE = 128u }
| An enumeration of subscription acknowledgement return codes. More...
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...
enum | MQTTQueuedMessageState { MQTT_QUEUED_UNSENT, MQTT_QUEUED_AWAITING_ACK, MQTT_QUEUED_COMPLETE }
| An enumeration of queued message states.

## Functions
const char * | mqtt_error_str (enum MQTTErrors error)
| Returns an error message for error code, `error`. More...
ssize_t | __mqtt_pack_uint16 (uint8_t *buf, uint16_t integer)
| Pack a MQTT 16 bit integer, given a native 16 bit integer . More...
uint16_t | __mqtt_unpack_uint16 (const uint8_t *buf)
| Unpack a MQTT 16 bit integer to a native 16 bit integer. More...
ssize_t | __mqtt_pack_str (uint8_t *buf, const char *str)
| Pack a MQTT string, given a c-string `str`. More...
ssize_t | mqtt_unpack_fixed_header (struct mqtt_response *response, const uint8_t *buf, size_t bufsz)
| Deserialize the contents of `buf` into an mqtt_fixed_header object. More...
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...
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...
enum MQTTErrors | mqtt_sync (struct mqtt_client *client)
| Function that does the actual sending and receiving of traffic from the network.All the other functions in the API simply stage messages for being sent to the broker. This function does the actual sending of those messages. Additionally this function receives traffic (responses and acknowledgements) from the broker and responds to that traffic accordingly. Lastly this function also calls the `publish_response_callback` when any `MQTT_CONTROL_PUBLISH` messages are received. More...
enum MQTTErrors | mqtt_init (struct mqtt_client *client, mqtt_pal_socket_handle sockfd, uint8_t *sendbuf, size_t sendbufsz, uint8_t *recvbuf, size_t recvbufsz, void(*publish_response_callback)(void **state, struct mqtt_response_publish *publish))
| Initializes an MQTT client.This function must be called before any other API function calls. More...
void | mqtt_init_reconnect (struct mqtt_client *client, void(*reconnect_callback)(struct mqtt_client *client, void **state), void *reconnect_state, void(*publish_response_callback)(void **state, struct mqtt_response_publish *publish))
| Initializes an MQTT client and enables automatic reconnections.An alternative to mqtt_init that allows the client to automatically reconnect to the broker after an error occurs (e.g. socket error or internal buffer overflows). More...
void | mqtt_reinit (struct mqtt_client *client, mqtt_pal_socket_handle socketfd, uint8_t *sendbuf, size_t sendbufsz, uint8_t *recvbuf, size_t recvbufsz)
| Safely assign/reassign a socket and buffers to an new/existing client.This function also clears the `client` error state. Upon exiting this function `client->error` will be `MQTT_ERROR_CONNECT_NOT_CALLED` (which will be cleared) as soon as mqtt_connect is called. More...
enum MQTTErrors | mqtt_connect (struct mqtt_client *client, 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)
| Establishes a session with the MQTT broker. More...
enum MQTTErrors | mqtt_publish (struct mqtt_client *client, const char *topic_name, void *application_message, size_t application_message_size, uint8_t publish_flags)
| Publish an application message.Publishes an application message to the MQTT broker. 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...
enum MQTTErrors | mqtt_subscribe (struct mqtt_client *client, const char *topic_name, int max_qos_level)
| Subscribe to a topic. More...
enum MQTTErrors | mqtt_unsubscribe (struct mqtt_client *client, const char *topic_name)
| Unsubscribe from a topic. More...
enum MQTTErrors | mqtt_ping (struct mqtt_client *client)
| Ping the broker. More...
enum MQTTErrors | __mqtt_ping (struct mqtt_client *client)
| Ping the broker without locking/unlocking the mutex. More...
enum MQTTErrors | mqtt_disconnect (struct mqtt_client *client)
| Terminate the session with the MQTT broker. More...

## Detailed Description

Declares all the MQTT-C functions and datastructures.

Note
  You should `#include <mqtt.h>`.

## Macro Definition Documentation

## ◆ __ALL_MQTT_ERRORS

#define __ALL_MQTT_ERRORS | ( |  | MQTT_ERROR | ) |

Value:
MQTT_ERROR(MQTT_ERROR_NULLPTR) \
MQTT_ERROR(MQTT_ERROR_CONTROL_FORBIDDEN_TYPE) \
MQTT_ERROR(MQTT_ERROR_CONTROL_INVALID_FLAGS) \
MQTT_ERROR(MQTT_ERROR_CONTROL_WRONG_TYPE) \
MQTT_ERROR(MQTT_ERROR_CONNECT_NULL_CLIENT_ID) \
MQTT_ERROR(MQTT_ERROR_CONNECT_NULL_WILL_MESSAGE) \
MQTT_ERROR(MQTT_ERROR_CONNECT_FORBIDDEN_WILL_QOS) \
MQTT_ERROR(MQTT_ERROR_CONNACK_FORBIDDEN_FLAGS) \
MQTT_ERROR(MQTT_ERROR_CONNACK_FORBIDDEN_CODE) \
MQTT_ERROR(MQTT_ERROR_PUBLISH_FORBIDDEN_QOS) \
MQTT_ERROR(MQTT_ERROR_SUBSCRIBE_TOO_MANY_TOPICS) \
MQTT_ERROR(MQTT_ERROR_MALFORMED_RESPONSE) \
MQTT_ERROR(MQTT_ERROR_UNSUBSCRIBE_TOO_MANY_TOPICS) \
MQTT_ERROR(MQTT_ERROR_RESPONSE_INVALID_CONTROL_TYPE) \
MQTT_ERROR(MQTT_ERROR_CONNECT_NOT_CALLED) \
MQTT_ERROR(MQTT_ERROR_SEND_BUFFER_IS_FULL) \
MQTT_ERROR(MQTT_ERROR_SOCKET_ERROR) \
MQTT_ERROR(MQTT_ERROR_MALFORMED_REQUEST) \
MQTT_ERROR(MQTT_ERROR_RECV_BUFFER_TOO_SMALL) \
MQTT_ERROR(MQTT_ERROR_ACK_OF_UNKNOWN) \
MQTT_ERROR(MQTT_ERROR_NOT_IMPLEMENTED) \
MQTT_ERROR(MQTT_ERROR_CONNECTION_REFUSED) \
MQTT_ERROR(MQTT_ERROR_SUBSCRIBE_FAILED) \
MQTT_ERROR(MQTT_ERROR_CONNECTION_CLOSED) \
MQTT_ERROR(MQTT_ERROR_INITIAL_RECONNECT) \
MQTT_ERROR(MQTT_ERROR_INVALID_REMAINING_LENGTH)

A macro used to declare the enum MQTTErrors and associated error messages (the members of the num) at the same time.

## ◆ GENERATE_ENUM

#define GENERATE_ENUM | ( |  | ENUM | ) | ENUM,

A macro used to generate the enum MQTTErrors from __ALL_MQTT_ERRORS.

See also
  __ALL_MQTT_ERRORS

## ◆ GENERATE_STRING

#define GENERATE_STRING | ( |  | STRING | ) | #STRING,

A macro used to generate the error messages associated with MQTTErrors from __ALL_MQTT_ERRORS.

See also
  __ALL_MQTT_ERRORS

## Function Documentation

## ◆ __mqtt_pack_str()

ssize_t __mqtt_pack_str | ( | uint8_t * | buf,
|  | const char * | str
| ) |  |

Pack a MQTT string, given a c-string `str`.

Parameters

  [out] | buf | the buffer that the MQTT string will be written to.
  [in] | str | the c-string to be written to `buf`.

Warning
  This function provides no error checking.

Returns
  strlen(str) + 2

## ◆ __mqtt_pack_uint16()

ssize_t __mqtt_pack_uint16 | ( | uint8_t * | buf,
|  | uint16_t | integer
| ) |  |

Pack a MQTT 16 bit integer, given a native 16 bit integer .

Parameters

  [out] | buf | the buffer that the MQTT integer will be written to.
  [in] | integer | the native integer to be written to `buf`.

Warning
  This function provides no error checking.

Returns
  2

## ◆ __mqtt_ping()

enum MQTTErrors __mqtt_ping | ( | struct mqtt_client * | client | ) |

Ping the broker without locking/unlocking the mutex.

See also
  mqtt_ping

## ◆ __mqtt_unpack_uint16()

uint16_t __mqtt_unpack_uint16 | ( | const uint8_t * | buf | ) |

Unpack a MQTT 16 bit integer to a native 16 bit integer.

Parameters

  [in] | buf | the buffer that the MQTT integer will be read from.

Warning
  This function provides no error checking and does not modify `buf`.

Returns
  The native integer