gnunet_datastore_service.h (14520B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2004, 2005, 2006, 2007, 2009, 2010, 2011 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup fs_l2 File sharing and support services/libraries 23 * @{ 24 * 25 * @author Christian Grothoff 26 * 27 * @file 28 * datastore service 29 * 30 * @defgroup datastore Data Store service 31 * Data store for files stored on a GNUnet node. 32 * 33 * Provides an API that can be used manage the 34 * datastore for files stored on a GNUnet node. 35 * Note that the datastore is NOT responsible for 36 * on-demand encoding, that is achieved using 37 * a special kind of entry. 38 * 39 * @{ 40 */ 41 42 #ifndef GNUNET_DATASTORE_SERVICE_H 43 #define GNUNET_DATASTORE_SERVICE_H 44 45 46 #include "gnunet_util_lib.h" 47 #include "gnunet_block_lib.h" 48 49 #ifdef __cplusplus 50 extern "C" 51 { 52 #if 0 /* keep Emacsens' auto-indent happy */ 53 } 54 #endif 55 #endif 56 57 /** 58 * Entry in the queue. 59 */ 60 struct GNUNET_DATASTORE_QueueEntry; 61 62 /** 63 * Handle to the datastore service. 64 */ 65 struct GNUNET_DATASTORE_Handle; 66 67 /** 68 * Maximum size of a value that can be stored in the datastore. 69 */ 70 #define GNUNET_DATASTORE_MAX_VALUE_SIZE 65536 71 72 /** 73 * Connect to the datastore service. 74 * 75 * @param cfg configuration to use 76 * @return handle to use to access the service 77 */ 78 struct GNUNET_DATASTORE_Handle * 79 GNUNET_DATASTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); 80 81 82 /** 83 * Disconnect from the datastore service (and free 84 * associated resources). 85 * 86 * @param h handle to the datastore 87 * @param drop set to #GNUNET_YES to delete all data in datastore (!) 88 */ 89 void 90 GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h, 91 int drop); 92 93 94 /** 95 * Continuation called to notify client about result of the 96 * operation. 97 * 98 * @param cls closure 99 * @param success #GNUNET_SYSERR on failure 100 * #GNUNET_NO if content was already there 101 * #GNUNET_YES (or other positive value) on success 102 * @param min_expiration minimum expiration time required for 0-priority content to be stored 103 * by the datacache at this time, zero for unknown, forever if we have no 104 * space for 0-priority content 105 * @param msg NULL on success, otherwise an error message 106 */ 107 typedef void 108 (*GNUNET_DATASTORE_ContinuationWithStatus) (void *cls, 109 int32_t success, 110 struct GNUNET_TIME_Absolute 111 min_expiration, 112 const char *msg); 113 114 115 /** 116 * Reserve space in the datastore. This function should be used 117 * to avoid "out of space" failures during a longer sequence of "put" 118 * operations (for example, when a file is being inserted). 119 * 120 * @param h handle to the datastore 121 * @param amount how much space (in bytes) should be reserved (for content only) 122 * @param entries how many entries will be created (to calculate per-entry overhead) 123 * @param cont continuation to call when done; "success" will be set to 124 * a positive reservation value if space could be reserved. 125 * @param cont_cls closure for @a cont 126 * @return NULL if the entry was not queued, otherwise a handle that can be used to 127 * cancel; note that even if NULL is returned, the callback will be invoked 128 * (or rather, will already have been invoked) 129 */ 130 struct GNUNET_DATASTORE_QueueEntry * 131 GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h, 132 uint64_t amount, 133 uint32_t entries, 134 GNUNET_DATASTORE_ContinuationWithStatus cont, 135 void *cont_cls); 136 137 138 /** 139 * Store an item in the datastore. If the item is already present, 140 * the priorities and replication values are summed up and the higher 141 * expiration time and lower anonymity level is used. 142 * 143 * @param h handle to the datastore 144 * @param rid reservation ID to use (from "reserve"); use 0 if no 145 * prior reservation was made 146 * @param key key for the value 147 * @param size number of bytes in data 148 * @param data content stored 149 * @param type type of the content 150 * @param priority priority of the content 151 * @param anonymity anonymity-level for the content 152 * @param replication how often should the content be replicated to other peers? 153 * @param expiration expiration time for the content 154 * @param queue_priority ranking of this request in the priority queue 155 * @param max_queue_size at what queue size should this request be dropped 156 * (if other requests of higher priority are in the queue) 157 * @param cont continuation to call when done 158 * @param cont_cls closure for @a cont 159 * @return NULL if the entry was not queued, otherwise a handle that can be used to 160 * cancel; note that even if NULL is returned, the callback will be invoked 161 * (or rather, will already have been invoked) 162 */ 163 struct GNUNET_DATASTORE_QueueEntry * 164 GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h, 165 uint32_t rid, 166 const struct GNUNET_HashCode *key, 167 size_t size, 168 const void *data, 169 enum GNUNET_BLOCK_Type type, 170 uint32_t priority, 171 uint32_t anonymity, 172 uint32_t replication, 173 struct GNUNET_TIME_Absolute expiration, 174 unsigned int queue_priority, 175 unsigned int max_queue_size, 176 GNUNET_DATASTORE_ContinuationWithStatus cont, 177 void *cont_cls); 178 179 180 /** 181 * Signal that all of the data for which a reservation was made has 182 * been stored and that whatever excess space might have been reserved 183 * can now be released. 184 * 185 * @param h handle to the datastore 186 * @param rid reservation ID (value of "success" in original continuation 187 * from the "reserve" function). 188 * @param queue_priority ranking of this request in the priority queue 189 * @param max_queue_size at what queue size should this request be dropped 190 * (if other requests of higher priority are in the queue) 191 * @param queue_priority ranking of this request in the priority queue 192 * @param max_queue_size at what queue size should this request be dropped 193 * (if other requests of higher priority are in the queue) 194 * @param cont continuation to call when done 195 * @param cont_cls closure for @a cont 196 * @return NULL if the entry was not queued, otherwise a handle that can be used to 197 * cancel; note that even if NULL is returned, the callback will be invoked 198 * (or rather, will already have been invoked) 199 */ 200 struct GNUNET_DATASTORE_QueueEntry * 201 GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h, 202 uint32_t rid, unsigned int queue_priority, 203 unsigned int max_queue_size, 204 GNUNET_DATASTORE_ContinuationWithStatus cont, 205 void *cont_cls); 206 207 208 /** 209 * Explicitly remove some content from the database. @a cont will be 210 * called with status #GNUNET_OK if content was removed, #GNUNET_NO if 211 * no matching entry was found and #GNUNET_SYSERR on all other types 212 * of errors. 213 * 214 * @param h handle to the datastore 215 * @param key key for the value 216 * @param size number of bytes in @a data 217 * @param data content stored 218 * @param queue_priority ranking of this request in the priority queue 219 * @param max_queue_size at what queue size should this request be dropped 220 * (if other requests of higher priority are in the queue) 221 * @param cont continuation to call when done 222 * @param cont_cls closure for @a cont 223 * @return NULL if the entry was not queued, otherwise a handle that can be used to 224 * cancel; note that even if NULL is returned, the callback will be invoked 225 * (or rather, will already have been invoked) 226 */ 227 struct GNUNET_DATASTORE_QueueEntry * 228 GNUNET_DATASTORE_remove (struct GNUNET_DATASTORE_Handle *h, 229 const struct GNUNET_HashCode *key, 230 size_t size, 231 const void *data, 232 unsigned int queue_priority, 233 unsigned int max_queue_size, 234 GNUNET_DATASTORE_ContinuationWithStatus cont, 235 void *cont_cls); 236 237 238 /** 239 * Process a datum that was stored in the datastore. 240 * 241 * @param cls closure 242 * @param key key for the content 243 * @param size number of bytes in data 244 * @param data content stored 245 * @param type type of the content 246 * @param priority priority of the content 247 * @param anonymity anonymity-level for the content 248 * @param replication how often should the content be replicated to other peers? 249 * @param expiration expiration time for the content 250 * @param uid unique identifier for the datum; 251 * maybe 0 if no unique identifier is available 252 */ 253 typedef void 254 (*GNUNET_DATASTORE_DatumProcessor) (void *cls, 255 const struct GNUNET_HashCode *key, 256 size_t size, 257 const void *data, 258 enum GNUNET_BLOCK_Type type, 259 uint32_t priority, 260 uint32_t anonymity, 261 uint32_t replication, 262 struct GNUNET_TIME_Absolute expiration, 263 uint64_t uid); 264 265 266 /** 267 * Get a result for a particular key from the datastore. The processor 268 * will only be called once. 269 * 270 * @param h handle to the datastore 271 * @param next_uid return the result with lowest uid >= next_uid 272 * @param random if true, return a random result instead of using next_uid 273 * @param key maybe NULL (to match all entries) 274 * @param type desired type, 0 for any 275 * @param queue_priority ranking of this request in the priority queue 276 * @param max_queue_size at what queue size should this request be dropped 277 * (if other requests of higher priority are in the queue) 278 * @param proc function to call on a matching value; 279 * or with a NULL value if no datum matches 280 * @param proc_cls closure for @a proc 281 * @return NULL if the entry was not queued, otherwise a handle that can be used to 282 * cancel 283 */ 284 struct GNUNET_DATASTORE_QueueEntry * 285 GNUNET_DATASTORE_get_key (struct GNUNET_DATASTORE_Handle *h, 286 uint64_t next_uid, 287 bool random, 288 const struct GNUNET_HashCode *key, 289 enum GNUNET_BLOCK_Type type, 290 unsigned int queue_priority, 291 unsigned int max_queue_size, 292 GNUNET_DATASTORE_DatumProcessor proc, 293 void *proc_cls); 294 295 296 /** 297 * Get a single zero-anonymity value from the datastore. 298 * 299 * @param h handle to the datastore 300 * @param next_uid return the result with lowest uid >= next_uid 301 * @param queue_priority ranking of this request in the priority queue 302 * @param max_queue_size at what queue size should this request be dropped 303 * (if other requests of higher priority are in the queue) 304 * @param type allowed type for the operation (never zero) 305 * @param proc function to call on a random value; it 306 * will be called once with a value (if available) 307 * or with NULL if none value exists. 308 * @param proc_cls closure for proc 309 * @return NULL if the entry was not queued, otherwise a handle that can be used to 310 * cancel 311 */ 312 struct GNUNET_DATASTORE_QueueEntry * 313 GNUNET_DATASTORE_get_zero_anonymity (struct GNUNET_DATASTORE_Handle *h, 314 uint64_t next_uid, 315 unsigned int queue_priority, 316 unsigned int max_queue_size, 317 enum GNUNET_BLOCK_Type type, 318 GNUNET_DATASTORE_DatumProcessor proc, 319 void *proc_cls); 320 321 322 /** 323 * Get a random value from the datastore for content replication. 324 * Returns a single, random value among those with the highest 325 * replication score, lowering positive replication scores by one for 326 * the chosen value (if only content with a replication score exists, 327 * a random value is returned and replication scores are not changed). 328 * 329 * @param h handle to the datastore 330 * @param queue_priority ranking of this request in the priority queue 331 * @param max_queue_size at what queue size should this request be dropped 332 * (if other requests of higher priority are in the queue) 333 * @param proc function to call on a random value; it 334 * will be called once with a value (if available) 335 * and always once with a value of NULL. 336 * @param proc_cls closure for @a proc 337 * @return NULL if the entry was not queued, otherwise a handle that can be used to 338 * cancel 339 */ 340 struct GNUNET_DATASTORE_QueueEntry * 341 GNUNET_DATASTORE_get_for_replication (struct GNUNET_DATASTORE_Handle *h, 342 unsigned int queue_priority, 343 unsigned int max_queue_size, 344 GNUNET_DATASTORE_DatumProcessor proc, 345 void *proc_cls); 346 347 348 /** 349 * Cancel a datastore operation. The final callback from the 350 * operation must not have been done yet. 351 * 352 * @param qe operation to cancel 353 */ 354 void 355 GNUNET_DATASTORE_cancel (struct GNUNET_DATASTORE_QueueEntry *qe); 356 357 358 #if 0 /* keep Emacsens' auto-indent happy */ 359 { 360 #endif 361 #ifdef __cplusplus 362 } 363 #endif 364 365 #endif 366 367 /** @} */ /* end of group */ 368 369 /** @} */ /* end of group addition */