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
  27 #include "platform.h"
  28 #include "gnunet_datastore_service.h"
  29 #include "datastore.h"
  30
  31
  32 struct MessageQueue
  33 {
  34   /**
  35    * This is a linked list.
  36    */
  37   struct MessageQueue *next;
  38
  39   /**
  40    * Message we will transmit (allocated at the end
  41    * of this struct; do not free!).
  42    */
  43   struct GNUNET_MessageHeader *msg;
  44
  45   /**
  46    * Function to call on the response.
  47    */
  48   GNUNET_CLIENT_MessageHandler response_processor;
  49
  50   /**
  51    * Closure for response_processor.
  52    */
  53   void *response_processor_cls;
  54
  55 };
  56
  57
  58 /**
  59  * Handle to the datastore service.
  60  */
  61 struct GNUNET_DATASTORE_Handle
  62 {
  63
  64   /**
  65    * Current connection to the datastore service.
  66    */
  67   struct GNUNET_CLIENT_Connection *client;
  68
  69   /**
  70    * Linked list of messages waiting to be transmitted.
  71    */
  72   struct MessageQueue *messages;
  73
  74   /**
  75    * Current response processor (NULL if we are not waiting
  76    * for a response).  Largely used only to know if we have
  77    * a 'receive' request pending.
  78    */
  79   GNUNET_CLIENT_MessageHandler response_proc;
  80
  81   /**
  82    * Closure for response_proc.
  83    */
  84   void *response_proc_cls;
  85
  86 };
  87
  88
  89 /**
  90  * Connect to the datastore service.
  91  *
  92  * @param cfg configuration to use
  93  * @param sched scheduler to use
  94  * @return handle to use to access the service
  95  */
  96 struct GNUNET_DATASTORE_Handle *GNUNET_DATASTORE_connect (struct
  97                                                           GNUNET_CONFIGURATION_Handle
  98                                                           *cfg,
  99                                                           struct
 100                                                           GNUNET_SCHEDULER_Handle
 101                                                           *sched)
 102 {
 103   struct GNUNET_CLIENT_Connection *c;
 104   struct GNUNET_DATASTORE_Handle *h;
 105
 106   c = GNUNET_CLIENT_connect (sched, "datastore", cfg);
 107   if (c == NULL)
 108     return NULL; /* oops */
 109   h = GNUNET_malloc (sizeof(struct GNUNET_DATASTORE_Handle));
 110   h->client = c;
 111   return h;
 112 }
 113
 114
 115 /**
 116  * Disconnect from the datastore service (and free
 117  * associated resources).
 118  *
 119  * @param h handle to the datastore
 120  * @param drop set to GNUNET_YES to delete all data in datastore (!)
 121  */
 122 void GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h,
 123                                   int drop)
 124 {
 125   if (GNUNET_YES == drop)
 126     {
 127       /* FIXME: send 'drop' request */
 128     }
 129   GNUNET_CLIENT_disconnect (h->client);
 130   GNUNET_free (h);
 131 }
 132
 133
 134 /**
 135  * Store an item in the datastore.  If the item is already present,
 136  * the priorities are summed up and the higher expiration time and
 137  * lower anonymity level is used.
 138  *
 139  * @param h handle to the datastore
 140  * @param key key for the value
 141  * @param size number of bytes in data
 142  * @param data content stored
 143  * @param type type of the content
 144  * @param priority priority of the content
 145  * @param anonymity anonymity-level for the content
 146  * @param expiration expiration time for the content
 147  * @param cont continuation to call when done
 148  * @param cont_cls closure for cont
 149  */
 150 void
 151 GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h,
 152                       int rid,
 153                       const GNUNET_HashCode * key,
 154                       uint32_t size,
 155                       const void *data,
 156                       uint32_t type,
 157                       uint32_t priority,
 158                       uint32_t anonymity,
 159                       struct GNUNET_TIME_Absolute expiration,
 160                       GNUNET_DATASTORE_ContinuationWithStatus cont,
 161                       void *cont_cls)
 162 {
 163   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 164 }
 165
 166
 167 /**
 168  * Reserve space in the datastore.  This function should be used
 169  * to avoid "out of space" failures during a longer sequence of "put"
 170  * operations (for example, when a file is being inserted).
 171  *
 172  * @param h handle to the datastore
 173  * @param amount how much space (in bytes) should be reserved (for content only)
 174  * @param entries how many entries will be created (to calculate per-entry overhead)
 175  * @param cont continuation to call when done; "success" will be set to
 176  *             a positive reservation value if space could be reserved.
 177  * @param cont_cls closure for cont
 178  */
 179 void
 180 GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h,
 181                           uint64_t amount,
 182                           uint64_t entries,
 183                           GNUNET_DATASTORE_ContinuationWithStatus cont,
 184                           void *cont_cls)
 185 {
 186   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 187 }
 188
 189
 190 /**
 191  * Signal that all of the data for which a reservation was made has
 192  * been stored and that whatever excess space might have been reserved
 193  * can now be released.
 194  *
 195  * @param h handle to the datastore
 196  * @param rid reservation ID (value of "success" in original continuation
 197  *        from the "reserve" function).
 198  * @param cont continuation to call when done
 199  * @param cont_cls closure for cont
 200  */
 201 void
 202 GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h,
 203                                   int rid,
 204                                   GNUNET_DATASTORE_ContinuationWithStatus cont,
 205                                   void *cont_cls)
 206 {
 207   cont (cont_cls, GNUNET_OK, NULL);
 208 }
 209
 210
 211 /**
 212  * Update a value in the datastore.
 213  *
 214  * @param h handle to the datastore
 215  * @param uid identifier for the value
 216  * @param priority how much to increase the priority of the value
 217  * @param expiration new expiration value should be MAX of existing and this argument
 218  * @param cont continuation to call when done
 219  * @param cont_cls closure for cont
 220  */
 221 void
 222 GNUNET_DATASTORE_update (struct GNUNET_DATASTORE_Handle *h,
 223                          unsigned long long uid,
 224                          uint32_t priority,
 225                          struct GNUNET_TIME_Absolute expiration,
 226                          GNUNET_DATASTORE_ContinuationWithStatus cont,
 227                          void *cont_cls)
 228 {
 229   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 230 }
 231
 232
 233 /**
 234  * Iterate over the results for a particular key
 235  * in the datastore.
 236  *
 237  * @param h handle to the datastore
 238  * @param key maybe NULL (to match all entries)
 239  * @param type desired type, 0 for any
 240  * @param iter function to call on each matching value;
 241  *        will be called once with a NULL value at the end
 242  * @param iter_cls closure for iter
 243  */
 244 void
 245 GNUNET_DATASTORE_get (struct GNUNET_DATASTORE_Handle *h,
 246                       const GNUNET_HashCode * key,
 247                       uint32_t type,
 248                       GNUNET_DATASTORE_Iterator iter, void *iter_cls)
 249 {
 250   static struct GNUNET_TIME_Absolute zero;
 251   iter (iter_cls,
 252         NULL, 0, NULL, 0, 0, 0, zero, 0);
 253 }
 254
 255
 256 /**
 257  * Get a random value from the datastore.
 258  *
 259  * @param h handle to the datastore
 260  * @param iter function to call on a random value; it
 261  *        will be called exactly once; if no values
 262  *        are available, the value will be NULL.
 263  * @param iter_cls closure for iter
 264  */
 265 void
 266 GNUNET_DATASTORE_get_random (struct GNUNET_DATASTORE_Handle *h,
 267                              GNUNET_DATASTORE_Iterator iter, void *iter_cls)
 268 {
 269   static struct GNUNET_TIME_Absolute zero;
 270
 271   iter (iter_cls,
 272         NULL, 0, NULL, 0, 0, 0, zero, 0);
 273 }
 274
 275
 276 /**
 277  * Explicitly remove some content from the database.
 278  *
 279  * @param h handle to the datastore
 280  * @param key key for the value
 281  * @param size number of bytes in data
 282  * @param data content stored
 283  * @param cont continuation to call when done
 284  * @param cont_cls closure for cont
 285  */
 286 void
 287 GNUNET_DATASTORE_remove (struct GNUNET_DATASTORE_Handle *h,
 288                          const GNUNET_HashCode * key,
 289                          uint32_t size, const void *data,
 290                          GNUNET_DATASTORE_ContinuationWithStatus cont,
 291                          void *cont_cls)
 292 {
 293   cont (cont_cls, GNUNET_SYSERR, "not implemented");
 294 }
 295
 296
 297 /* end of datastore_api.c */