new DHT API, tests do not yet compile
[oweals/gnunet.git] / src / include / gnunet_dht_service.h
1 /*
2       This file is part of GNUnet
3       (C) 2004, 2005, 2006, 2008, 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 3, 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 include/gnunet_dht_service.h
23  * @brief API to the DHT service
24  * @author Christian Grothoff
25  */
26
27 #ifndef GNUNET_DHT_SERVICE_H
28 #define GNUNET_DHT_SERVICE_H
29
30 #include "gnunet_util_lib.h"
31 #include "gnunet_block_lib.h"
32 #include "gnunet_hello_lib.h"
33
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #if 0                           /* keep Emacsens' auto-indent happy */
38 }
39 #endif
40 #endif
41
42
43 /**
44  * Connection to the DHT service.
45  */
46 struct GNUNET_DHT_Handle;
47
48 /**
49  * Handle to control a route operation.
50  */
51 struct GNUNET_DHT_RouteHandle;
52
53 /**
54  * Handle to control a get operation.
55  */
56 struct GNUNET_DHT_GetHandle;
57
58 /**
59  * Handle to control a find peer operation.
60  */
61 struct GNUNET_DHT_FindPeerHandle;
62
63
64 /**
65  * Options for routing.
66  */
67 enum GNUNET_DHT_RouteOption
68   {
69     /**
70      * Default.  Do nothing special.
71      */
72     GNUNET_DHT_RO_NONE = 0,
73
74     /**
75      * Each peer along the way should look at 'enc' (otherwise
76      * only the k-peers closest to the key should look at it).
77      */
78     GNUNET_DHT_RO_DEMULTIPLEX_EVERYWHERE = 1,
79
80     /**
81      * We should keep track of the route that the message
82      * took in the P2P network.
83      */
84     GNUNET_DHT_RO_RECORD_ROUTE = 2
85   };
86
87
88 /**
89  * Initialize the connection with the DHT service.
90  *
91  * @param sched scheduler to use
92  * @param cfg configuration to use
93  * @param ht_len size of the internal hash table to use for
94  *               processing multiple GET/FIND requests in parallel
95  * @return NULL on error
96  */
97 struct GNUNET_DHT_Handle *
98 GNUNET_DHT_connect (struct GNUNET_SCHEDULER_Handle *sched,
99                     const struct GNUNET_CONFIGURATION_Handle *cfg,
100                     unsigned int ht_len);
101
102
103 /**
104  * Shutdown connection with the DHT service.
105  *
106  * @param handle connection to shut down
107  */
108 void
109 GNUNET_DHT_disconnect (struct GNUNET_DHT_Handle *handle);
110
111
112 /* *************** Standard API: get and put ******************* */
113
114 /**
115  * Perform a PUT operation on the DHT identified by 'table' storing
116  * a binding of 'key' to 'value'.  The peer does not have to be part
117  * of the table (if so, we will attempt to locate a peer that is!)
118  *
119  * @param handle handle to DHT service
120  * @param key the key to store data under
121  * @param options routing options for this message
122  * @param type type of the value
123  * @param size number of bytes in data; must be less than 64k
124  * @param data the data to store
125  * @param exp desired expiration time for the data
126  * @param timeout when to abort if we fail to transmit the request 
127  *                for the PUT to the local DHT service
128  * @param cont continuation to call when done (transmitting request to service)
129  * @param cont_cls closure for cont
130  */
131 void
132 GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle,
133                 const GNUNET_HashCode * key,
134                 enum GNUNET_DHT_RouteOption options,
135                 enum GNUNET_BLOCK_Type type,
136                 size_t size,
137                 const char *data,
138                 struct GNUNET_TIME_Absolute exp,
139                 struct GNUNET_TIME_Relative timeout,
140                 GNUNET_SCHEDULER_Task cont,
141                 void *cont_cls);
142
143
144 /**
145  * Iterator called on each result obtained for a DHT
146  * operation that expects a reply
147  *
148  * @param cls closure
149  * @param exp when will this value expire
150  * @param key key of the result
151  * @param get_path NULL-terminated array of pointers
152  *                 to the peers on reverse GET path (or NULL if not recorded)
153  * @param put_path NULL-terminated array of pointers
154  *                 to the peers on the PUT path (or NULL if not recorded)
155  * @param type type of the result
156  * @param size number of bytes in data
157  * @param data pointer to the result data
158  */
159 typedef void (*GNUNET_DHT_GetIterator)(void *cls,
160                                        struct GNUNET_TIME_Absolute exp,
161                                        const GNUNET_HashCode * key,
162                                        const struct GNUNET_PeerIdentity * const *get_path,
163                                        const struct GNUNET_PeerIdentity * const *put_path,
164                                        enum GNUNET_BLOCK_Type type,
165                                        size_t size,
166                                        const void *data);
167
168
169
170 /**
171  * Perform an asynchronous GET operation on the DHT.  See
172  * also "GNUNET_BLOCK_evaluate".
173  *
174  * @param handle handle to the DHT service
175  * @param timeout timeout for this request to be sent to the
176  *        service (this is NOT a timeout for receiving responses)
177  * @param type expected type of the response object (GNUNET_BLOCK_TYPE_FS_*)
178  * @param key the key to look up
179  * @param options routing options for this message
180  * @param bf bloom filter associated with query (can be NULL)
181  * @param bf_mutator mutation value for bf
182  * @param xquery extrended query data (can be NULL, depending on type)
183  * @param xquery_size number of bytes in xquery
184  * @param iter function to call on each result
185  * @param iter_cls closure for iter
186  * @return handle to stop the async get, NULL on error
187  */
188 struct GNUNET_DHT_GetHandle *
189 GNUNET_DHT_get_start (struct GNUNET_DHT_Handle *handle,
190                       struct GNUNET_TIME_Relative timeout,
191                       enum GNUNET_BLOCK_Type type,
192                       const GNUNET_HashCode * key,
193                       enum GNUNET_DHT_RouteOption options,
194                       const struct GNUNET_CONTAINER_BloomFilter *bf,
195                       int32_t bf_mutator,
196                       const void *xquery,
197                       size_t xquery_size,
198                       GNUNET_DHT_GetIterator iter,
199                       void *iter_cls);
200
201
202 /**
203  * Stop async DHT-get.  Frees associated resources.
204  *
205  * @param get_handle GET operation to stop.
206  */
207 void
208 GNUNET_DHT_get_stop (struct GNUNET_DHT_GetHandle *get_handle);
209
210
211 /* ******** Special high-level API for finding peers *********** */
212
213 /**
214  * Iterator called on each result obtained from a find peer
215  * operation
216  *
217  * @param cls closure
218  * @param peer hello of a target (peer near key)
219  */
220 typedef void (*GNUNET_DHT_FindPeerProcessor)(void *cls,
221                                              const struct GNUNET_HELLO_Message *peer);
222
223
224 /**
225  * Perform an asynchronous FIND PEER operation on the DHT.
226  *
227  * @param handle handle to the DHT service
228  * @param timeout timeout for this request to be sent to the
229  *        service
230  * @param key the key to look up
231  * @param options routing options for this message
232  * @param proc function to call on each result
233  * @param proc_cls closure for proc
234  * @return handle to stop the async get, NULL on error
235  */
236 struct GNUNET_DHT_FindPeerHandle *
237 GNUNET_DHT_find_peer_start (struct GNUNET_DHT_Handle *handle,
238                             struct GNUNET_TIME_Relative timeout,
239                             const GNUNET_HashCode *key,
240                             enum GNUNET_DHT_RouteOption options,
241                             GNUNET_DHT_FindPeerProcessor proc,
242                             void *proc_cls);
243
244
245 /**
246  * Stop async find peer.  Frees associated resources.
247  *
248  * @param find_peer_handle GET operation to stop.
249  */
250 void
251 GNUNET_DHT_find_peer_stop (struct GNUNET_DHT_FindPeerHandle *find_peer_handle);
252
253
254
255 /* ***** Special low-level API providing generic routeing abstraction ***** */
256
257 /**
258  * Iterator called on each result obtained from a generic route
259  * operation
260  *
261  * @param cls closure
262  * @param key key that was used
263  * @param reply response
264  */
265 typedef void (*GNUNET_DHT_ReplyProcessor)(void *cls,
266                                           const GNUNET_HashCode *key,
267                                           const struct GNUNET_MessageHeader *reply);
268
269
270 /**
271  * Perform an asynchronous ROUTE_START operation on the DHT.
272  *
273  * @param handle handle to the DHT service
274  * @param key the key to look up
275  * @param desired_replication_level how many peers should ultimately receive
276  *                this message (advisory only, target may be too high for the
277  *                given DHT or not hit exactly).
278  * @param options options for routing
279  * @param enc send the encapsulated message to a peer close to the key
280  * @param timeout when to abort with an error if we fail to get
281  *                a confirmation for the request (when necessary) or how long
282  *                to wait for transmission to the service; only applies
283  *                if 'iter' is NULL
284  * @param iter function to call on each result, NULL if no replies are expected
285  * @param iter_cls closure for iter
286  * @param cont continuation to call when the request has been transmitted
287  *             the first time to the service
288  * @param cont_cls closure for cont
289  * @return handle to stop the request, NULL if the request is "fire and forget"
290  */
291 struct GNUNET_DHT_RouteHandle *
292 GNUNET_DHT_route_start (struct GNUNET_DHT_Handle *handle,
293                         const GNUNET_HashCode *key,
294                         uint32_t desired_replication_level,
295                         enum GNUNET_DHT_RouteOption options,
296                         const struct GNUNET_MessageHeader *enc,
297                         struct GNUNET_TIME_Relative timeout,
298                         GNUNET_DHT_ReplyProcessor iter,
299                         void *iter_cls,
300                         GNUNET_SCHEDULER_Task cont,
301                         void *cont_cls);
302
303
304
305 /**
306  * Stop async route operation.  Frees associated resources.
307  *
308  * @param route_handle  operation to stop.
309  */
310 void
311 GNUNET_DHT_route_stop (struct GNUNET_DHT_RouteHandle *route_handle);
312
313
314 /* ***** Special API for controlling DHT routing maintenance ******* */
315
316
317 /**
318  * Send a message to the DHT telling it to issue a single find
319  * peer request using the peers unique identifier as key.  This
320  * is used to fill the routing table, and is normally controlled
321  * by the DHT itself.  However, for testing and perhaps more
322  * close control over the DHT, this can be explicitly managed.
323  *
324  * @param cont continuation to call when done (transmitting request to service)
325  * @param cont_cls closure for cont
326  * @param handle handle to the DHT service
327  */
328 void
329 GNUNET_DHT_find_peers (struct GNUNET_DHT_Handle *handle,
330                        GNUNET_SCHEDULER_Task cont,
331                        void *cont_cls);
332
333 /* ***** Special API for testing robustness with malicious peers ******* */
334
335 #if HAVE_MALICIOUS
336 /* Note that these functions are NOT considered to be part of the
337    "official" API and hence are NOT subjected to library versioning;
338    only developers testing GNUnet's robustness should have any use for
339    them, applications should never use them.  Applications must NOT
340    define "HAVE_MALICIOUS" before including this header. */
341
342 /**
343  * Send a message to the DHT telling it to start dropping
344  * all requests received.
345  *
346  * @param handle handle to the DHT service
347  */
348 void 
349 GNUNET_DHT_set_malicious_dropper (struct GNUNET_DHT_Handle *handle);
350
351
352 /**
353  * Send a message to the DHT telling it to start issuing random PUT
354  * requests every 'frequency' milliseconds.
355  *
356  * @param handle handle to the DHT service
357  * @param frequency delay (in milliseconds) between sending malicious messages
358  */
359 void 
360 GNUNET_DHT_set_malicious_putter (struct GNUNET_DHT_Handle *handle,
361                                  struct GNUNET_TIME_Relative frequency);
362
363
364 /**
365  * Send a message to the DHT telling it to start issuing random GET
366  * requests every 'frequency' milliseconds.
367  *
368  * @param handle handle to the DHT service
369  * @param frequency delay between sending malicious messages
370  */
371 void 
372 GNUNET_DHT_set_malicious_getter (struct GNUNET_DHT_Handle *handle, 
373                                  struct GNUNET_TIME_Relative frequency);
374
375
376 #endif
377
378 #if 0                           /* keep Emacsens' auto-indent happy */
379 {
380 #endif
381 #ifdef __cplusplus
382 }
383 #endif
384
385
386 #endif
387 /* gnunet_dht_service.h */