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