2 This file is part of GNUnet
3 Copyright (C) 2004, 2005, 2006, 2007, 2009, 2010, 2011 GNUnet e.V.
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.
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.
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/>.
20 * @author Christian Grothoff
25 * @defgroup datastore Data Store service
26 * Data store for files stored on a GNUnet node.
28 * Provides an API that can be used manage the
29 * datastore for files stored on a GNUnet node.
30 * Note that the datastore is NOT responsible for
31 * on-demand encoding, that is achieved using
32 * a special kind of entry.
37 #ifndef GNUNET_DATASTORE_SERVICE_H
38 #define GNUNET_DATASTORE_SERVICE_H
40 #include "gnunet_util_lib.h"
41 #include "gnunet_block_lib.h"
46 #if 0 /* keep Emacsens' auto-indent happy */
54 struct GNUNET_DATASTORE_QueueEntry;
57 * Handle to the datastore service.
59 struct GNUNET_DATASTORE_Handle;
62 * Maximum size of a value that can be stored in the datastore.
64 #define GNUNET_DATASTORE_MAX_VALUE_SIZE 65536
67 * Connect to the datastore service.
69 * @param cfg configuration to use
70 * @return handle to use to access the service
72 struct GNUNET_DATASTORE_Handle *
73 GNUNET_DATASTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
77 * Disconnect from the datastore service (and free
78 * associated resources).
80 * @param h handle to the datastore
81 * @param drop set to #GNUNET_YES to delete all data in datastore (!)
84 GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h,
89 * Continuation called to notify client about result of the
93 * @param success #GNUNET_SYSERR on failure
94 * #GNUNET_NO if content was already there
95 * #GNUNET_YES (or other positive value) on success
96 * @param min_expiration minimum expiration time required for 0-priority content to be stored
97 * by the datacache at this time, zero for unknown, forever if we have no
98 * space for 0-priority content
99 * @param msg NULL on success, otherwise an error message
102 (*GNUNET_DATASTORE_ContinuationWithStatus) (void *cls,
104 struct GNUNET_TIME_Absolute min_expiration,
109 * Reserve space in the datastore. This function should be used
110 * to avoid "out of space" failures during a longer sequence of "put"
111 * operations (for example, when a file is being inserted).
113 * @param h handle to the datastore
114 * @param amount how much space (in bytes) should be reserved (for content only)
115 * @param entries how many entries will be created (to calculate per-entry overhead)
116 * @param cont continuation to call when done; "success" will be set to
117 * a positive reservation value if space could be reserved.
118 * @param cont_cls closure for @a cont
119 * @return NULL if the entry was not queued, otherwise a handle that can be used to
120 * cancel; note that even if NULL is returned, the callback will be invoked
121 * (or rather, will already have been invoked)
123 struct GNUNET_DATASTORE_QueueEntry *
124 GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h,
127 GNUNET_DATASTORE_ContinuationWithStatus cont,
132 * Store an item in the datastore. If the item is already present,
133 * the priorities and replication values are summed up and the higher
134 * expiration time and lower anonymity level is used.
136 * @param h handle to the datastore
137 * @param rid reservation ID to use (from "reserve"); use 0 if no
138 * prior reservation was made
139 * @param key key for the value
140 * @param size number of bytes in data
141 * @param data content stored
142 * @param type type of the content
143 * @param priority priority of the content
144 * @param anonymity anonymity-level for the content
145 * @param replication how often should the content be replicated to other peers?
146 * @param expiration expiration time for the content
147 * @param queue_priority ranking of this request in the priority queue
148 * @param max_queue_size at what queue size should this request be dropped
149 * (if other requests of higher priority are in the queue)
150 * @param cont continuation to call when done
151 * @param cont_cls closure for @a cont
152 * @return NULL if the entry was not queued, otherwise a handle that can be used to
153 * cancel; note that even if NULL is returned, the callback will be invoked
154 * (or rather, will already have been invoked)
156 struct GNUNET_DATASTORE_QueueEntry *
157 GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h,
159 const struct GNUNET_HashCode *key,
162 enum GNUNET_BLOCK_Type type,
165 uint32_t replication,
166 struct GNUNET_TIME_Absolute expiration,
167 unsigned int queue_priority,
168 unsigned int max_queue_size,
169 GNUNET_DATASTORE_ContinuationWithStatus cont,
174 * Signal that all of the data for which a reservation was made has
175 * been stored and that whatever excess space might have been reserved
176 * can now be released.
178 * @param h handle to the datastore
179 * @param rid reservation ID (value of "success" in original continuation
180 * from the "reserve" function).
181 * @param queue_priority ranking of this request in the priority queue
182 * @param max_queue_size at what queue size should this request be dropped
183 * (if other requests of higher priority are in the queue)
184 * @param queue_priority ranking of this request in the priority queue
185 * @param max_queue_size at what queue size should this request be dropped
186 * (if other requests of higher priority are in the queue)
187 * @param cont continuation to call when done
188 * @param cont_cls closure for @a cont
189 * @return NULL if the entry was not queued, otherwise a handle that can be used to
190 * cancel; note that even if NULL is returned, the callback will be invoked
191 * (or rather, will already have been invoked)
193 struct GNUNET_DATASTORE_QueueEntry *
194 GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h,
195 uint32_t rid, unsigned int queue_priority,
196 unsigned int max_queue_size,
197 GNUNET_DATASTORE_ContinuationWithStatus cont,
202 * Explicitly remove some content from the database. @a cont will be
203 * called with status #GNUNET_OK if content was removed, #GNUNET_NO if
204 * no matching entry was found and #GNUNET_SYSERR on all other types
207 * @param h handle to the datastore
208 * @param key key for the value
209 * @param size number of bytes in @a data
210 * @param data content stored
211 * @param queue_priority ranking of this request in the priority queue
212 * @param max_queue_size at what queue size should this request be dropped
213 * (if other requests of higher priority are in the queue)
214 * @param cont continuation to call when done
215 * @param cont_cls closure for @a cont
216 * @return NULL if the entry was not queued, otherwise a handle that can be used to
217 * cancel; note that even if NULL is returned, the callback will be invoked
218 * (or rather, will already have been invoked)
220 struct GNUNET_DATASTORE_QueueEntry *
221 GNUNET_DATASTORE_remove (struct GNUNET_DATASTORE_Handle *h,
222 const struct GNUNET_HashCode *key,
225 unsigned int queue_priority,
226 unsigned int max_queue_size,
227 GNUNET_DATASTORE_ContinuationWithStatus cont,
232 * Process a datum that was stored in the datastore.
235 * @param key key for the content
236 * @param size number of bytes in data
237 * @param data content stored
238 * @param type type of the content
239 * @param priority priority of the content
240 * @param anonymity anonymity-level for the content
241 * @param replication how often should the content be replicated to other peers?
242 * @param expiration expiration time for the content
243 * @param uid unique identifier for the datum;
244 * maybe 0 if no unique identifier is available
247 (*GNUNET_DATASTORE_DatumProcessor) (void *cls,
248 const struct GNUNET_HashCode *key,
251 enum GNUNET_BLOCK_Type type,
254 uint32_t replication,
255 struct GNUNET_TIME_Absolute expiration,
260 * Get a result for a particular key from the datastore. The processor
261 * will only be called once.
263 * @param h handle to the datastore
264 * @param next_uid return the result with lowest uid >= next_uid
265 * @param random if true, return a random result instead of using next_uid
266 * @param key maybe NULL (to match all entries)
267 * @param type desired type, 0 for any
268 * @param queue_priority ranking of this request in the priority queue
269 * @param max_queue_size at what queue size should this request be dropped
270 * (if other requests of higher priority are in the queue)
271 * @param proc function to call on a matching value;
272 * or with a NULL value if no datum matches
273 * @param proc_cls closure for @a proc
274 * @return NULL if the entry was not queued, otherwise a handle that can be used to
277 struct GNUNET_DATASTORE_QueueEntry *
278 GNUNET_DATASTORE_get_key (struct GNUNET_DATASTORE_Handle *h,
281 const struct GNUNET_HashCode *key,
282 enum GNUNET_BLOCK_Type type,
283 unsigned int queue_priority,
284 unsigned int max_queue_size,
285 GNUNET_DATASTORE_DatumProcessor proc,
290 * Get a single zero-anonymity value from the datastore.
292 * @param h handle to the datastore
293 * @param next_uid return the result with lowest uid >= next_uid
294 * @param queue_priority ranking of this request in the priority queue
295 * @param max_queue_size at what queue size should this request be dropped
296 * (if other requests of higher priority are in the queue)
297 * @param type allowed type for the operation (never zero)
298 * @param proc function to call on a random value; it
299 * will be called once with a value (if available)
300 * or with NULL if none value exists.
301 * @param proc_cls closure for proc
302 * @return NULL if the entry was not queued, otherwise a handle that can be used to
305 struct GNUNET_DATASTORE_QueueEntry *
306 GNUNET_DATASTORE_get_zero_anonymity (struct GNUNET_DATASTORE_Handle *h,
308 unsigned int queue_priority,
309 unsigned int max_queue_size,
310 enum GNUNET_BLOCK_Type type,
311 GNUNET_DATASTORE_DatumProcessor proc,
316 * Get a random value from the datastore for content replication.
317 * Returns a single, random value among those with the highest
318 * replication score, lowering positive replication scores by one for
319 * the chosen value (if only content with a replication score exists,
320 * a random value is returned and replication scores are not changed).
322 * @param h handle to the datastore
323 * @param queue_priority ranking of this request in the priority queue
324 * @param max_queue_size at what queue size should this request be dropped
325 * (if other requests of higher priority are in the queue)
326 * @param proc function to call on a random value; it
327 * will be called once with a value (if available)
328 * and always once with a value of NULL.
329 * @param proc_cls closure for @a proc
330 * @return NULL if the entry was not queued, otherwise a handle that can be used to
333 struct GNUNET_DATASTORE_QueueEntry *
334 GNUNET_DATASTORE_get_for_replication (struct GNUNET_DATASTORE_Handle *h,
335 unsigned int queue_priority,
336 unsigned int max_queue_size,
337 GNUNET_DATASTORE_DatumProcessor proc,
343 * Cancel a datastore operation. The final callback from the
344 * operation must not have been done yet.
346 * @param qe operation to cancel
349 GNUNET_DATASTORE_cancel (struct GNUNET_DATASTORE_QueueEntry *qe);
352 #if 0 /* keep Emacsens' auto-indent happy */
361 /** @} */ /* end of group */