2 This file is part of GNUnet
3 (C) 2004, 2005, 2006, 2007, 2009 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your
8 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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file datastore/datastore_api.c
23 * @brief Management for the datastore for files stored on a GNUnet node
24 * @author Christian Grothoff
27 * 1) clarify API (wrt. efficient UPDATE of priority/expiration after GET)
32 * 7) implement GET_RANDOM
37 #include "gnunet_datastore_service.h"
38 #include "datastore.h"
44 * This is a linked list.
46 struct MessageQueue *next;
49 * Message we will transmit (allocated at the end
50 * of this struct; do not free!).
52 struct GNUNET_MessageHeader *msg;
55 * Function to call on the response.
57 GNUNET_CLIENT_MessageHandler response_processor;
60 * Closure for response_processor.
62 void *response_processor_cls;
68 * Handle to the datastore service.
70 struct GNUNET_DATASTORE_Handle
74 * Current connection to the datastore service.
76 struct GNUNET_CLIENT_Connection *client;
79 * Linked list of messages waiting to be transmitted.
81 struct MessageQueue *messages;
84 * Current response processor (NULL if we are not waiting
85 * for a response). Largely used only to know if we have
86 * a 'receive' request pending.
88 GNUNET_CLIENT_MessageHandler response_proc;
91 * Closure for response_proc.
93 void *response_proc_cls;
99 * Connect to the datastore service.
101 * @param cfg configuration to use
102 * @param sched scheduler to use
103 * @return handle to use to access the service
105 struct GNUNET_DATASTORE_Handle *GNUNET_DATASTORE_connect (struct
106 GNUNET_CONFIGURATION_Handle
109 GNUNET_SCHEDULER_Handle
112 struct GNUNET_CLIENT_Connection *c;
113 struct GNUNET_DATASTORE_Handle *h;
115 c = GNUNET_CLIENT_connect (sched, "datastore", cfg);
117 return NULL; /* oops */
118 h = GNUNET_malloc (sizeof(struct GNUNET_DATASTORE_Handle));
125 * Disconnect from the datastore service (and free
126 * associated resources).
128 * @param h handle to the datastore
129 * @param drop set to GNUNET_YES to delete all data in datastore (!)
131 void GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h,
134 if (GNUNET_YES == drop)
136 /* FIXME: send 'drop' request */
138 GNUNET_CLIENT_disconnect (h->client);
144 * Store an item in the datastore. If the item is already present,
145 * the priorities are summed up and the higher expiration time and
146 * lower anonymity level is used.
148 * @param h handle to the datastore
149 * @param key key for the value
150 * @param size number of bytes in data
151 * @param data content stored
152 * @param type type of the content
153 * @param priority priority of the content
154 * @param anonymity anonymity-level for the content
155 * @param expiration expiration time for the content
156 * @param cont continuation to call when done
157 * @param cont_cls closure for cont
160 GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h,
162 const GNUNET_HashCode * key,
168 struct GNUNET_TIME_Absolute expiration,
169 GNUNET_DATASTORE_ContinuationWithStatus cont,
172 cont (cont_cls, GNUNET_SYSERR, "not implemented");
177 * Reserve space in the datastore. This function should be used
178 * to avoid "out of space" failures during a longer sequence of "put"
179 * operations (for example, when a file is being inserted).
181 * @param h handle to the datastore
182 * @param amount how much space (in bytes) should be reserved (for content only)
183 * @param entries how many entries will be created (to calculate per-entry overhead)
184 * @param cont continuation to call when done; "success" will be set to
185 * a positive reservation value if space could be reserved.
186 * @param cont_cls closure for cont
189 GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h,
192 GNUNET_DATASTORE_ContinuationWithStatus cont,
195 cont (cont_cls, GNUNET_SYSERR, "not implemented");
200 * Signal that all of the data for which a reservation was made has
201 * been stored and that whatever excess space might have been reserved
202 * can now be released.
204 * @param h handle to the datastore
205 * @param rid reservation ID (value of "success" in original continuation
206 * from the "reserve" function).
207 * @param cont continuation to call when done
208 * @param cont_cls closure for cont
211 GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h,
213 GNUNET_DATASTORE_ContinuationWithStatus cont,
216 cont (cont_cls, GNUNET_OK, NULL);
221 * Update a value in the datastore.
223 * @param h handle to the datastore
224 * @param uid identifier for the value
225 * @param priority how much to increase the priority of the value
226 * @param expiration new expiration value should be MAX of existing and this argument
227 * @param cont continuation to call when done
228 * @param cont_cls closure for cont
231 GNUNET_DATASTORE_update (struct GNUNET_DATASTORE_Handle *h,
232 unsigned long long uid,
234 struct GNUNET_TIME_Absolute expiration,
235 GNUNET_DATASTORE_ContinuationWithStatus cont,
238 cont (cont_cls, GNUNET_SYSERR, "not implemented");
243 * Iterate over the results for a particular key
246 * @param h handle to the datastore
247 * @param key maybe NULL (to match all entries)
248 * @param type desired type, 0 for any
249 * @param iter function to call on each matching value;
250 * will be called once with a NULL value at the end
251 * @param iter_cls closure for iter
254 GNUNET_DATASTORE_get (struct GNUNET_DATASTORE_Handle *h,
255 const GNUNET_HashCode * key,
257 GNUNET_DATASTORE_Iterator iter, void *iter_cls)
259 static struct GNUNET_TIME_Absolute zero;
261 NULL, 0, NULL, 0, 0, 0, zero, 0);
266 * Get a random value from the datastore.
268 * @param h handle to the datastore
269 * @param iter function to call on a random value; it
270 * will be called exactly once; if no values
271 * are available, the value will be NULL.
272 * @param iter_cls closure for iter
275 GNUNET_DATASTORE_get_random (struct GNUNET_DATASTORE_Handle *h,
276 GNUNET_DATASTORE_Iterator iter, void *iter_cls)
278 static struct GNUNET_TIME_Absolute zero;
281 NULL, 0, NULL, 0, 0, 0, zero, 0);
286 * Explicitly remove some content from the database.
288 * @param h handle to the datastore
289 * @param key key for the value
290 * @param size number of bytes in data
291 * @param data content stored
292 * @param cont continuation to call when done
293 * @param cont_cls closure for cont
296 GNUNET_DATASTORE_remove (struct GNUNET_DATASTORE_Handle *h,
297 const GNUNET_HashCode * key,
298 uint32_t size, const void *data,
299 GNUNET_DATASTORE_ContinuationWithStatus cont,
302 cont (cont_cls, GNUNET_SYSERR, "not implemented");
306 /* end of datastore_api.c */