1 /******************************************************************************* 2 * Copyright (c) 2009, 2012 IBM Corp. 3 * 4 * All rights reserved. This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License v1.0 6 * and Eclipse Distribution License v1.0 which accompany this distribution. 7 * 8 * The Eclipse Public License is available at 9 * http://www.eclipse.org/legal/epl-v10.html 10 * and the Eclipse Distribution License is available at 11 * http://www.eclipse.org/org/documents/edl-v10.php. 12 * 13 * Contributors: 14 * Ian Craggs - initial API and implementation and/or initial documentation 15 *******************************************************************************/ 16 17 /** 18 * @file 19 * \brief This structure represents a persistent data store, used to store 20 * outbound and inbound messages, in order to achieve reliable messaging. 21 * 22 * The MQTT Client persists QoS1 and QoS2 messages in order to meet the 23 * assurances of delivery associated with these @ref qos levels. The messages 24 * are saved in persistent storage 25 * The type and context of the persistence implementation are specified when 26 * the MQTT client is created (see MQTTClient_create()). The default 27 * persistence type (::MQTTCLIENT_PERSISTENCE_DEFAULT) uses a file system-based 28 * persistence mechanism. The <i>persistence_context</i> argument passed to 29 * MQTTClient_create() when using the default peristence is a string 30 * representing the location of the persistence directory. If the context 31 * argument is NULL, the working directory will be used. 32 * 33 * To use memory-based persistence, an application passes 34 * ::MQTTCLIENT_PERSISTENCE_NONE as the <i>persistence_type</i> to 35 * MQTTClient_create(). This can lead to message loss in certain situations, 36 * but can be appropriate in some cases (see @ref qos). 37 * 38 * Client applications can provide their own persistence mechanism by passing 39 * ::MQTTCLIENT_PERSISTENCE_USER as the <i>persistence_type</i>. To implement a 40 * custom persistence mechanism, the application must pass an initialized 41 * ::MQTTClient_persistence structure as the <i>persistence_context</i> 42 * argument to MQTTClient_create(). 43 * 44 * If the functions defined return an ::MQTTCLIENT_PERSISTENCE_ERROR then the 45 * state of the persisted data should remain as it was prior to the function 46 * being called. For example, if Persistence_put() returns 47 * ::MQTTCLIENT_PERSISTENCE_ERROR, then it is assumed tha tthe persistent store 48 * does not contain the data that was passed to the function. Similarly, if 49 * Persistence_remove() returns ::MQTTCLIENT_PERSISTENCE_ERROR then it is 50 * assumed that the data to be removed is still held in the persistent store. 51 * 52 * It is up to the persistence implementation to log any error information that 53 * may be required to diagnose a persistence mechanism failure. 54 */ 55 56 /* 57 /// @cond EXCLUDE 58 */ 59 #if !defined(MQTTCLIENTPERSISTENCE_H) 60 #define MQTTCLIENTPERSISTENCE_H 61 /* 62 /// @endcond 63 */ 64 65 /** 66 * This <i>persistence_type</i> value specifies the default file system-based 67 * persistence mechanism (see MQTTClient_create()). 68 */ 69 #define MQTTCLIENT_PERSISTENCE_DEFAULT 0 70 /** 71 * This <i>persistence_type</i> value specifies a memory-based 72 * persistence mechanism (see MQTTClient_create()). 73 */ 74 #define MQTTCLIENT_PERSISTENCE_NONE 1 75 /** 76 * This <i>persistence_type</i> value specifies an application-specific 77 * persistence mechanism (see MQTTClient_create()). 78 */ 79 #define MQTTCLIENT_PERSISTENCE_USER 2 80 81 /** 82 * Application-specific persistence functions must return this error code if 83 * there is a problem executing the function. 84 */ 85 #define MQTTCLIENT_PERSISTENCE_ERROR -2 86 87 /** 88 * @brief Initialize the persistent store. 89 * 90 * Either open the existing persistent store for this client ID or create a new 91 * one if one doesn't exist. If the persistent store is already open, return 92 * without taking any action. 93 * 94 * An application can use the same client identifier to connect to many 95 * different servers. The <i>clientid</i> in conjunction with the 96 * <i>serverURI</i> uniquely identifies the persistence store required. 97 * 98 * @param handle The address of a pointer to a handle for this persistence 99 * implementation. This function must set handle to a valid reference to the 100 * persistence following a successful return. 101 * The handle pointer is passed as an argument to all the other 102 * persistence functions. It may include the context parameter and/or any other 103 * data for use by the persistence functions. 104 * @param clientID The client identifier for which the persistent store should 105 * be opened. 106 * @param serverURI The connection string specified when the MQTT client was 107 * created (see MQTTClient_create()). 108 * @param context A pointer to any data required to initialize the persistent 109 * store (see ::MQTTClient_persistence). 110 * @return Return 0 if the function completes successfully, otherwise return 111 * ::MQTTCLIENT_PERSISTENCE_ERROR. 112 */ 113 typedef int (*Persistence_open)(void** handle, const char* clientID, const char* serverURI, void* context); 114 115 /** 116 * @brief Close the persistent store referred to by the handle. 117 * 118 * @param handle The handle pointer from a successful call to 119 * Persistence_open(). 120 * @return Return 0 if the function completes successfully, otherwise return 121 * ::MQTTCLIENT_PERSISTENCE_ERROR. 122 */ 123 typedef int (*Persistence_close)(void* handle); 124 125 /** 126 * @brief Put the specified data into the persistent store. 127 * 128 * @param handle The handle pointer from a successful call to 129 * Persistence_open(). 130 * @param key A string used as the key for the data to be put in the store. The 131 * key is later used to retrieve data from the store with Persistence_get(). 132 * @param bufcount The number of buffers to write to the persistence store. 133 * @param buffers An array of pointers to the data buffers associated with 134 * this <i>key</i>. 135 * @param buflens An array of lengths of the data buffers. <i>buflen[n]</i> 136 * gives the length of <i>buffer[n]</i>. 137 * @return Return 0 if the function completes successfully, otherwise return 138 * ::MQTTCLIENT_PERSISTENCE_ERROR. 139 */ 140 typedef int (*Persistence_put)(void* handle, char* key, int bufcount, char* buffers[], int buflens[]); 141 142 /** 143 * @brief Retrieve the specified data from the persistent store. 144 * 145 * @param handle The handle pointer from a successful call to 146 * Persistence_open(). 147 * @param key A string that is the key for the data to be retrieved. This is 148 * the same key used to save the data to the store with Persistence_put(). 149 * @param buffer The address of a pointer to a buffer. This function sets the 150 * pointer to point at the retrieved data, if successful. 151 * @param buflen The address of an int that is set to the length of 152 * <i>buffer</i> by this function if successful. 153 * @return Return 0 if the function completes successfully, otherwise return 154 * ::MQTTCLIENT_PERSISTENCE_ERROR. 155 */ 156 typedef int (*Persistence_get)(void* handle, char* key, char** buffer, int* buflen); 157 158 /** 159 * @brief Remove the data for the specified key from the store. 160 * 161 * @param handle The handle pointer from a successful call to 162 * Persistence_open(). 163 * @param key A string that is the key for the data to be removed from the 164 * store. This is the same key used to save the data to the store with 165 * Persistence_put(). 166 * @return Return 0 if the function completes successfully, otherwise return 167 * ::MQTTCLIENT_PERSISTENCE_ERROR. 168 */ 169 typedef int (*Persistence_remove)(void* handle, char* key); 170 171 /** 172 * @brief Returns the keys in this persistent data store. 173 * 174 * @param handle The handle pointer from a successful call to 175 * Persistence_open(). 176 * @param keys The address of a pointer to pointers to strings. Assuming 177 * successful execution, this function allocates memory to hold the returned 178 * keys (strings used to store the data with Persistence_put()). It also 179 * allocates memory to hold an array of pointers to these strings. <i>keys</i> 180 * is set to point to the array of pointers to strings. 181 * @param nkeys A pointer to the number of keys in this persistent data store. 182 * This function sets the number of keys, if successful. 183 * @return Return 0 if the function completes successfully, otherwise return 184 * ::MQTTCLIENT_PERSISTENCE_ERROR. 185 */ 186 typedef int (*Persistence_keys)(void* handle, char*** keys, int* nkeys); 187 188 /** 189 * @brief Clears the persistence store, so that it no longer contains any 190 * persisted data. 191 * 192 * @param handle The handle pointer from a successful call to 193 * Persistence_open(). 194 * @return Return 0 if the function completes successfully, otherwise return 195 * ::MQTTCLIENT_PERSISTENCE_ERROR. 196 */ 197 typedef int (*Persistence_clear)(void* handle); 198 199 /** 200 * @brief Returns whether any data has been persisted using the specified key. 201 * 202 * @param handle The handle pointer from a successful call to 203 * Persistence_open(). 204 * @param key The string to be tested for existence in the store. 205 * @return Return 0 if the key was found in the store, otherwise return 206 * ::MQTTCLIENT_PERSISTENCE_ERROR. 207 */ 208 typedef int (*Persistence_containskey)(void* handle, char* key); 209 210 /** 211 * @brief A structure containing the function pointers to a persistence 212 * implementation and the context or state that will be shared across all 213 * the persistence functions. 214 */ 215 typedef struct { 216 /** 217 * A pointer to any data required to initialize the persistent store. 218 */ 219 void* context; 220 /** 221 * A function pointer to an implementation of Persistence_open(). 222 */ 223 Persistence_open popen; 224 /** 225 * A function pointer to an implementation of Persistence_close(). 226 */ 227 Persistence_close pclose; 228 /** 229 * A function pointer to an implementation of Persistence_put(). 230 */ 231 Persistence_put pput; 232 /** 233 * A function pointer to an implementation of Persistence_get(). 234 */ 235 Persistence_get pget; 236 /** 237 * A function pointer to an implementation of Persistence_remove(). 238 */ 239 Persistence_remove premove; 240 /** 241 * A function pointer to an implementation of Persistence_keys(). 242 */ 243 Persistence_keys pkeys; 244 /** 245 * A function pointer to an implementation of Persistence_clear(). 246 */ 247 Persistence_clear pclear; 248 /** 249 * A function pointer to an implementation of Persistence_containskey(). 250 */ 251 Persistence_containskey pcontainskey; 252 } MQTTClient_persistence; 253 254 #endif 255