2 This file is part of GNUnet
3 Copyright (C) 2013, 2014 GNUnet e.V.
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 * @author Florian Dold
23 * @author Christian Grothoff
26 * Two-peer set operations
28 * @defgroup set Set service
29 * Two-peer set operations
31 * @see [Documentation](https://gnunet.org/set-subsystem)
36 #ifndef GNUNET_SET_SERVICE_H
37 #define GNUNET_SET_SERVICE_H
42 #if 0 /* keep Emacsens' auto-indent happy */
47 #include "gnunet_common.h"
48 #include "gnunet_time_lib.h"
49 #include "gnunet_configuration_lib.h"
53 * Maximum size of a context message for set operation requests.
55 #define GNUNET_SET_CONTEXT_MESSAGE_MAX_SIZE ((1<<16) - 1024)
59 * Opaque handle to a set.
61 struct GNUNET_SET_Handle;
64 * Opaque handle to a set operation request from another peer.
66 struct GNUNET_SET_Request;
69 * Opaque handle to a listen operation.
71 struct GNUNET_SET_ListenHandle;
74 * Opaque handle to a set operation.
76 struct GNUNET_SET_OperationHandle;
80 * The operation that a set set supports.
82 enum GNUNET_SET_OperationType
85 * A purely local set that does not support any operation.
87 GNUNET_SET_OPERATION_NONE,
90 * Set intersection, only return elements that are in both sets.
92 GNUNET_SET_OPERATION_INTERSECTION,
95 * Set union, return all elements that are in at least one of the sets.
97 GNUNET_SET_OPERATION_UNION
102 * Status for the result callback
104 enum GNUNET_SET_Status
107 * Everything went ok, we are transmitting an element of the
108 * result (in set, or to be removed from set, depending on
109 * the `enum GNUNET_SET_ResultMode`).
112 * #GNUNET_SET_RESULT_FULL,
113 * #GNUNET_SET_RESULT_ADDED,
114 * #GNUNET_SET_RESULT_REMOVED,
116 GNUNET_SET_STATUS_OK,
119 * Element should be added to the result set
120 * of the local peer, i.e. the local peer is
121 * missing an element.
123 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
125 GNUNET_SET_STATUS_ADD_LOCAL,
128 * Element should be added to the result set
129 * of the remote peer, i.e. the remote peer is
130 * missing an element.
132 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
134 GNUNET_SET_STATUS_ADD_REMOTE,
137 * The other peer refused to to the operation with us,
138 * or something went wrong.
140 GNUNET_SET_STATUS_FAILURE,
143 * Success, all elements have been returned (but the other peer
144 * might still be receiving some from us, so we are not done). Only
145 * used during UNION operation.
147 GNUNET_SET_STATUS_HALF_DONE,
150 * Success, all elements have been sent (and received).
152 GNUNET_SET_STATUS_DONE
158 * The way results are given to the client.
160 enum GNUNET_SET_ResultMode
163 * Client gets every element in the resulting set.
165 * Only supported for set intersection.
167 GNUNET_SET_RESULT_FULL,
170 * Client gets notified of the required changes
171 * for both the local and the remote set.
173 * Only supported for set
175 GNUNET_SET_RESULT_SYMMETRIC,
178 * Client gets only elements that have been removed from the set.
180 * Only supported for set intersection.
182 GNUNET_SET_RESULT_REMOVED,
185 * Client gets only elements that have been added to the set.
187 * Only supported for set union.
189 GNUNET_SET_RESULT_ADDED
194 * Element stored in a set.
196 struct GNUNET_SET_Element
199 * Number of bytes in the buffer pointed to by data.
204 * Application-specific element type.
206 uint16_t element_type;
209 * Actual data of the element
216 * Possible options to pass to a set operation.
218 * Used as tag for struct #GNUNET_SET_Option.
220 enum GNUNET_SET_OptionType
223 * Fail set operations when the other peer shows weird behavior
224 * that might by a Byzantine fault.
226 * For set union, 'v.num' is a lower bound on elements
227 * that the other peer must have in common with us.
229 GNUNET_SET_OPTION_BYZANTINE=1,
231 * Do not use the optimized set operation, but send full sets.
232 * Might trigger Byzantine fault detection.
234 GNUNET_SET_OPTION_FORCE_FULL=2,
236 * Only use optimized set operations, even though for this
237 * particular set operation they might be much slower.
238 * Might trigger Byzantine fault detection.
240 GNUNET_SET_OPTION_FORCE_DELTA=4,
245 * Option for set operations.
247 struct GNUNET_SET_Option
250 * Type of the option.
252 enum GNUNET_SET_OptionType type;
255 * Value for the option, only used with some options.
264 * Continuation used for some of the set operations
269 (*GNUNET_SET_Continuation) (void *cls);
273 * Callback for set operation results. Called for each element
277 * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK
278 * @param status see `enum GNUNET_SET_Status`
281 (*GNUNET_SET_ResultIterator) (void *cls,
282 const struct GNUNET_SET_Element *element,
283 enum GNUNET_SET_Status status);
286 * Iterator for set elements.
289 * @param element the current element, NULL if all elements have been
291 * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop.
294 (*GNUNET_SET_ElementIterator) (void *cls,
295 const struct GNUNET_SET_Element *element);
299 * Called when another peer wants to do a set operation with the
300 * local peer. If a listen error occurs, the @a request is NULL.
303 * @param other_peer the other peer
304 * @param context_msg message with application specific information from
306 * @param request request from the other peer (never NULL), use GNUNET_SET_accept()
307 * to accept it, otherwise the request will be refused
308 * Note that we can't just return value from the listen callback,
309 * as it is also necessary to specify the set we want to do the
310 * operation with, whith sometimes can be derived from the context
311 * message. It's necessary to specify the timeout.
314 (*GNUNET_SET_ListenCallback) (void *cls,
315 const struct GNUNET_PeerIdentity *other_peer,
316 const struct GNUNET_MessageHeader *context_msg,
317 struct GNUNET_SET_Request *request);
322 (*GNUNET_SET_CopyReadyCallback) (void *cls,
323 struct GNUNET_SET_Handle *copy);
327 * Create an empty set, supporting the specified operation.
329 * @param cfg configuration to use for connecting to the
331 * @param op operation supported by the set
332 * Note that the operation has to be specified
333 * beforehand, as certain set operations need to maintain
334 * data structures spefific to the operation
335 * @return a handle to the set
337 struct GNUNET_SET_Handle *
338 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
339 enum GNUNET_SET_OperationType op);
343 * Add an element to the given set.
344 * After the element has been added (in the sense of being
345 * transmitted to the set service), @a cont will be called.
346 * Calls to #GNUNET_SET_add_element can be queued
348 * @param set set to add element to
349 * @param element element to add to the set
350 * @param cont continuation called after the element has been added
351 * @param cont_cls closure for @a cont
352 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
353 * set is invalid (e.g. the set service crashed)
356 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
357 const struct GNUNET_SET_Element *element,
358 GNUNET_SET_Continuation cont,
363 * Remove an element to the given set.
364 * After the element has been removed (in the sense of the
365 * request being transmitted to the set service), cont will be called.
366 * Calls to remove_element can be queued
368 * @param set set to remove element from
369 * @param element element to remove from the set
370 * @param cont continuation called after the element has been removed
371 * @param cont_cls closure for @a cont
372 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
373 * set is invalid (e.g. the set service crashed)
376 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
377 const struct GNUNET_SET_Element *element,
378 GNUNET_SET_Continuation cont,
383 GNUNET_SET_copy_lazy (struct GNUNET_SET_Handle *set,
384 GNUNET_SET_CopyReadyCallback cb,
389 * Destroy the set handle, and free all associated resources.
390 * Iterations must have completed (or be explicitly canceled)
391 * before destroying the corresponding set. Operations may
392 * still be pending when a set is destroyed.
394 * @param set set to destroy
397 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
401 * Prepare a set operation to be evaluated with another peer.
402 * The evaluation will not start until the client provides
403 * a local set with GNUNET_SET_commit().
405 * @param other_peer peer with the other set
406 * @param app_id hash for the application using the set
407 * @param context_msg additional information for the request
408 * @param result_mode specified how results will be returned,
409 * see `enum GNUNET_SET_ResultMode`.
410 * @param result_cb called on error or success
411 * @param result_cls closure for @a result_cb
412 * @return a handle to cancel the operation
414 struct GNUNET_SET_OperationHandle *
415 GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
416 const struct GNUNET_HashCode *app_id,
417 const struct GNUNET_MessageHeader *context_msg,
418 enum GNUNET_SET_ResultMode result_mode,
419 struct GNUNET_SET_Option options[],
420 GNUNET_SET_ResultIterator result_cb,
425 * Wait for set operation requests for the given application ID.
426 * If the connection to the set service is lost, the listener is
427 * re-created transparently with exponential backoff.
429 * @param cfg configuration to use for connecting to
431 * @param operation operation we want to listen for
432 * @param app_id id of the application that handles set operation requests
433 * @param listen_cb called for each incoming request matching the operation
435 * @param listen_cls handle for @a listen_cb
436 * @return a handle that can be used to cancel the listen operation
438 struct GNUNET_SET_ListenHandle *
439 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
440 enum GNUNET_SET_OperationType op_type,
441 const struct GNUNET_HashCode *app_id,
442 GNUNET_SET_ListenCallback listen_cb,
447 * Cancel the given listen operation. After calling cancel, the
448 * listen callback for this listen handle will not be called again.
450 * @param lh handle for the listen operation
453 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
457 * Accept a request we got via GNUNET_SET_listen(). Must be called during
458 * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid
460 * Call GNUNET_SET_commit() to provide the local set to use for the operation,
461 * and to begin the exchange with the remote peer.
463 * @param request request to accept
464 * @param result_mode specified how results will be returned,
465 * see `enum GNUNET_SET_ResultMode`.
466 * @param result_cb callback for the results
467 * @param result_cls closure for @a result_cb
468 * @return a handle to cancel the operation
470 struct GNUNET_SET_OperationHandle *
471 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
472 enum GNUNET_SET_ResultMode result_mode,
473 struct GNUNET_SET_Option options[],
474 GNUNET_SET_ResultIterator result_cb,
479 * Commit a set to be used with a set operation.
480 * This function is called once we have fully constructed
481 * the set that we want to use for the operation. At this
482 * time, the P2P protocol can then begin to exchange the
483 * set information and call the result callback with the
484 * result information.
486 * @param oh handle to the set operation
487 * @param set the set to use for the operation
488 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
489 * set is invalid (e.g. the set service crashed)
492 GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
493 struct GNUNET_SET_Handle *set);
497 * Cancel the given set operation. May not be called after the
498 * operation's `GNUNET_SET_ResultIterator` has been called with a
499 * status that indicates error, timeout or done.
501 * @param oh set operation to cancel
504 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
508 * Iterate over all elements in the given set.
509 * Note that this operation involves transferring every element of the set
510 * from the service to the client, and is thus costly.
511 * Only one iteration per set may be active at the same time.
513 * @param set the set to iterate over
514 * @param iter the iterator to call for each element
515 * @param iter_cls closure for @a iter
516 * @return #GNUNET_YES if the iteration started successfuly,
517 * #GNUNET_NO if another iteration was still active,
518 * #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
521 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
522 GNUNET_SET_ElementIterator iter,
526 * Stop iteration over all elements in the given set. Can only
527 * be called before the iteration has "naturally" completed its
530 * @param set the set to stop iterating over
533 GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
536 * Create a copy of an element. The copy
537 * must be GNUNET_free-d by the caller.
539 * @param element the element to copy
540 * @return the copied element
542 struct GNUNET_SET_Element *
543 GNUNET_SET_element_dup (const struct GNUNET_SET_Element *element);
546 * Hash a set element.
548 * @param element the element that should be hashed
549 * @param ret_hash a pointer to where the hash of @a element
553 GNUNET_SET_element_hash (const struct GNUNET_SET_Element *element, struct GNUNET_HashCode *ret_hash);
556 #if 0 /* keep Emacsens' auto-indent happy */
565 /** @} */ /* end of group */