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 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.
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.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @author Florian Dold
21 * @author Christian Grothoff
24 * Two-peer set operations
26 * @defgroup set Set service
27 * Two-peer set operations
29 * @see [Documentation](https://gnunet.org/set-subsystem)
34 #ifndef GNUNET_SET_SERVICE_H
35 #define GNUNET_SET_SERVICE_H
40 #if 0 /* keep Emacsens' auto-indent happy */
45 #include "gnunet_common.h"
46 #include "gnunet_time_lib.h"
47 #include "gnunet_configuration_lib.h"
51 * Maximum size of a context message for set operation requests.
53 #define GNUNET_SET_CONTEXT_MESSAGE_MAX_SIZE ((1<<16) - 1024)
57 * Opaque handle to a set.
59 struct GNUNET_SET_Handle;
62 * Opaque handle to a set operation request from another peer.
64 struct GNUNET_SET_Request;
67 * Opaque handle to a listen operation.
69 struct GNUNET_SET_ListenHandle;
72 * Opaque handle to a set operation.
74 struct GNUNET_SET_OperationHandle;
78 * The operation that a set set supports.
80 enum GNUNET_SET_OperationType
83 * A purely local set that does not support any operation.
85 GNUNET_SET_OPERATION_NONE,
88 * Set intersection, only return elements that are in both sets.
90 GNUNET_SET_OPERATION_INTERSECTION,
93 * Set union, return all elements that are in at least one of the sets.
95 GNUNET_SET_OPERATION_UNION
100 * Status for the result callback
102 enum GNUNET_SET_Status
105 * Everything went ok, we are transmitting an element of the
106 * result (in set, or to be removed from set, depending on
107 * the `enum GNUNET_SET_ResultMode`).
110 * #GNUNET_SET_RESULT_FULL,
111 * #GNUNET_SET_RESULT_ADDED,
112 * #GNUNET_SET_RESULT_REMOVED,
114 GNUNET_SET_STATUS_OK,
117 * Element should be added to the result set
118 * of the local peer, i.e. the local peer is
119 * missing an element.
121 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
123 GNUNET_SET_STATUS_ADD_LOCAL,
126 * Element should be added to the result set
127 * of the remote peer, i.e. the remote peer is
128 * missing an element.
130 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
132 GNUNET_SET_STATUS_ADD_REMOTE,
135 * The other peer refused to to the operation with us,
136 * or something went wrong.
138 GNUNET_SET_STATUS_FAILURE,
141 * Success, all elements have been returned (but the other peer
142 * might still be receiving some from us, so we are not done). Only
143 * used during UNION operation.
145 GNUNET_SET_STATUS_HALF_DONE,
148 * Success, all elements have been sent (and received).
150 GNUNET_SET_STATUS_DONE
156 * The way results are given to the client.
158 enum GNUNET_SET_ResultMode
161 * Client gets every element in the resulting set.
163 * Only supported for set intersection.
165 GNUNET_SET_RESULT_FULL,
168 * Client gets notified of the required changes
169 * for both the local and the remote set.
171 * Only supported for set
173 GNUNET_SET_RESULT_SYMMETRIC,
176 * Client gets only elements that have been removed from the set.
178 * Only supported for set intersection.
180 GNUNET_SET_RESULT_REMOVED,
183 * Client gets only elements that have been added to the set.
185 * Only supported for set union.
187 GNUNET_SET_RESULT_ADDED
192 * Element stored in a set.
194 struct GNUNET_SET_Element
197 * Number of bytes in the buffer pointed to by data.
202 * Application-specific element type.
204 uint16_t element_type;
207 * Actual data of the element
214 * Possible options to pass to a set operation.
216 * Used as tag for struct #GNUNET_SET_Option.
218 enum GNUNET_SET_OptionType
223 GNUNET_SET_OPTION_END=0,
225 * Fail set operations when the other peer shows weird behavior
226 * that might by a Byzantine fault.
228 * For set union, 'v.num' is a lower bound on elements
229 * that the other peer must have in common with us.
231 GNUNET_SET_OPTION_BYZANTINE=1,
233 * Do not use the optimized set operation, but send full sets.
234 * Might trigger Byzantine fault detection.
236 GNUNET_SET_OPTION_FORCE_FULL=2,
238 * Only use optimized set operations, even though for this
239 * particular set operation they might be much slower.
240 * Might trigger Byzantine fault detection.
242 GNUNET_SET_OPTION_FORCE_DELTA=4,
247 * Option for set operations.
249 struct GNUNET_SET_Option
252 * Type of the option.
254 enum GNUNET_SET_OptionType type;
257 * Value for the option, only used with some options.
266 * Continuation used for some of the set operations
271 (*GNUNET_SET_Continuation) (void *cls);
275 * Callback for set operation results. Called for each element
279 * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK
280 * @param current_size current set size
281 * @param status see `enum GNUNET_SET_Status`
284 (*GNUNET_SET_ResultIterator) (void *cls,
285 const struct GNUNET_SET_Element *element,
286 uint64_t current_size,
287 enum GNUNET_SET_Status status);
290 * Iterator for set elements.
293 * @param element the current element, NULL if all elements have been
295 * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop.
298 (*GNUNET_SET_ElementIterator) (void *cls,
299 const struct GNUNET_SET_Element *element);
303 * Called when another peer wants to do a set operation with the
304 * local peer. If a listen error occurs, the @a request is NULL.
307 * @param other_peer the other peer
308 * @param context_msg message with application specific information from
310 * @param request request from the other peer (never NULL), use GNUNET_SET_accept()
311 * to accept it, otherwise the request will be refused
312 * Note that we can't just return value from the listen callback,
313 * as it is also necessary to specify the set we want to do the
314 * operation with, whith sometimes can be derived from the context
315 * message. It's necessary to specify the timeout.
318 (*GNUNET_SET_ListenCallback) (void *cls,
319 const struct GNUNET_PeerIdentity *other_peer,
320 const struct GNUNET_MessageHeader *context_msg,
321 struct GNUNET_SET_Request *request);
326 (*GNUNET_SET_CopyReadyCallback) (void *cls,
327 struct GNUNET_SET_Handle *copy);
331 * Create an empty set, supporting the specified operation.
333 * @param cfg configuration to use for connecting to the
335 * @param op operation supported by the set
336 * Note that the operation has to be specified
337 * beforehand, as certain set operations need to maintain
338 * data structures spefific to the operation
339 * @return a handle to the set
341 struct GNUNET_SET_Handle *
342 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
343 enum GNUNET_SET_OperationType op);
347 * Add an element to the given set.
348 * After the element has been added (in the sense of being
349 * transmitted to the set service), @a cont will be called.
350 * Calls to #GNUNET_SET_add_element can be queued
352 * @param set set to add element to
353 * @param element element to add to the set
354 * @param cont continuation called after the element has been added
355 * @param cont_cls closure for @a cont
356 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
357 * set is invalid (e.g. the set service crashed)
360 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
361 const struct GNUNET_SET_Element *element,
362 GNUNET_SET_Continuation cont,
367 * Remove an element to the given set.
368 * After the element has been removed (in the sense of the
369 * request being transmitted to the set service), cont will be called.
370 * Calls to remove_element can be queued
372 * @param set set to remove element from
373 * @param element element to remove from the set
374 * @param cont continuation called after the element has been removed
375 * @param cont_cls closure for @a cont
376 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
377 * set is invalid (e.g. the set service crashed)
380 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
381 const struct GNUNET_SET_Element *element,
382 GNUNET_SET_Continuation cont,
387 GNUNET_SET_copy_lazy (struct GNUNET_SET_Handle *set,
388 GNUNET_SET_CopyReadyCallback cb,
393 * Destroy the set handle, and free all associated resources.
394 * Iterations must have completed (or be explicitly canceled)
395 * before destroying the corresponding set. Operations may
396 * still be pending when a set is destroyed.
398 * @param set set to destroy
401 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
405 * Prepare a set operation to be evaluated with another peer.
406 * The evaluation will not start until the client provides
407 * a local set with GNUNET_SET_commit().
409 * @param other_peer peer with the other set
410 * @param app_id hash for the application using the set
411 * @param context_msg additional information for the request
412 * @param result_mode specified how results will be returned,
413 * see `enum GNUNET_SET_ResultMode`.
414 * @param result_cb called on error or success
415 * @param result_cls closure for @a result_cb
416 * @return a handle to cancel the operation
418 struct GNUNET_SET_OperationHandle *
419 GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
420 const struct GNUNET_HashCode *app_id,
421 const struct GNUNET_MessageHeader *context_msg,
422 enum GNUNET_SET_ResultMode result_mode,
423 struct GNUNET_SET_Option options[],
424 GNUNET_SET_ResultIterator result_cb,
429 * Wait for set operation requests for the given application ID.
430 * If the connection to the set service is lost, the listener is
431 * re-created transparently with exponential backoff.
433 * @param cfg configuration to use for connecting to
435 * @param operation operation we want to listen for
436 * @param app_id id of the application that handles set operation requests
437 * @param listen_cb called for each incoming request matching the operation
439 * @param listen_cls handle for @a listen_cb
440 * @return a handle that can be used to cancel the listen operation
442 struct GNUNET_SET_ListenHandle *
443 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
444 enum GNUNET_SET_OperationType op_type,
445 const struct GNUNET_HashCode *app_id,
446 GNUNET_SET_ListenCallback listen_cb,
451 * Cancel the given listen operation. After calling cancel, the
452 * listen callback for this listen handle will not be called again.
453 * Note that cancelling a listen operation will automatically reject
454 * all operations that have not yet been accepted.
456 * @param lh handle for the listen operation
459 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
463 * Accept a request we got via GNUNET_SET_listen(). Must be called during
464 * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid
466 * Call GNUNET_SET_commit() to provide the local set to use for the operation,
467 * and to begin the exchange with the remote peer.
469 * @param request request to accept
470 * @param result_mode specified how results will be returned,
471 * see `enum GNUNET_SET_ResultMode`.
472 * @param result_cb callback for the results
473 * @param result_cls closure for @a result_cb
474 * @return a handle to cancel the operation
476 struct GNUNET_SET_OperationHandle *
477 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
478 enum GNUNET_SET_ResultMode result_mode,
479 struct GNUNET_SET_Option options[],
480 GNUNET_SET_ResultIterator result_cb,
485 * Commit a set to be used with a set operation.
486 * This function is called once we have fully constructed
487 * the set that we want to use for the operation. At this
488 * time, the P2P protocol can then begin to exchange the
489 * set information and call the result callback with the
490 * result information.
492 * @param oh handle to the set operation
493 * @param set the set to use for the operation
494 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
495 * set is invalid (e.g. the set service crashed)
498 GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
499 struct GNUNET_SET_Handle *set);
503 * Cancel the given set operation. May not be called after the
504 * operation's `GNUNET_SET_ResultIterator` has been called with a
505 * status that indicates error, timeout or done.
507 * @param oh set operation to cancel
510 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
514 * Iterate over all elements in the given set.
515 * Note that this operation involves transferring every element of the set
516 * from the service to the client, and is thus costly.
517 * Only one iteration per set may be active at the same time.
519 * @param set the set to iterate over
520 * @param iter the iterator to call for each element
521 * @param iter_cls closure for @a iter
522 * @return #GNUNET_YES if the iteration started successfuly,
523 * #GNUNET_NO if another iteration was still active,
524 * #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
527 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
528 GNUNET_SET_ElementIterator iter,
533 * Stop iteration over all elements in the given set. Can only
534 * be called before the iteration has "naturally" completed its
537 * @param set the set to stop iterating over
540 GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
544 * Create a copy of an element. The copy
545 * must be GNUNET_free-d by the caller.
547 * @param element the element to copy
548 * @return the copied element
550 struct GNUNET_SET_Element *
551 GNUNET_SET_element_dup (const struct GNUNET_SET_Element *element);
555 * Hash a set element.
557 * @param element the element that should be hashed
558 * @param ret_hash a pointer to where the hash of @a element
562 GNUNET_SET_element_hash (const struct GNUNET_SET_Element *element,
563 struct GNUNET_HashCode *ret_hash);
566 #if 0 /* keep Emacsens' auto-indent happy */
575 /** @} */ /* end of group */