src/include/gnunet_datacache_lib.h

   1 /*
   2      This file is part of GNUnet
   3      Copyright (C) 2006, 2009, 2015 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
  16 /**
  17  * @author Christian Grothoff
  18  *
  19  * @file
  20  * datacache API
  21  *
  22  * @defgroup datacache  Data Cache library
  23  * Simple, transient hash table of bounded size with content expiration.
  24  *
  25  * In contrast to the sqstore there is
  26  * no prioritization, deletion or iteration.
  27  * All of the data is discarded when the peer shuts down!
  28  *
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_DATACACHE_LIB_H
  33 #define GNUNET_DATACACHE_LIB_H
  34
  35 #include "gnunet_util_lib.h"
  36 #include "gnunet_block_lib.h"
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46
  47 /**
  48  * Handle to the cache.
  49  */
  50 struct GNUNET_DATACACHE_Handle;
  51
  52
  53 /**
  54  * Create a data cache.
  55  *
  56  * @param cfg configuration to use
  57  * @param section section in the configuration that contains our options
  58  * @return handle to use to access the service
  59  */
  60 struct GNUNET_DATACACHE_Handle *
  61 GNUNET_DATACACHE_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
  62                          const char *section);
  63
  64
  65 /**
  66  * Destroy a data cache (and free associated resources).
  67  *
  68  * @param h handle to the datastore
  69  */
  70 void
  71 GNUNET_DATACACHE_destroy (struct GNUNET_DATACACHE_Handle *h);
  72
  73
  74 /**
  75  * An iterator over a set of items stored in the datacache.
  76  *
  77  * @param cls closure
  78  * @param key key for the content
  79  * @param data_size number of bytes in @a data
  80  * @param data content stored
  81  * @param type type of the content
  82  * @param exp when will the content expire?
  83  * @param path_info_len number of entries in @a path_info
  84  * @param path_info a path through the network
  85  * @return #GNUNET_OK to continue iterating, #GNUNET_SYSERR to abort
  86  */
  87 typedef int
  88 (*GNUNET_DATACACHE_Iterator) (void *cls,
  89                               const struct GNUNET_HashCode *key,
  90                               size_t data_size,
  91                               const char *data,
  92                               enum GNUNET_BLOCK_Type type,
  93                               struct GNUNET_TIME_Absolute exp,
  94                               unsigned int path_info_len,
  95                               const struct GNUNET_PeerIdentity *path_info);
  96
  97
  98 /**
  99  * Store an item in the datacache.
 100  *
 101  * @param h handle to the datacache
 102  * @param key key to store data under
 103  * @param how close is @a key to our pid?
 104  * @param data_size number of bytes in @a data
 105  * @param data data to store
 106  * @param type type of the value
 107  * @param discard_time when to discard the value in any case
 108  * @param path_info_len number of entries in @a path_info
 109  * @param path_info a path through the network
 110  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error, #GNUNET_NO if duplicate
 111  */
 112 int
 113 GNUNET_DATACACHE_put (struct GNUNET_DATACACHE_Handle *h,
 114                       const struct GNUNET_HashCode *key,
 115                       uint32_t xor_distance,
 116                       size_t data_size,
 117                       const char *data,
 118                       enum GNUNET_BLOCK_Type type,
 119                       struct GNUNET_TIME_Absolute discard_time,
 120                       unsigned int path_info_len,
 121                       const struct GNUNET_PeerIdentity *path_info);
 122
 123
 124 /**
 125  * Iterate over the results for a particular key
 126  * in the datacache.
 127  *
 128  * @param h handle to the datacache
 129  * @param key what to look up
 130  * @param type entries of which type are relevant?
 131  * @param iter maybe NULL (to just count)
 132  * @param iter_cls closure for @a iter
 133  * @return the number of results found
 134  */
 135 unsigned int
 136 GNUNET_DATACACHE_get (struct GNUNET_DATACACHE_Handle *h,
 137                       const struct GNUNET_HashCode *key,
 138                       enum GNUNET_BLOCK_Type type,
 139                       GNUNET_DATACACHE_Iterator iter,
 140                       void *iter_cls);
 141
 142
 143 /**
 144  * Obtain a random element from the datacache.
 145  *
 146  * @param h handle to the datacache
 147  * @param iter maybe NULL (to just count)
 148  * @param iter_cls closure for @a iter
 149  * @return the number of results found (zero or 1)
 150  */
 151 unsigned int
 152 GNUNET_DATACACHE_get_random (struct GNUNET_DATACACHE_Handle *h,
 153                              GNUNET_DATACACHE_Iterator iter,
 154                              void *iter_cls);
 155
 156
 157 /**
 158  * Iterate over the results that are "close" to a particular key in
 159  * the datacache.  "close" is defined as numerically larger than @a
 160  * key (when interpreted as a circular address space), with small
 161  * distance.
 162  *
 163  * @param h handle to the datacache
 164  * @param key area of the keyspace to look into
 165  * @param num_results number of results that should be returned to @a iter
 166  * @param iter maybe NULL (to just count)
 167  * @param iter_cls closure for @a iter
 168  * @return the number of results found
 169  */
 170 unsigned int
 171 GNUNET_DATACACHE_get_closest (struct GNUNET_DATACACHE_Handle *h,
 172                               const struct GNUNET_HashCode *key,
 173                               unsigned int num_results,
 174                               GNUNET_DATACACHE_Iterator iter,
 175                               void *iter_cls);
 176
 177
 178 #if 0                           /* keep Emacsens' auto-indent happy */
 179 {
 180 #endif
 181 #ifdef __cplusplus
 182 }
 183 #endif
 184
 185 #endif
 186
 187 /** @} */  /* end of group */