src/datastore/datastore_api.c

   1 /*
   2      This file is part of GNUnet
   3      (C) 2004, 2005, 2006, 2007, 2009 Christian Grothoff (and other contributing authors)
   4
   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.
   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      General Public License for more details.
  14
  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.
  19 */
  20
  21 /**
  22  * @file datastore/datastore_api.c
  23  * @brief Management for the datastore for files stored on a GNUnet node
  24  * @author Christian Grothoff
  25  *
  26  * TODO:
  27  * 1) clarify API (wrt. efficient UPDATE of priority/expiration after GET)
  28  * 2) implement INIT
  29  * 4) implement DROP
  30  * 5) implement PUT
  31  * 6) implement GET
  32  * 7) implement GET_RANDOM
  33  * 8) implement REMOVE
  34  */
  35
  36 #include "platform.h"
  37 #include "gnunet_datastore_service.h"
  38 #include "datastore.h"
  39
  40
  41 struct MessageQueue
  42 {
  43   /**
  44    * This is a linked list.
  45    */
  46   struct MessageQueue *next;
  47
  48   /**
  49    * Message we will transmit (allocated at the end
  50    * of this struct; do not free!).
  51    */
  52   struct GNUNET_MessageHeader *msg;
  53
  54   /**
  55    * Function to call on the response.
  56    */
  57   GNUNET_CLIENT_MessageHandler response_processor;
  58
  59   /**
  60    * Closure for response_processor.
  61    */
  62   void *response_processor_cls;
  63
  64 };
  65
  66
  67 /**
  68  * Handle to the datastore service.
  69  */
  70 struct GNUNET_DATASTORE_Handle
  71 {
  72
  73   /**
  74    * Current connection to the datastore service.
  75    */
  76   struct GNUNET_CLIENT_Connection *client;
  77
  78   /**
  79    * Linked list of messages waiting to be transmitted.
  80    */
  81   struct MessageQueue *messages;
  82
  83   /**
  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.
  87    */
  88   GNUNET_CLIENT_MessageHandler response_proc;
  89
  90   /**
  91    * Closure for response_proc.
  92    */
  93   void *response_proc_cls;
  94
  95 };
  96
  97
  98 /**
  99  * Connect to the datastore service.
 100  *
 101  * @param cfg configuration to use
 102  * @param sched scheduler to use
 103  * @return handle to use to access the service
 104  */
 105 struct GNUNET_DATASTORE_Handle *GNUNET_DATASTORE_connect (struct
 106                                                           GNUNET_CONFIGURATION_Handle
 107                                                           *cfg,
 108                                                           struct
 109                                                           GNUNET_SCHEDULER_Handle
 110                                                           *sched)
 111 {
 112   struct GNUNET_CLIENT_Connection *c;
 113   struct GNUNET_DATASTORE_Handle *h;
 114
 115   c = GNUNET_CLIENT_connect (sched, "datastore", cfg);
 116   if (c == NULL)
 117     return NULL; /* oops */
 118   h = GNUNET_malloc (sizeof(struct GNUNET_DATASTORE_Handle));
 119   h->client = c;
 120   return h;
 121 }
 122
 123
 124 /**
 125  * Disconnect from the datastore service (and free
 126  * associated resources).
 127  *
 128  * @param h handle to the datastore
 129  * @param drop set to GNUNET_YES to delete all data in datastore (!)
 130  */
 131 void GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h,
 132                                   int drop)
 133 {
 134   if (GNUNET_YES == drop)
 135     {
 136       /* FIXME: send 'drop' request */
 137     }
 138   GNUNET_CLIENT_disconnect (h->client);
 139   GNUNET_free (h);
 140 }
 141
 142
 143 /**
 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.
 147  *
 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
 158  */
 159 void
 160 GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h,
 161                       int rid,
 162                       const GNUNET_HashCode * key,
 163                       uint32_t size,
 164                       const void *data,
 165                       uint32_t type,
 166                       uint32_t priority,
 167                       uint32_t anonymity,
 168                       struct GNUNET_TIME_Absolute expiration,
 169                       GNUNET_DATASTORE_ContinuationWithStatus cont,
 170                       void *cont_cls)
 171 {
 172   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 173 }
 174
 175
 176 /**
 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).
 180  *
 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
 187  */
 188 void
 189 GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h,
 190                           uint64_t amount,
 191                           uint64_t entries,
 192                           GNUNET_DATASTORE_ContinuationWithStatus cont,
 193                           void *cont_cls)
 194 {
 195   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 196 }
 197
 198
 199 /**
 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.
 203  *
 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
 209  */
 210 void
 211 GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h,
 212                                   int rid,
 213                                   GNUNET_DATASTORE_ContinuationWithStatus cont,
 214                                   void *cont_cls)
 215 {
 216   cont (cont_cls, GNUNET_OK, NULL);
 217 }
 218
 219
 220 /**
 221  * Update a value in the datastore.
 222  *
 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
 229  */
 230 void
 231 GNUNET_DATASTORE_update (struct GNUNET_DATASTORE_Handle *h,
 232                          unsigned long long uid,
 233                          uint32_t priority,
 234                          struct GNUNET_TIME_Absolute expiration,
 235                          GNUNET_DATASTORE_ContinuationWithStatus cont,
 236                          void *cont_cls)
 237 {
 238   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 239 }
 240
 241
 242 /**
 243  * Iterate over the results for a particular key
 244  * in the datastore.
 245  *
 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
 252  */
 253 void
 254 GNUNET_DATASTORE_get (struct GNUNET_DATASTORE_Handle *h,
 255                       const GNUNET_HashCode * key,
 256                       uint32_t type,
 257                       GNUNET_DATASTORE_Iterator iter, void *iter_cls)
 258 {
 259   static struct GNUNET_TIME_Absolute zero;
 260   iter (iter_cls,
 261         NULL, 0, NULL, 0, 0, 0, zero, 0);
 262 }
 263
 264
 265 /**
 266  * Get a random value from the datastore.
 267  *
 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
 273  */
 274 void
 275 GNUNET_DATASTORE_get_random (struct GNUNET_DATASTORE_Handle *h,
 276                              GNUNET_DATASTORE_Iterator iter, void *iter_cls)
 277 {
 278   static struct GNUNET_TIME_Absolute zero;
 279
 280   iter (iter_cls,
 281         NULL, 0, NULL, 0, 0, 0, zero, 0);
 282 }
 283
 284
 285 /**
 286  * Explicitly remove some content from the database.
 287  *
 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
 294  */
 295 void
 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,
 300                          void *cont_cls)
 301 {
 302   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 303 }
 304
 305
 306 /* end of datastore_api.c */