diff options
Diffstat (limited to 'src/include/gnunet_peerstore_service.h')
-rw-r--r-- | src/include/gnunet_peerstore_service.h | 200 |
1 files changed, 160 insertions, 40 deletions
diff --git a/src/include/gnunet_peerstore_service.h b/src/include/gnunet_peerstore_service.h index 91a8f2e66..3fb9df82a 100644 --- a/src/include/gnunet_peerstore_service.h +++ b/src/include/gnunet_peerstore_service.h | |||
@@ -19,6 +19,9 @@ | |||
19 | */ | 19 | */ |
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @addtogroup Backbone | ||
23 | * @{ | ||
24 | * | ||
22 | * @author Omar Tarabai | 25 | * @author Omar Tarabai |
23 | * | 26 | * |
24 | * @file | 27 | * @file |
@@ -33,6 +36,7 @@ | |||
33 | #ifndef GNUNET_PEERSTORE_SERVICE_H | 36 | #ifndef GNUNET_PEERSTORE_SERVICE_H |
34 | #define GNUNET_PEERSTORE_SERVICE_H | 37 | #define GNUNET_PEERSTORE_SERVICE_H |
35 | 38 | ||
39 | |||
36 | #include "gnunet_util_lib.h" | 40 | #include "gnunet_util_lib.h" |
37 | 41 | ||
38 | #ifdef __cplusplus | 42 | #ifdef __cplusplus |
@@ -42,6 +46,10 @@ extern "C" { | |||
42 | #endif | 46 | #endif |
43 | #endif | 47 | #endif |
44 | 48 | ||
49 | /** | ||
50 | * Key used for storing HELLO in the peerstore | ||
51 | */ | ||
52 | #define GNUNET_PEERSTORE_HELLO_KEY "peerstore-peer-hello-uri" | ||
45 | 53 | ||
46 | /** | 54 | /** |
47 | * Key used for storing addresses in URL format in the peerstore | 55 | * Key used for storing addresses in URL format in the peerstore |
@@ -58,32 +66,32 @@ extern "C" { | |||
58 | * messages. | 66 | * messages. |
59 | */ | 67 | */ |
60 | #define GNUNET_PEERSTORE_TRANSPORT_BACKCHANNEL_MONOTIME \ | 68 | #define GNUNET_PEERSTORE_TRANSPORT_BACKCHANNEL_MONOTIME \ |
61 | "transport-backchannel-monotonic-time" | 69 | "transport-backchannel-monotonic-time" |
62 | 70 | ||
63 | /** | 71 | /** |
64 | * Key used to store sender's monotonic time from DV learn | 72 | * Key used to store sender's monotonic time from DV learn |
65 | * messages. | 73 | * messages. |
66 | */ | 74 | */ |
67 | #define GNUNET_PEERSTORE_TRANSPORT_DVLEARN_MONOTIME \ | 75 | #define GNUNET_PEERSTORE_TRANSPORT_DVLEARN_MONOTIME \ |
68 | "transport-dv-learn-monotonic-time" | 76 | "transport-dv-learn-monotonic-time" |
69 | 77 | ||
70 | /** | 78 | /** |
71 | * Key used to store sender's monotonic time from handshake message. | 79 | * Key used to store sender's monotonic time from handshake message. |
72 | */ | 80 | */ |
73 | #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE \ | 81 | #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE \ |
74 | "transport-tcp-communicator-handshake" | 82 | "transport-tcp-communicator-handshake" |
75 | 83 | ||
76 | /** | 84 | /** |
77 | * Key used to store sender's monotonic time from handshake ack message. | 85 | * Key used to store sender's monotonic time from handshake ack message. |
78 | */ | 86 | */ |
79 | #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE_ACK \ | 87 | #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE_ACK \ |
80 | "transport-tcp-communicator-handshake-ack" | 88 | "transport-tcp-communicator-handshake-ack" |
81 | 89 | ||
82 | /** | 90 | /** |
83 | * Key used to store sender's monotonic time from rekey message. | 91 | * Key used to store sender's monotonic time from rekey message. |
84 | */ | 92 | */ |
85 | #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_REKEY \ | 93 | #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_REKEY \ |
86 | "transport-tcp-communicator-rekey" | 94 | "transport-tcp-communicator-rekey" |
87 | 95 | ||
88 | 96 | ||
89 | /** | 97 | /** |
@@ -100,7 +108,8 @@ enum GNUNET_PEERSTORE_StoreOption | |||
100 | * Delete any previous values for the given key before | 108 | * Delete any previous values for the given key before |
101 | * storing the given value. | 109 | * storing the given value. |
102 | */ | 110 | */ |
103 | GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1 | 111 | GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1, |
112 | |||
104 | }; | 113 | }; |
105 | 114 | ||
106 | /** | 115 | /** |
@@ -114,6 +123,11 @@ struct GNUNET_PEERSTORE_Handle; | |||
114 | struct GNUNET_PEERSTORE_StoreContext; | 123 | struct GNUNET_PEERSTORE_StoreContext; |
115 | 124 | ||
116 | /** | 125 | /** |
126 | * Context for the info handler. | ||
127 | */ | ||
128 | struct GNUNET_PEERSTORE_NotifyContext; | ||
129 | |||
130 | /** | ||
117 | * Single PEERSTORE record | 131 | * Single PEERSTORE record |
118 | */ | 132 | */ |
119 | struct GNUNET_PEERSTORE_Record | 133 | struct GNUNET_PEERSTORE_Record |
@@ -148,11 +162,6 @@ struct GNUNET_PEERSTORE_Record | |||
148 | */ | 162 | */ |
149 | struct GNUNET_TIME_Absolute expiry; | 163 | struct GNUNET_TIME_Absolute expiry; |
150 | 164 | ||
151 | /** | ||
152 | * Client from which this record originated. | ||
153 | * NOTE: This is internal to the service. | ||
154 | */ | ||
155 | struct GNUNET_SERVICE_Client *client; | ||
156 | }; | 165 | }; |
157 | 166 | ||
158 | 167 | ||
@@ -166,9 +175,16 @@ typedef void (*GNUNET_PEERSTORE_Continuation) (void *cls, int success); | |||
166 | 175 | ||
167 | 176 | ||
168 | /** | 177 | /** |
178 | * Context for a add hello uri request. | ||
179 | */ | ||
180 | struct GNUNET_PEERSTORE_StoreHelloContext; | ||
181 | |||
182 | |||
183 | /** | ||
169 | * Function called by PEERSTORE for each matching record. | 184 | * Function called by PEERSTORE for each matching record. |
170 | * | 185 | * |
171 | * @param cls closure | 186 | * @param cls closure |
187 | * @param seq sequence in interation | ||
172 | * @param record peerstore record information | 188 | * @param record peerstore record information |
173 | * @param emsg error message, or NULL if no errors | 189 | * @param emsg error message, or NULL if no errors |
174 | */ | 190 | */ |
@@ -177,6 +193,43 @@ typedef void (*GNUNET_PEERSTORE_Processor) ( | |||
177 | const struct GNUNET_PEERSTORE_Record *record, | 193 | const struct GNUNET_PEERSTORE_Record *record, |
178 | const char *emsg); | 194 | const char *emsg); |
179 | 195 | ||
196 | /** | ||
197 | * Function called by PEERSTORE when notifying a client about a changed hello. | ||
198 | * | ||
199 | * @param cls closure | ||
200 | * @param hello_uri Hello uri. | ||
201 | */ | ||
202 | typedef void (*GNUNET_PEERSTORE_hello_notify_cb) ( | ||
203 | void *cls, | ||
204 | const struct GNUNET_PeerIdentity *peer, | ||
205 | const struct GNUNET_MessageHeader *hello, | ||
206 | const char *err_msg); | ||
207 | |||
208 | /** | ||
209 | * Add hello to peerstore. | ||
210 | * | ||
211 | * @param h handle for peerstore. | ||
212 | * @param msg The hello to add. | ||
213 | * @param cont The continuation function to execute after storing. | ||
214 | * @param cont_cls The continuation function closure. | ||
215 | * @return The context for storing. | ||
216 | */ | ||
217 | struct GNUNET_PEERSTORE_StoreHelloContext * | ||
218 | GNUNET_PEERSTORE_hello_add (struct GNUNET_PEERSTORE_Handle *h, | ||
219 | const struct GNUNET_MessageHeader *msg, | ||
220 | GNUNET_PEERSTORE_Continuation cont, | ||
221 | void *cont_cls); | ||
222 | |||
223 | |||
224 | /** | ||
225 | * Cancel the request to add a hello. | ||
226 | * | ||
227 | * @param huc The context for storing a hello. | ||
228 | */ | ||
229 | void | ||
230 | GNUNET_PEERSTORE_hello_add_cancel (struct | ||
231 | GNUNET_PEERSTORE_StoreHelloContext *huc); | ||
232 | |||
180 | 233 | ||
181 | /** | 234 | /** |
182 | * Connect to the PEERSTORE service. | 235 | * Connect to the PEERSTORE service. |
@@ -188,15 +241,13 @@ GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); | |||
188 | 241 | ||
189 | 242 | ||
190 | /** | 243 | /** |
191 | * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH requests | 244 | * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH and |
192 | * will be canceled. | 245 | * STORE requests will be canceled. |
193 | * Any pending STORE requests will depend on @e snyc_first flag. | ||
194 | * | 246 | * |
195 | * @param h handle to disconnect | 247 | * @param h handle to disconnect |
196 | * @param sync_first send any pending STORE requests before disconnecting | ||
197 | */ | 248 | */ |
198 | void | 249 | void |
199 | GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first); | 250 | GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h); |
200 | 251 | ||
201 | 252 | ||
202 | /** | 253 | /** |
@@ -238,63 +289,130 @@ GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); | |||
238 | 289 | ||
239 | 290 | ||
240 | /** | 291 | /** |
241 | * Iterate over records matching supplied key information | 292 | * Iterate over peerstore entries. |
293 | * The iteration can be filtered to contain only records | ||
294 | * matching @a peer and/or @a key. | ||
295 | * The @a sub_system to match must be provided. | ||
296 | * @a callback will be called with (each) matching record. | ||
297 | * #GNUNET_PEERSTORE_iteration_next() must be invoked | ||
298 | * to continue processing until the end of the iteration is | ||
299 | * reached. | ||
242 | * | 300 | * |
243 | * @param h handle to the PEERSTORE service | 301 | * @param h handle to the PEERSTORE service |
244 | * @param sub_system name of sub system | 302 | * @param sub_system name of sub system |
245 | * @param peer Peer identity (can be NULL) | 303 | * @param peer Peer identity (can be NULL) |
246 | * @param key entry key string (can be NULL) | 304 | * @param key entry key string (can be NULL) |
247 | * @param callback function called with each matching record, all NULL's on end | 305 | * @param callback function called with each matching record. The record will be NULL to indicate end. |
248 | * @param callback_cls closure for @a callback | 306 | * @param callback_cls closure for @a callback |
307 | * @return Handle to iteration request | ||
249 | */ | 308 | */ |
250 | struct GNUNET_PEERSTORE_IterateContext * | 309 | struct GNUNET_PEERSTORE_IterateContext * |
251 | GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h, | 310 | GNUNET_PEERSTORE_iteration_start (struct GNUNET_PEERSTORE_Handle *h, |
252 | const char *sub_system, | 311 | const char *sub_system, |
253 | const struct GNUNET_PeerIdentity *peer, | 312 | const struct GNUNET_PeerIdentity *peer, |
254 | const char *key, | 313 | const char *key, |
255 | GNUNET_PEERSTORE_Processor callback, | 314 | GNUNET_PEERSTORE_Processor callback, |
256 | void *callback_cls); | 315 | void *callback_cls); |
257 | 316 | ||
258 | 317 | ||
259 | /** | 318 | /** |
260 | * Cancel an iterate request | 319 | * Continue an iteration. |
261 | * Please do not call after the iterate request is done | 320 | * Do NOT call after the iterate request is done. |
262 | * | 321 | * |
263 | * @param ic Iterate request context as returned by GNUNET_PEERSTORE_iterate() | 322 | * @param ic Iterate request context as returned by #GNUNET_PEERSTORE_iteration_start() |
323 | * @param limit how many records to return max until #GNUNET_PEERSTORE_iterate_next() needs to be called again. | ||
264 | */ | 324 | */ |
265 | void | 325 | void |
266 | GNUNET_PEERSTORE_iterate_cancel (struct GNUNET_PEERSTORE_IterateContext *ic); | 326 | GNUNET_PEERSTORE_iteration_next (struct GNUNET_PEERSTORE_IterateContext *ic, |
327 | uint64_t limit); | ||
267 | 328 | ||
268 | 329 | ||
269 | /** | 330 | /** |
331 | * Cancel an iteration. | ||
332 | * Do NOT call after the iterate request is done | ||
333 | * | ||
334 | * @param ic Iterate request context as returned by #GNUNET_PEERSTORE_iteration_start() | ||
335 | */ | ||
336 | void | ||
337 | GNUNET_PEERSTORE_iteration_stop (struct GNUNET_PEERSTORE_IterateContext *ic); | ||
338 | |||
339 | /** | ||
270 | * Request watching a given key | 340 | * Request watching a given key |
271 | * User will be notified with any new values added to key. | 341 | * The monitoring can be filtered to contain only records |
342 | * matching @a peer and/or @a key. | ||
343 | * The @a sub_system to match must be provided. | ||
344 | * @a callback will be called with (each) matching new record. | ||
345 | * #GNUNET_PEERSTORE_monitor_next() must be invoked | ||
346 | * to continue processing until @a sync_cb is | ||
347 | * called, indicating that the caller should be up-to-date. | ||
348 | * The caller will be notified with any new values added to key | ||
349 | * through @a callback. | ||
350 | * If @a iterate_first is set to GNUNET_YES, the monitor will first | ||
351 | * iterate over all existing, matching records. In any case, | ||
352 | * after @a sync_cb is called the first time monitoring starts. | ||
272 | * | 353 | * |
273 | * @param h handle to the PEERSTORE service | 354 | * @param h handle to the PEERSTORE service |
355 | * @param iterate_first first iterated of all results if GNUNET_YES | ||
274 | * @param sub_system name of sub system | 356 | * @param sub_system name of sub system |
275 | * @param peer Peer identity | 357 | * @param peer Peer identity |
276 | * @param key entry key string | 358 | * @param key entry key string |
359 | * @param error_cb function to call on error (i.e. disconnect); note that | ||
360 | * unlike the other error callbacks in this API, a call to this | ||
361 | * function does NOT destroy the monitor handle, it merely signals | ||
362 | * that monitoring is down. You need to still explicitly call | ||
363 | * #GNUNET_PEERSTORE_monitor_stop(). | ||
364 | * @param error_cb_cls closure for @a error_cb | ||
365 | * @param sync_cb function called when we're in sync with the peerstore | ||
366 | * @param sync_cb_cls closure for @a sync_cb | ||
277 | * @param callback function called with each new value | 367 | * @param callback function called with each new value |
278 | * @param callback_cls closure for @a callback | 368 | * @param callback_cls closure for @a callback |
279 | * @return Handle to watch request | 369 | * @return Handle to watch request |
280 | */ | 370 | */ |
281 | struct GNUNET_PEERSTORE_WatchContext * | 371 | struct GNUNET_PEERSTORE_Monitor * |
282 | GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h, | 372 | GNUNET_PEERSTORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg, |
283 | const char *sub_system, | 373 | int iterate_first, |
284 | const struct GNUNET_PeerIdentity *peer, | 374 | const char *sub_system, |
285 | const char *key, | 375 | const struct GNUNET_PeerIdentity *peer, |
286 | GNUNET_PEERSTORE_Processor callback, | 376 | const char *key, |
287 | void *callback_cls); | 377 | GNUNET_SCHEDULER_TaskCallback error_cb, |
288 | 378 | void *error_cb_cls, | |
379 | GNUNET_SCHEDULER_TaskCallback sync_cb, | ||
380 | void *sync_cb_cls, | ||
381 | GNUNET_PEERSTORE_Processor callback, | ||
382 | void *callback_cls); | ||
289 | 383 | ||
290 | /** | 384 | /** |
291 | * Cancel a watch request | 385 | * Calls the monitor processor specified in #GNUNET_PEERSTORE_monitor_start |
386 | * for the next record(s). This function is used to allow clients that merely | ||
387 | * monitor the NAMESTORE to still throttle namestore operations, so we can be | ||
388 | * sure that the monitors can keep up. | ||
389 | * | ||
390 | * Note that #GNUNET_PEERSTORE_store() only waits for this | ||
391 | * call if the previous limit set by the client was already reached. | ||
392 | * Thus, by using a @a limit greater than 1, monitors basically enable | ||
393 | * a queue of notifications to be processed asynchronously with some | ||
394 | * delay. Note that even with a limit of 1 the | ||
395 | * #GNUNET_PEERSTORE_store() function will run asynchronously | ||
396 | * and the continuation may be invoked before the monitors completed | ||
397 | * (or even started) processing the notification. Thus, monitors will | ||
398 | * only closely track the current state of the peerstore, but not | ||
399 | * be involved in the transactions. | ||
292 | * | 400 | * |
293 | * @param wc handle to the watch request | 401 | * @param zm the monitor |
402 | * @param limit number of records to return to the iterator in one shot | ||
403 | * (before #GNUNET_PEERSTORE_monitor_next is to be called again) | ||
294 | */ | 404 | */ |
295 | void | 405 | void |
296 | GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc); | 406 | GNUNET_PEERSTORE_monitor_next (struct GNUNET_PEERSTORE_Monitor *zm, |
407 | uint64_t limit); | ||
297 | 408 | ||
409 | /** | ||
410 | * Stop monitoring. | ||
411 | * | ||
412 | * @param zm handle to the monitor activity to stop | ||
413 | */ | ||
414 | void | ||
415 | GNUNET_PEERSTORE_monitor_stop (struct GNUNET_PEERSTORE_Monitor *zm); | ||
298 | 416 | ||
299 | #if 0 /* keep Emacsens' auto-indent happy */ | 417 | #if 0 /* keep Emacsens' auto-indent happy */ |
300 | { | 418 | { |
@@ -306,3 +424,5 @@ GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc); | |||
306 | #endif | 424 | #endif |
307 | 425 | ||
308 | /** @} */ /* end of group */ | 426 | /** @} */ /* end of group */ |
427 | |||
428 | /** @} */ /* end of group addition */ | ||