2 This file is part of GNUnet
3 Copyright (C) 2013, 2014 Christian Grothoff (and other contributing authors)
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.
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.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @file include/gnunet_set_service.h
23 * @brief two-peer set operations
24 * @author Florian Dold
25 * @author Christian Grothoff
28 #ifndef GNUNET_SET_SERVICE_H
29 #define GNUNET_SET_SERVICE_H
34 #if 0 /* keep Emacsens' auto-indent happy */
39 #include "gnunet_common.h"
40 #include "gnunet_time_lib.h"
41 #include "gnunet_configuration_lib.h"
45 * Maximum size of a context message for set operation requests.
47 #define GNUNET_SET_CONTEXT_MESSAGE_MAX_SIZE ((1<<16) - 1024)
51 * Opaque handle to a set.
53 struct GNUNET_SET_Handle;
56 * Opaque handle to a set operation request from another peer.
58 struct GNUNET_SET_Request;
61 * Opaque handle to a listen operation.
63 struct GNUNET_SET_ListenHandle;
66 * Opaque handle to a set operation.
68 struct GNUNET_SET_OperationHandle;
72 * The operation that a set set supports.
74 enum GNUNET_SET_OperationType
77 * A purely local set that does not support any operation.
79 GNUNET_SET_OPERATION_NONE,
82 * Set intersection, only return elements that are in both sets.
84 GNUNET_SET_OPERATION_INTERSECTION,
87 * Set union, return all elements that are in at least one of the sets.
89 GNUNET_SET_OPERATION_UNION
94 * Status for the result callback
96 enum GNUNET_SET_Status
99 * Everything went ok, we are transmitting an element of the
100 * result (in set, or to be removed from set, depending on
101 * the `enum GNUNET_SET_ResultMode`).
104 * #GNUNET_SET_RESULT_FULL,
105 * #GNUNET_SET_RESULT_ADDED,
106 * #GNUNET_SET_RESULT_REMOVED,
108 GNUNET_SET_STATUS_OK,
111 * Element should be added to the result set
112 * of the local peer, i.e. the local peer is
113 * missing an element.
115 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
117 GNUNET_SET_STATUS_ADD_LOCAL,
120 * Element should be added to the result set
121 * of the remove peer, i.e. the remote peer is
122 * missing an element.
124 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
126 GNUNET_SET_STATUS_ADD_REMOTE,
129 * The other peer refused to to the operation with us,
130 * or something went wrong.
132 GNUNET_SET_STATUS_FAILURE,
135 * Success, all elements have been returned (but the other peer
136 * might still be receiving some from us, so we are not done). Only
137 * used during UNION operation.
139 GNUNET_SET_STATUS_HALF_DONE,
142 * Success, all elements have been sent (and received).
144 GNUNET_SET_STATUS_DONE
149 * The way results are given to the client.
151 enum GNUNET_SET_ResultMode
154 * Client gets every element in the resulting set.
156 * Only supported for set intersection.
158 GNUNET_SET_RESULT_FULL,
161 * Client gets notified of the required changes
162 * for both the local and the remote set.
164 * Only supported for set
166 GNUNET_SET_RESULT_SYMMETRIC,
169 * Client gets only elements that have been removed from the set.
171 * Only supported for set intersection.
173 GNUNET_SET_RESULT_REMOVED,
176 * Client gets only elements that have been removed from the set.
178 * Only supported for set union.
180 GNUNET_SET_RESULT_ADDED
185 * Element stored in a set.
187 struct GNUNET_SET_Element
190 * Number of bytes in the buffer pointed to by data.
195 * Application-specific element type.
197 uint16_t element_type;
200 * Actual data of the element
207 * Continuation used for some of the set operations
211 typedef void (*GNUNET_SET_Continuation) (void *cls);
215 * Callback for set operation results. Called for each element
219 * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK
220 * @param status see `enum GNUNET_SET_Status`
222 typedef void (*GNUNET_SET_ResultIterator) (void *cls,
223 const struct GNUNET_SET_Element *element,
224 enum GNUNET_SET_Status status);
227 * Iterator for set elements.
230 * @param element the current element, NULL if all elements have been
232 * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop.
234 typedef int (*GNUNET_SET_ElementIterator) (void *cls,
235 const struct GNUNET_SET_Element *element);
239 * Called when another peer wants to do a set operation with the
240 * local peer. If a listen error occurs, the @a request is NULL.
243 * @param other_peer the other peer
244 * @param context_msg message with application specific information from
246 * @param request request from the other peer (never NULL), use GNUNET_SET_accept()
247 * to accept it, otherwise the request will be refused
248 * Note that we can't just return value from the listen callback,
249 * as it is also necessary to specify the set we want to do the
250 * operation with, whith sometimes can be derived from the context
251 * message. It's necessary to specify the timeout.
254 (*GNUNET_SET_ListenCallback) (void *cls,
255 const struct GNUNET_PeerIdentity *other_peer,
256 const struct GNUNET_MessageHeader *context_msg,
257 struct GNUNET_SET_Request *request);
262 (*GNUNET_SET_CopyReadyCallback) (void *cls,
263 struct GNUNET_SET_Handle *copy);
267 * Create an empty set, supporting the specified operation.
269 * @param cfg configuration to use for connecting to the
271 * @param op operation supported by the set
272 * Note that the operation has to be specified
273 * beforehand, as certain set operations need to maintain
274 * data structures spefific to the operation
275 * @return a handle to the set
277 struct GNUNET_SET_Handle *
278 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
279 enum GNUNET_SET_OperationType op);
283 * Add an element to the given set.
284 * After the element has been added (in the sense of being
285 * transmitted to the set service), @a cont will be called.
286 * Calls to #GNUNET_SET_add_element can be queued
288 * @param set set to add element to
289 * @param element element to add to the set
290 * @param cont continuation called after the element has been added
291 * @param cont_cls closure for @a cont
292 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
293 * set is invalid (e.g. the set service crashed)
296 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
297 const struct GNUNET_SET_Element *element,
298 GNUNET_SET_Continuation cont,
303 * Remove an element to the given set.
304 * After the element has been removed (in the sense of the
305 * request being transmitted to the set service), cont will be called.
306 * Calls to remove_element can be queued
308 * @param set set to remove element from
309 * @param element element to remove from the set
310 * @param cont continuation called after the element has been removed
311 * @param cont_cls closure for @a cont
312 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
313 * set is invalid (e.g. the set service crashed)
316 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
317 const struct GNUNET_SET_Element *element,
318 GNUNET_SET_Continuation cont,
323 GNUNET_SET_copy_lazy (struct GNUNET_SET_Handle *set,
324 GNUNET_SET_CopyReadyCallback cb,
329 * Destroy the set handle, and free all associated resources.
330 * Iterations must have completed (or be explicitly canceled)
331 * before destroying the corresponding set. Operations may
332 * still be pending when a set is destroyed.
334 * @param set set to destroy
337 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
341 * Prepare a set operation to be evaluated with another peer.
342 * The evaluation will not start until the client provides
343 * a local set with GNUNET_SET_commit().
345 * @param other_peer peer with the other set
346 * @param app_id hash for the application using the set
347 * @param context_msg additional information for the request
348 * @param result_mode specified how results will be returned,
349 * see `enum GNUNET_SET_ResultMode`.
350 * @param result_cb called on error or success
351 * @param result_cls closure for @a result_cb
352 * @return a handle to cancel the operation
354 struct GNUNET_SET_OperationHandle *
355 GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
356 const struct GNUNET_HashCode *app_id,
357 const struct GNUNET_MessageHeader *context_msg,
358 enum GNUNET_SET_ResultMode result_mode,
359 GNUNET_SET_ResultIterator result_cb,
364 * Wait for set operation requests for the given application ID.
365 * If the connection to the set service is lost, the listener is
366 * re-created transparently with exponential backoff.
368 * @param cfg configuration to use for connecting to
370 * @param operation operation we want to listen for
371 * @param app_id id of the application that handles set operation requests
372 * @param listen_cb called for each incoming request matching the operation
374 * @param listen_cls handle for @a listen_cb
375 * @return a handle that can be used to cancel the listen operation
377 struct GNUNET_SET_ListenHandle *
378 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
379 enum GNUNET_SET_OperationType op_type,
380 const struct GNUNET_HashCode *app_id,
381 GNUNET_SET_ListenCallback listen_cb,
386 * Cancel the given listen operation. After calling cancel, the
387 * listen callback for this listen handle will not be called again.
389 * @param lh handle for the listen operation
392 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
396 * Accept a request we got via GNUNET_SET_listen(). Must be called during
397 * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid
399 * Call GNUNET_SET_commit() to provide the local set to use for the operation,
400 * and to begin the exchange with the remote peer.
402 * @param request request to accept
403 * @param result_mode specified how results will be returned,
404 * see `enum GNUNET_SET_ResultMode`.
405 * @param result_cb callback for the results
406 * @param result_cls closure for @a result_cb
407 * @return a handle to cancel the operation
409 struct GNUNET_SET_OperationHandle *
410 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
411 enum GNUNET_SET_ResultMode result_mode,
412 GNUNET_SET_ResultIterator result_cb,
417 * Commit a set to be used with a set operation.
418 * This function is called once we have fully constructed
419 * the set that we want to use for the operation. At this
420 * time, the P2P protocol can then begin to exchange the
421 * set information and call the result callback with the
422 * result information.
424 * @param oh handle to the set operation
425 * @param set the set to use for the operation
426 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
427 * set is invalid (e.g. the set service crashed)
430 GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
431 struct GNUNET_SET_Handle *set);
435 * Cancel the given set operation. May not be called after the
436 * operation's `GNUNET_SET_ResultIterator` has been called with a
437 * status that indicates error, timeout or done.
439 * @param oh set operation to cancel
442 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
446 * Iterate over all elements in the given set.
447 * Note that this operation involves transferring every element of the set
448 * from the service to the client, and is thus costly.
449 * Only one iteration per set may be active at the same time.
451 * @param set the set to iterate over
452 * @param iter the iterator to call for each element
453 * @param iter_cls closure for @a iter
454 * @return #GNUNET_YES if the iteration started successfuly,
455 * #GNUNET_NO if another iteration was still active,
456 * #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
459 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
460 GNUNET_SET_ElementIterator iter,
464 * Stop iteration over all elements in the given set. Can only
465 * be called before the iteration has "naturally" completed its
468 * @param set the set to stop iterating over
471 GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
474 * Create a copy of an element. The copy
475 * must be GNUNET_free-d by the caller.
477 * @param element the element to copy
478 * @return the copied element
480 struct GNUNET_SET_Element *
481 GNUNET_SET_element_dup (const struct GNUNET_SET_Element *element);
484 * Hash a set element.
486 * @param element the element that should be hashed
487 * @param ret_hash a pointer to where the hash of @a element
491 GNUNET_SET_element_hash (const struct GNUNET_SET_Element *element, struct GNUNET_HashCode *ret_hash);
494 #if 0 /* keep Emacsens' auto-indent happy */