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 * @author Florian Dold
23 * @author Christian Grothoff
26 * Two-peer set operations
28 * @defgroup set Set service
29 * Two-peer set operations
33 #ifndef GNUNET_SET_SERVICE_H
34 #define GNUNET_SET_SERVICE_H
39 #if 0 /* keep Emacsens' auto-indent happy */
44 #include "gnunet_common.h"
45 #include "gnunet_time_lib.h"
46 #include "gnunet_configuration_lib.h"
50 * Maximum size of a context message for set operation requests.
52 #define GNUNET_SET_CONTEXT_MESSAGE_MAX_SIZE ((1<<16) - 1024)
56 * Opaque handle to a set.
58 struct GNUNET_SET_Handle;
61 * Opaque handle to a set operation request from another peer.
63 struct GNUNET_SET_Request;
66 * Opaque handle to a listen operation.
68 struct GNUNET_SET_ListenHandle;
71 * Opaque handle to a set operation.
73 struct GNUNET_SET_OperationHandle;
77 * The operation that a set set supports.
79 enum GNUNET_SET_OperationType
82 * A purely local set that does not support any operation.
84 GNUNET_SET_OPERATION_NONE,
87 * Set intersection, only return elements that are in both sets.
89 GNUNET_SET_OPERATION_INTERSECTION,
92 * Set union, return all elements that are in at least one of the sets.
94 GNUNET_SET_OPERATION_UNION
99 * Status for the result callback
101 enum GNUNET_SET_Status
104 * Everything went ok, we are transmitting an element of the
105 * result (in set, or to be removed from set, depending on
106 * the `enum GNUNET_SET_ResultMode`).
109 * #GNUNET_SET_RESULT_FULL,
110 * #GNUNET_SET_RESULT_ADDED,
111 * #GNUNET_SET_RESULT_REMOVED,
113 GNUNET_SET_STATUS_OK,
116 * Element should be added to the result set
117 * of the local peer, i.e. the local peer is
118 * missing an element.
120 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
122 GNUNET_SET_STATUS_ADD_LOCAL,
125 * Element should be added to the result set
126 * of the remove peer, i.e. the remote peer is
127 * missing an element.
129 * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
131 GNUNET_SET_STATUS_ADD_REMOTE,
134 * The other peer refused to to the operation with us,
135 * or something went wrong.
137 GNUNET_SET_STATUS_FAILURE,
140 * Success, all elements have been returned (but the other peer
141 * might still be receiving some from us, so we are not done). Only
142 * used during UNION operation.
144 GNUNET_SET_STATUS_HALF_DONE,
147 * Success, all elements have been sent (and received).
149 GNUNET_SET_STATUS_DONE
154 * The way results are given to the client.
156 enum GNUNET_SET_ResultMode
159 * Client gets every element in the resulting set.
161 * Only supported for set intersection.
163 GNUNET_SET_RESULT_FULL,
166 * Client gets notified of the required changes
167 * for both the local and the remote set.
169 * Only supported for set
171 GNUNET_SET_RESULT_SYMMETRIC,
174 * Client gets only elements that have been removed from the set.
176 * Only supported for set intersection.
178 GNUNET_SET_RESULT_REMOVED,
181 * Client gets only elements that have been removed from the set.
183 * Only supported for set union.
185 GNUNET_SET_RESULT_ADDED
190 * Element stored in a set.
192 struct GNUNET_SET_Element
195 * Number of bytes in the buffer pointed to by data.
200 * Application-specific element type.
202 uint16_t element_type;
205 * Actual data of the element
212 * Continuation used for some of the set operations
216 typedef void (*GNUNET_SET_Continuation) (void *cls);
220 * Callback for set operation results. Called for each element
224 * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK
225 * @param status see `enum GNUNET_SET_Status`
227 typedef void (*GNUNET_SET_ResultIterator) (void *cls,
228 const struct GNUNET_SET_Element *element,
229 enum GNUNET_SET_Status status);
232 * Iterator for set elements.
235 * @param element the current element, NULL if all elements have been
237 * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop.
239 typedef int (*GNUNET_SET_ElementIterator) (void *cls,
240 const struct GNUNET_SET_Element *element);
244 * Called when another peer wants to do a set operation with the
245 * local peer. If a listen error occurs, the @a request is NULL.
248 * @param other_peer the other peer
249 * @param context_msg message with application specific information from
251 * @param request request from the other peer (never NULL), use GNUNET_SET_accept()
252 * to accept it, otherwise the request will be refused
253 * Note that we can't just return value from the listen callback,
254 * as it is also necessary to specify the set we want to do the
255 * operation with, whith sometimes can be derived from the context
256 * message. It's necessary to specify the timeout.
259 (*GNUNET_SET_ListenCallback) (void *cls,
260 const struct GNUNET_PeerIdentity *other_peer,
261 const struct GNUNET_MessageHeader *context_msg,
262 struct GNUNET_SET_Request *request);
267 (*GNUNET_SET_CopyReadyCallback) (void *cls,
268 struct GNUNET_SET_Handle *copy);
272 * Create an empty set, supporting the specified operation.
274 * @param cfg configuration to use for connecting to the
276 * @param op operation supported by the set
277 * Note that the operation has to be specified
278 * beforehand, as certain set operations need to maintain
279 * data structures spefific to the operation
280 * @return a handle to the set
282 struct GNUNET_SET_Handle *
283 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
284 enum GNUNET_SET_OperationType op);
288 * Add an element to the given set.
289 * After the element has been added (in the sense of being
290 * transmitted to the set service), @a cont will be called.
291 * Calls to #GNUNET_SET_add_element can be queued
293 * @param set set to add element to
294 * @param element element to add to the set
295 * @param cont continuation called after the element has been added
296 * @param cont_cls closure for @a cont
297 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
298 * set is invalid (e.g. the set service crashed)
301 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
302 const struct GNUNET_SET_Element *element,
303 GNUNET_SET_Continuation cont,
308 * Remove an element to the given set.
309 * After the element has been removed (in the sense of the
310 * request being transmitted to the set service), cont will be called.
311 * Calls to remove_element can be queued
313 * @param set set to remove element from
314 * @param element element to remove from the set
315 * @param cont continuation called after the element has been removed
316 * @param cont_cls closure for @a cont
317 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
318 * set is invalid (e.g. the set service crashed)
321 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
322 const struct GNUNET_SET_Element *element,
323 GNUNET_SET_Continuation cont,
328 GNUNET_SET_copy_lazy (struct GNUNET_SET_Handle *set,
329 GNUNET_SET_CopyReadyCallback cb,
334 * Destroy the set handle, and free all associated resources.
335 * Iterations must have completed (or be explicitly canceled)
336 * before destroying the corresponding set. Operations may
337 * still be pending when a set is destroyed.
339 * @param set set to destroy
342 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
346 * Prepare a set operation to be evaluated with another peer.
347 * The evaluation will not start until the client provides
348 * a local set with GNUNET_SET_commit().
350 * @param other_peer peer with the other set
351 * @param app_id hash for the application using the set
352 * @param context_msg additional information for the request
353 * @param result_mode specified how results will be returned,
354 * see `enum GNUNET_SET_ResultMode`.
355 * @param result_cb called on error or success
356 * @param result_cls closure for @a result_cb
357 * @return a handle to cancel the operation
359 struct GNUNET_SET_OperationHandle *
360 GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
361 const struct GNUNET_HashCode *app_id,
362 const struct GNUNET_MessageHeader *context_msg,
363 enum GNUNET_SET_ResultMode result_mode,
364 GNUNET_SET_ResultIterator result_cb,
369 * Wait for set operation requests for the given application ID.
370 * If the connection to the set service is lost, the listener is
371 * re-created transparently with exponential backoff.
373 * @param cfg configuration to use for connecting to
375 * @param operation operation we want to listen for
376 * @param app_id id of the application that handles set operation requests
377 * @param listen_cb called for each incoming request matching the operation
379 * @param listen_cls handle for @a listen_cb
380 * @return a handle that can be used to cancel the listen operation
382 struct GNUNET_SET_ListenHandle *
383 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
384 enum GNUNET_SET_OperationType op_type,
385 const struct GNUNET_HashCode *app_id,
386 GNUNET_SET_ListenCallback listen_cb,
391 * Cancel the given listen operation. After calling cancel, the
392 * listen callback for this listen handle will not be called again.
394 * @param lh handle for the listen operation
397 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
401 * Accept a request we got via GNUNET_SET_listen(). Must be called during
402 * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid
404 * Call GNUNET_SET_commit() to provide the local set to use for the operation,
405 * and to begin the exchange with the remote peer.
407 * @param request request to accept
408 * @param result_mode specified how results will be returned,
409 * see `enum GNUNET_SET_ResultMode`.
410 * @param result_cb callback for the results
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_accept (struct GNUNET_SET_Request *request,
416 enum GNUNET_SET_ResultMode result_mode,
417 GNUNET_SET_ResultIterator result_cb,
422 * Commit a set to be used with a set operation.
423 * This function is called once we have fully constructed
424 * the set that we want to use for the operation. At this
425 * time, the P2P protocol can then begin to exchange the
426 * set information and call the result callback with the
427 * result information.
429 * @param oh handle to the set operation
430 * @param set the set to use for the operation
431 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
432 * set is invalid (e.g. the set service crashed)
435 GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
436 struct GNUNET_SET_Handle *set);
440 * Cancel the given set operation. May not be called after the
441 * operation's `GNUNET_SET_ResultIterator` has been called with a
442 * status that indicates error, timeout or done.
444 * @param oh set operation to cancel
447 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
451 * Iterate over all elements in the given set.
452 * Note that this operation involves transferring every element of the set
453 * from the service to the client, and is thus costly.
454 * Only one iteration per set may be active at the same time.
456 * @param set the set to iterate over
457 * @param iter the iterator to call for each element
458 * @param iter_cls closure for @a iter
459 * @return #GNUNET_YES if the iteration started successfuly,
460 * #GNUNET_NO if another iteration was still active,
461 * #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
464 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
465 GNUNET_SET_ElementIterator iter,
469 * Stop iteration over all elements in the given set. Can only
470 * be called before the iteration has "naturally" completed its
473 * @param set the set to stop iterating over
476 GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
479 * Create a copy of an element. The copy
480 * must be GNUNET_free-d by the caller.
482 * @param element the element to copy
483 * @return the copied element
485 struct GNUNET_SET_Element *
486 GNUNET_SET_element_dup (const struct GNUNET_SET_Element *element);
489 * Hash a set element.
491 * @param element the element that should be hashed
492 * @param ret_hash a pointer to where the hash of @a element
496 GNUNET_SET_element_hash (const struct GNUNET_SET_Element *element, struct GNUNET_HashCode *ret_hash);
499 #if 0 /* keep Emacsens' auto-indent happy */
508 /** @} */ /* end of group */