MQTTClientPersistence.h(3)

📦
version 1.3.16 · 7 versions
, in fedora 44

💖 MQTTClientPersistence.h(3) — Library Functions Manual 💖

okay bestie, sit down, hydrate, because we're about to get into MQTTClientPersistence.h and honestly? it's giving infrastructure that carries the whole vibe. this is the persistence layer for MQTT, and if you don't understand it, your QoS1 and QoS2 messages are just gonna be out here ghosting people. let's go 🫶

✨ NAME ✨

MQTTClientPersistence.h — this structure represents a persistent data store, used to store outbound and inbound messages, in order to achieve reliable messaging.

✨ SYNOPSIS ✨

🌸 Data Structures

  • struct MQTTClient_persistence — a structure containing the function pointers to a persistence implementation and the context or state that will be shared across all the persistence functions. it's basically the group chat config, iykyk 💅

🌸 Macros

#define MQTTCLIENT_PERSISTENCE_DEFAULT   0
#define MQTTCLIENT_PERSISTENCE_NONE   1
#define MQTTCLIENT_PERSISTENCE_USER   2
#define MQTTCLIENT_PERSISTENCE_ERROR   -2

🌸 Typedefs

  • typedef int(* Persistence_open) (void **handle, const char *clientID, const char *serverURI, void *context) — Initialize the persistent store. it's the "hey bestie, wake up" call ✨
  • typedef int(* Persistence_close) (void *handle) — Close the persistent store referred to by the handle. say bye, no ghosting 🎀
  • typedef int(* Persistence_put) (void *handle, char *key, int bufcount, char *buffers[], int buflens[]) — Put the specified data into the persistent store.
  • typedef int(* Persistence_get) (void *handle, char *key, char **buffer, int *buflen) — Retrieve the specified data from the persistent store.
  • typedef int(* Persistence_remove) (void *handle, char *key) — Remove the data for the specified key from the store. it's giving blocked 🚫
  • typedef int(* Persistence_keys) (void *handle, char ***keys, int *nkeys) — Returns the keys in this persistent data store.
  • typedef int(* Persistence_clear) (void *handle) — Clears the persistence store, so that it no longer contains any persisted data. factory reset energy 💀
  • typedef int(* Persistence_containskey) (void *handle, char *key) — Returns whether any data has been persisted using the specified key.
  • typedef int MQTTPersistence_beforeWrite(void *context, int bufcount, char *buffers[], int buflens[])
  • typedef int MQTTPersistence_afterRead(void *context, char **buffer, int *buflen)

✨ Detailed Description ✨

This structure represents a persistent data store, used to store outbound and inbound messages, in order to achieve reliable messaging. reliable messaging is the whole point, periodt.

The MQTT Client persists QoS1 and QoS2 messages in order to meet the assurances of delivery associated with these Quality of service levels. The messages are saved in persistent storage The type and context of the persistence implementation are specified when the MQTT client is created (see MQTTClient_create()). The default persistence type (MQTTCLIENT_PERSISTENCE_DEFAULT) uses a file system-based persistence mechanism. The persistence_context argument passed to MQTTClient_create() when using the default peristence is a string representing the location of the persistence directory. If the context argument is NULL, the working directory will be used. no cap, NULL means "just use wherever you already are."

To use memory-based persistence, an application passes MQTTCLIENT_PERSISTENCE_NONE as the persistence_type to MQTTClient_create(). This can lead to message loss in certain situations, but can be appropriate in some cases (see Quality of service). ⚠️ message loss is real, bestie — do not play with this unless you know what you're doing.

Client applications can provide their own persistence mechanism by passing MQTTCLIENT_PERSISTENCE_USER as the persistence_type. To implement a custom persistence mechanism, the application must pass an initialized MQTTClient_persistence structure as the persistence_context argument to MQTTClient_create(). main character energy: build your own, slay.

If the functions defined return an MQTTCLIENT_PERSISTENCE_ERROR then the state of the persisted data should remain as it was prior to the function being called. For example, if Persistence_put() returns MQTTCLIENT_PERSISTENCE_ERROR, then it is assumed that the persistent store does not contain the data that was passed to the function. Similarly, if Persistence_remove() returns MQTTCLIENT_PERSISTENCE_ERROR then it is assumed that the data to be removed is still held in the persistent store. basically: if it errors, it's like it never happened. atomicity vibes, we love to see it.

It is up to the persistence implementation to log any error information that may be required to diagnose a persistence mechanism failure. you want logs? you're gonna have to write them yourself, queen. the library is not doing it for you.

✨ Macro Definition Documentation ✨

🦋 #define MQTTCLIENT_PERSISTENCE_DEFAULT 0

This persistence_type value specifies the default file system-based persistence mechanism (see MQTTClient_create()). the classic. the default. the safe pick.

🦋 #define MQTTCLIENT_PERSISTENCE_NONE 1

This persistence_type value specifies a memory-based persistence mechanism (see MQTTClient_create()). fast, but forgetful. it's giving goldfish memory 🐠

🦋 #define MQTTCLIENT_PERSISTENCE_USER 2

This persistence_type value specifies an application-specific persistence mechanism (see MQTTClient_create()). DIY era ✨

🦋 #define MQTTCLIENT_PERSISTENCE_ERROR -2

Application-specific persistence functions must return this error code if there is a problem executing the function. this is the "something went wrong" flag, and you MUST return it when something goes wrong. no vibes-based silent failures, okay? 💅

okay that's part 1, don't go anywhere — there's more coming 🫶✨

🌸 Typedef Documentation 🌸

okay bestie, this is where we meet all the function-pointer typedefs that make up the persistence interface. they're literally the blueprint for plugging your own storage into Paho. let's go one by one, no skipping, fr fr. ✨

Persistence_open

typedef int(* Persistence_open) (void **handle, const char *clientID, const char *serverURI, void *context)

Initialize the persistent store. Either open the existing persistent store for this client ID or create a new one if one doesn't exist. If the persistent store is already open, return without taking any action.

An application can use the same client identifier to connect to many different servers. The clientid in conjunction with the serverURI uniquely identifies the persistence store required.

Parameters

  • handle — The address of a pointer to a handle for this persistence implementation. This function must set handle to a valid reference to the persistence following a successful return. The handle pointer is passed as an argument to all the other persistence functions. It may include the context parameter and/or any other data for use by the persistence functions.
  • clientID — The client identifier for which the persistent store should be opened.
  • serverURI — The connection string specified when the MQTT client was created (see MQTTClient_create()).
  • context — A pointer to any data required to initialize the persistent store (see MQTTClient_persistence).

Returns

Return 0 if the function completes successfully, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

Persistence_close

typedef int(* Persistence_close) (void *handle)

Close the persistent store referred to by the handle.

Parameters

  • handle — The handle pointer from a successful call to Persistence_open().

Returns

Return 0 if the function completes successfully, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

Persistence_put

typedef int(* Persistence_put) (void *handle, char *key, int bufcount, char *buffers[], int buflens[])

Put the specified data into the persistent store.

Parameters

  • handle — The handle pointer from a successful call to Persistence_open().
  • key — A string used as the key for the data to be put in the store. The key is later used to retrieve data from the store with Persistence_get().
  • bufcount — The number of buffers to write to the persistence store.
  • buffers — An array of pointers to the data buffers associated with this key.
  • buflens — An array of lengths of the data buffers. buflen[n] gives the length of buffer[n].

Returns

Return 0 if the function completes successfully, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

Persistence_get

typedef int(* Persistence_get) (void *handle, char *key, char **buffer, int *buflen)

Retrieve the specified data from the persistent store.

Parameters

  • handle — The handle pointer from a successful call to Persistence_open().
  • key — A string that is the key for the data to be retrieved. This is the same key used to save the data to the store with Persistence_put().
  • buffer — The address of a pointer to a buffer. This function sets the pointer to point at the retrieved data, if successful.
  • buflen — The address of an int that is set to the length of buffer by this function if successful.

Returns

Return 0 if the function completes successfully, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

Persistence_remove

typedef int(* Persistence_remove) (void *handle, char *key)

Remove the data for the specified key from the store.

Parameters

  • handle — The handle pointer from a successful call to Persistence_open().
  • key — A string that is the key for the data to be removed from the store. This is the same key used to save the data to the store with Persistence_put().

Returns

Return 0 if the function completes successfully, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

Persistence_keys

typedef int(* Persistence_keys) (void *handle, char ***keys, int *nkeys)

Returns the keys in this persistent data store.

Parameters

  • handle — The handle pointer from a successful call to Persistence_open().
  • keys — The address of a pointer to pointers to strings. Assuming successful execution, this function allocates memory to hold the returned keys (strings used to store the data with Persistence_put()). It also allocates memory to hold an array of pointers to these strings. keys is set to point to the array of pointers to strings.
  • nkeys — A pointer to the number of keys in this persistent data store. This function sets the number of keys, if successful.

Returns

Return 0 if the function completes successfully, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

Persistence_clear

typedef int(* Persistence_clear) (void *handle)

Clears the persistence store, so that it no longer contains any persisted data.

Parameters

  • handle — The handle pointer from a successful call to Persistence_open().

Returns

Return 0 if the function completes successfully, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

Persistence_containskey

typedef int(* Persistence_containskey) (void *handle, char *key)

Returns whether any data has been persisted using the specified key.

Parameters

  • handle — The handle pointer from a successful call to Persistence_open().
  • key — The string to be tested for existence in the store.

Returns

Return 0 if the key was found in the store, otherwise return MQTTCLIENT_PERSISTENCE_ERROR.

MQTTPersistence_beforeWrite

typedef int MQTTPersistence_beforeWrite(void *context, int bufcount, char *buffers[], int buflens[])

A callback which is invoked just before a write to persistence. This can be used to transform the data, for instance to encrypt it.

Parameters

  • context — The context as set in ::MQTTAsync_setBeforePersistenceWrite
  • bufcount — The number of buffers to write to the persistence store.
  • buffers — An array of pointers to the data buffers.
  • buflens — An array of lengths of the data buffers.

Returns

Return 0 if the function completes successfully, otherwise non 0.

MQTTPersistence_afterRead

typedef int MQTTPersistence_afterRead(void *context, char **buffer, int *buflen)

A callback which is invoked just after a read from persistence. This can be used to transform the data, for instance to decrypt it.

Parameters

  • context — The context as set in ::MQTTAsync_setAfterPersistenceRead
  • buffer — The address of a pointer to a buffer.
  • buflen — The address of an int that is the length of the buffer.

Returns

Return 0 if the function completes successfully, otherwise non 0.

👑 Author 👑

Generated automatically by Doxygen for Paho MQTT C Client Library from the source code.

and that's the tea, bestie! this page is from the Paho MQTT C Client Library, dated Tue Jun 2 2026 00:00:00, and it documents MQTTClientPersistence.h(3). stay persistent, queen 💅💖🦋

📦 where this page comes from