src/dht/gnunet-service-dht_datacache.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009, 2010, 2011 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      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/>.
  17 */
  18
  19 /**
  20  * @file dht/gnunet-service-dht_datacache.h
  21  * @brief GNUnet DHT service's datacache integration
  22  * @author Christian Grothoff
  23  * @author Nathan Evans
  24  */
  25 #ifndef GNUNET_SERVICE_DHT_DATACACHE_H
  26 #define GNUNET_SERVICE_DHT_DATACACHE_H
  27
  28 #include "gnunet_util_lib.h"
  29 #include "gnunet_block_lib.h"
  30 #include "gnunet_dht_service.h"
  31
  32 /**
  33  * Handle a datum we've received from another peer.  Cache if
  34  * possible.
  35  *
  36  * @param expiration when will the reply expire
  37  * @param key the query this reply is for
  38  * @param put_path_length number of peers in 'put_path'
  39  * @param put_path path the reply took on put
  40  * @param type type of the reply
  41  * @param data_size number of bytes in 'data'
  42  * @param data application payload data
  43  */
  44 void
  45 GDS_DATACACHE_handle_put (struct GNUNET_TIME_Absolute expiration,
  46                           const struct GNUNET_HashCode *key,
  47                           unsigned int put_path_length,
  48                           const struct GNUNET_PeerIdentity *put_path,
  49                           enum GNUNET_BLOCK_Type type,
  50                           size_t data_size,
  51                           const void *data);
  52
  53
  54 /**
  55  * Handle a result for a GET operation.
  56  *
  57  * @param cls closure
  58  * @param type type of the block
  59  * @param expiration_time when does the content expire
  60  * @param key key for the content
  61  * @param put_path_length number of entries in @a put_path
  62  * @param put_path peers the original PUT traversed (if tracked)
  63  * @param get_path_length number of entries in @a get_path
  64  * @param get_path peers this reply has traversed so far (if tracked)
  65  * @param data payload of the reply
  66  * @param data_size number of bytes in @a data
  67  */
  68 typedef void
  69 (*GDS_DATACACHE_GetCallback)(void *cls,
  70                              enum GNUNET_BLOCK_Type type,
  71                              struct GNUNET_TIME_Absolute expiration_time,
  72                              const struct GNUNET_HashCode *key,
  73                              unsigned int put_path_length,
  74                              const struct GNUNET_PeerIdentity *put_path,
  75                              unsigned int get_path_length,
  76                              const struct GNUNET_PeerIdentity *get_path,
  77                              const void *data,
  78                              size_t data_size);
  79
  80
  81 /**
  82  * Handle a GET request we've received from another peer.
  83  *
  84  * @param key the query
  85  * @param type requested data type
  86  * @param xquery extended query
  87  * @param xquery_size number of bytes in xquery
  88  * @param bg block group to use for evaluation of replies
  89  * @param gc function to call on the results
  90  * @param gc_cls closure for @a gc
  91  * @return evaluation result for the local replies
  92  */
  93 enum GNUNET_BLOCK_EvaluationResult
  94 GDS_DATACACHE_handle_get (const struct GNUNET_HashCode *key,
  95                           enum GNUNET_BLOCK_Type type,
  96                           const void *xquery,
  97                           size_t xquery_size,
  98                           struct GNUNET_BLOCK_Group *bg,
  99                           GDS_DATACACHE_GetCallback gc,
 100                           void *gc_cls);
 101
 102
 103 /**
 104  * Obtain a random key from the datacache.
 105  * Used by Whanau for load-balancing.
 106  *
 107  * @param[out] key where to store the key of a random element,
 108  *             randomized by PRNG if datacache is empty
 109  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the datacache is empty
 110  */
 111 int
 112 GDS_DATACACHE_get_random_key (struct GNUNET_HashCode *key);
 113
 114
 115 /**
 116  * Send the get result to requesting client.
 117  *
 118  * @param cls closure
 119  * @param options routing options (from GET request)
 120  * @param key key of the requested data.
 121  * @param type block type
 122  * @param put_path_length number of peers in @a put_path
 123  * @param put_path path taken to put the data at its stored location.
 124  * @param expiration when will this result expire?
 125  * @param data payload to store
 126  * @param data_size size of the @a data
 127  */
 128 typedef void
 129 (*GDS_DATACACHE_SuccessorCallback)(void *cls,
 130                                    enum GNUNET_DHT_RouteOption options,
 131                                    const struct GNUNET_HashCode *key,
 132                                    enum GNUNET_BLOCK_Type type,
 133                                    unsigned int put_path_length,
 134                                    const struct GNUNET_PeerIdentity *put_path,
 135                                    struct GNUNET_TIME_Absolute expiration,
 136                                    const void *data,
 137                                    size_t data_size);
 138
 139
 140 /**
 141  * Handle a request for data close to a key that we have received from
 142  * another peer.
 143  *
 144  * @param key the location at which the peer is looking for data that is close
 145  * @param cb function to call with the result
 146  * @param cb_cls closure for @a cb
 147  */
 148 void
 149 GDS_DATACACHE_get_successors (const struct GNUNET_HashCode *key,
 150                               GDS_DATACACHE_SuccessorCallback cb,
 151                               void *cb_cls);
 152
 153
 154 /**
 155  * Initialize datacache subsystem.
 156  */
 157 void
 158 GDS_DATACACHE_init (void);
 159
 160
 161 /**
 162  * Shutdown datacache subsystem.
 163  */
 164 void
 165 GDS_DATACACHE_done (void);
 166
 167 #endif