MQTT-C: API

MQTT-C

Enumerations | Functions
API

Documentation of everything you need to know to use the MQTT-C client. More...

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

## Functions
const char * | mqtt_error_str (enum MQTTErrors error)
| Returns an error message for error code, `error`. 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...
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_disconnect (struct mqtt_client *client)
| Terminate the session with the MQTT broker. More...

## Detailed Description

Documentation of everything you need to know to use the MQTT-C client.

This module contains everything you need to know to use MQTT-C in your application. For usage examples see:

- simple_publisher.c
- simple_subscriber.c
- reconnect_subscriber.c
- bio_publisher.c
- openssl_publisher.c

Note
  MQTT-C can be used in both single-threaded and multi-threaded applications. All the functions in API are thread-safe.

## Enumeration Type Documentation

## ◆ MQTTErrors

enum MQTTErrors

An enumeration of error codes. Error messages can be retrieved by calling mqtt_error_str.

See also
  mqtt_error_str

## Function Documentation

## ◆ mqtt_connect()

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.

Precondition
  mqtt_init must have been called.

Parameters

  [in,out] | client | The MQTT client.
  [in] | client_id | The unique name identifying the client.
  [in] | will_topic | The topic name of client's `will_message`. If no will message is desired set to `NULL`.
  [in] | will_message | The application message (data) to be published in the event the client ungracefully disconnects. Set to `NULL` if `will_topic` is `NULL`.
  [in] | will_message_size | The size of `will_message` in bytes.
  [in] | user_name | The username to use when establishing the session with the MQTT broker. Set to `NULL` if a username is not required.
  [in] | password | The password to use when establishing the session with the MQTT broker. Set to `NULL` if a password is not required.
  [in] | connect_flags | Additional MQTTConnectFlags to use when establishing the connection. These flags are for forcing the session to start clean, `MQTT_CONNECT_CLEAN_SESSION`, the QOS level to publish the `will_message` with (provided `will_message` != `NULL`), MQTT_CONNECT_WILL_QOS_[0,1,2], and whether or not the broker should retain the `will_message`, MQTT_CONNECT_WILL_RETAIN.
  [in] | keep_alive | The keep-alive time in seconds. A reasonable value for this is 400 [seconds].

Returns
  `MQTT_OK` upon success, an MQTTErrors otherwise.

Examples:
  bio_publisher.c, openssl_publisher.c, reconnect_subscriber.c, simple_publisher.c, and simple_subscriber.c.

## ◆ mqtt_disconnect()

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

Terminate the session with the MQTT broker.

Precondition
  mqtt_connect must have been called.

Parameters

  [in,out] | client | The MQTT client.

Note
  To re-establish the session, mqtt_connect must be called.

Returns
  `MQTT_OK` upon success, an MQTTErrors otherwise.

## ◆ mqtt_error_str()

const char* mqtt_error_str | ( | enum MQTTErrors | error | ) |

Returns an error message for error code, `error`.

Parameters

  [in] | error | the error code.

Returns
  The associated error message.

Examples:
  bio_publisher.c, openssl_publisher.c, reconnect_subscriber.c, simple_publisher.c, and simple_subscriber.c.

## ◆ mqtt_init()

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(*)(void **state, struct mqtt_response_publish *publish) | publish_response_callback
| ) |  |

Initializes an MQTT client.This function must be called before any other API function calls.

Precondition
  None.

Parameters

  [out] | client | The MQTT client.
  [in] | sockfd | The socket file descriptor (or equivalent socket handle, e.g. BIO pointer for OpenSSL sockets) connected to the MQTT broker.
  [in] | sendbuf | A buffer that will be used for sending messages to the broker.
  [in] | sendbufsz | The size of `sendbuf` in bytes.
  [in] | recvbuf | A buffer that will be used for receiving messages from the broker.
  [in] | recvbufsz | The size of `recvbuf` in bytes.
  [in] | publish_response_callback | The callback to call whenever application messages are received from the broker.

Postcondition
  mqtt_connect must be called.

Note
  `sockfd` is a non-blocking TCP connection.
  If `sendbuf` fills up completely during runtime a `MQTT_ERROR_SEND_BUFFER_IS_FULL` error will be set. Similarly if `recvbuf` is ever to small to receive a message from the broker an MQTT_ERROR_RECV_BUFFER_TOO_SMALL error will be set.
  A pointer to mqtt_client::publish_response_callback_state is always passed as the `state` argument to `publish_response_callback`. Note that the second argument is the mqtt_response_publish that was received from the broker.

Attention
  Only initialize an MQTT client once (i.e. don't call mqtt_init or mqtt_init_reconnect more than once per client).

Returns
  `MQTT_OK` upon success, an MQTTErrors otherwise.

Examples:
  bio_publisher.c, openssl_publisher.c, simple_publisher.c, and simple_subscriber.c.

## ◆ mqtt_init_reconnect()

void mqtt_init_reconnect | ( | struct mqtt_client * | client,
|  | void(*)(struct mqtt_client *client, void **state) | reconnect_callback,
|  | void * | reconnect_state,
|  | void(*)(void **state, struct mqtt_response_publish *publish) | publish_response_callback
| ) |  |

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

This is accomplished by calling the `reconnect_callback` whenever the client enters an error state. The job of the `reconnect_callback` is to: (1) perform error handling/logging, (2) clean up the old connection (i.e. close client->socketfd), (3) mqtt_reinit the client, and (4) reconfigure the MQTT session by calling mqtt_connect followed by other API calls such as mqtt_subscribe.

The first argument to the `reconnect_callback` is the client (which will be in an error state) and the second argument is a pointer to a void pointer where you can store some state information. Internally, MQTT-C calls the reconnect callback like so:

client->reconnect_callback(client, &client->reconnect_state)

Note that the `reconnect_callback` is also called to setup the initial session. After calling mqtt_init_reconnect the client will be in the error state `MQTT_ERROR_INITIAL_RECONNECT`.

Precondition
  None.

Parameters

  [in,out] | client | The MQTT client that will be initialized.
  [in] | reconnect_callback | The callback that will be called to connect/reconnect the client to the broker and perform application level error handling.
  [in] | reconnect_state | A pointer to some state data for your `reconnect_callback`. If your `reconnect_callback` does not require any state information set this to NULL. A pointer to the memory address where the client stores a copy of this pointer is passed as the second argumnet to `reconnect_callback`.
  [in] | publish_response_callback | The callback to call whenever application messages are received from the broker.

Postcondition
  Call `reconnect_callback` yourself, or call mqtt_sync (which will trigger the call to `reconnect_callback`).

Attention
  Only initialize an MQTT client once (i.e. don't call mqtt_init or mqtt_init_reconnect more than once per client).

Examples:
  reconnect_subscriber.c.

## ◆ mqtt_ping()

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

Ping the broker.

Precondition
  mqtt_connect must have been called.

Parameters

  [in,out] | client | The MQTT client.

Returns
  `MQTT_OK` upon success, an MQTTErrors otherwise.

## ◆ mqtt_publish()

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.

Precondition
  mqtt_connect must have been called.

Parameters

  [in,out] | client | The MQTT client.
  [in] | topic_name | The name of the topic.
  [in] | application_message | The data to be published.
  [in] | application_message_size | The size of `application_message` in bytes.
  [in] | publish_flags | MQTTPublishFlags to be used, namely the QOS level to publish at (MQTT_PUBLISH_QOS_[0,1,2]) or whether or not the broker should retain the publish (MQTT_PUBLISH_RETAIN).

Returns
  `MQTT_OK` upon success, an MQTTErrors otherwise.

Examples:
  bio_publisher.c, openssl_publisher.c, and simple_publisher.c.

## ◆ mqtt_reinit()

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.

Precondition
  This function must be called BEFORE mqtt_connect.

Parameters

  [in,out] | client | The MQTT client.
  [in] | socketfd | The new socket connected to the broker.
  [in] | sendbuf | The buffer that will be used to buffer egress traffic to the broker.
  [in] | sendbufsz | The size of `sendbuf` in bytes.
  [in] | recvbuf | The buffer that will be used to buffer ingress traffic from the broker.
  [in] | recvbufsz | The size of `recvbuf` in bytes.

Postcondition
  Call mqtt_connect.

Attention
  This function should be used in conjunction with clients that have been initialzed with mqtt_init_reconnect.

Examples:
  reconnect_subscriber.c.

## ◆ mqtt_subscribe()

enum MQTTErrors mqtt_subscribe | ( | struct mqtt_client * | client,
|  | const char * | topic_name,
|  | int | max_qos_level
| ) |  |

Subscribe to a topic.

Precondition
  mqtt_connect must have been called.

Parameters

  [in,out] | client | The MQTT client.
  [in] | topic_name | The name of the topic to subscribe to.
  [in] | max_qos_level | The maximum QOS level with which the broker can send application messages for this topic.

Returns
  `MQTT_OK` upon success, an MQTTErrors otherwise.

Examples:
  reconnect_subscriber.c, and simple_subscriber.c.

## ◆ mqtt_sync()

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.

Precondition
  mqtt_init must have been called.

Parameters

  [in,out] | client | The MQTT client.

Attention
  It is the responsibility of the application programmer to call this function periodically. All functions in the API are thread-safe so it is perfectly reasonable to have a thread dedicated to calling this function every 200 ms or so. MQTT-C can be used in single threaded application though by simply calling this functino periodically inside your main thread. See simple_publisher.c and simple_subscriber.c for examples (specifically the `client_refresher` functions).

Returns
  MQTT_OK upon success, an MQTTErrors otherwise.

Examples:
  bio_publisher.c, openssl_publisher.c, reconnect_subscriber.c, simple_publisher.c, and simple_subscriber.c.

## ◆ mqtt_unsubscribe()

enum MQTTErrors mqtt_unsubscribe | ( | struct mqtt_client * | client,
|  | const char * | topic_name
| ) |  |

Unsubscribe from a topic.

Precondition
  mqtt_connect must have been called.

Parameters

  [in,out] | client | The MQTT client.
  [in] | topic_name | The name of the topic to unsubscribe from.

Returns
  `MQTT_OK` upon success, an MQTTErrors otherwise.