2 This file is part of GNUnet
3 (C) 2013 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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, 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
80 GNUNET_SET_OPERATION_NONE,
83 * Set intersection, only return elements that are in both sets.
85 GNUNET_SET_OPERATION_INTERSECTION,
88 * Set union, return all elements that are in at least one of the sets.
90 GNUNET_SET_OPERATION_UNION
94 * Status for the result callback
96 enum GNUNET_SET_Status
101 GNUNET_SET_STATUS_OK,
104 * There was a timeout.
106 GNUNET_SET_STATUS_TIMEOUT,
109 * The other peer refused to to the operation with us,
110 * or something went wrong.
112 GNUNET_SET_STATUS_FAILURE,
115 * Success, all elements have been returned (but the other
116 * peer might still be receiving some from us, so we are not done).
118 GNUNET_SET_STATUS_HALF_DONE,
121 * Success, all elements have been sent (and received).
123 GNUNET_SET_STATUS_DONE
128 * The way results are given to the client.
130 enum GNUNET_SET_ResultMode
133 * Client gets every element in the resulting set.
135 GNUNET_SET_RESULT_FULL,
137 * Client gets only elements that have been added to the set.
138 * Only works with set union.
140 GNUNET_SET_RESULT_ADDED,
142 * Client gets only elements that have been removed from the set.
143 * Only works with set intersection.
145 GNUNET_SET_RESULT_REMOVED
150 * Element stored in a set.
152 struct GNUNET_SET_Element
155 * Number of bytes in the buffer pointed to by data.
160 * Application-specific element type.
165 * Actual data of the element
172 * Continuation used for some of the set operations
176 typedef void (*GNUNET_SET_Continuation) (void *cls);
180 * Callback for set operation results. Called for each element
184 * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK
185 * @param status see `enum GNUNET_SET_Status`
187 typedef void (*GNUNET_SET_ResultIterator) (void *cls,
188 const struct GNUNET_SET_Element *element,
189 enum GNUNET_SET_Status status);
192 * Iterator for set elements.
195 * @param element the current element, NULL if all elements have been
197 * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop.
199 typedef int (*GNUNET_SET_ElementIterator) (void *cls,
200 const struct GNUNET_SET_Element *element);
204 * Called when another peer wants to do a set operation with the
205 * local peer. If a listen error occurs, the @a request is NULL.
208 * @param other_peer the other peer
209 * @param context_msg message with application specific information from
211 * @param request request from the other peer (never NULL), use GNUNET_SET_accept()
212 * to accept it, otherwise the request will be refused
213 * Note that we can't just return value from the listen callback,
214 * as it is also necessary to specify the set we want to do the
215 * operation with, whith sometimes can be derived from the context
216 * message. It's necessary to specify the timeout.
219 (*GNUNET_SET_ListenCallback) (void *cls,
220 const struct GNUNET_PeerIdentity *other_peer,
221 const struct GNUNET_MessageHeader *context_msg,
222 struct GNUNET_SET_Request *request);
227 * Create an empty set, supporting the specified operation.
229 * @param cfg configuration to use for connecting to the
231 * @param op operation supported by the set
232 * Note that the operation has to be specified
233 * beforehand, as certain set operations need to maintain
234 * data structures spefific to the operation
235 * @return a handle to the set
237 struct GNUNET_SET_Handle *
238 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
239 enum GNUNET_SET_OperationType op);
243 * Add an element to the given set.
244 * After the element has been added (in the sense of being
245 * transmitted to the set service), @a cont will be called.
246 * Calls to #GNUNET_SET_add_element can be queued
248 * @param set set to add element to
249 * @param element element to add to the set
250 * @param cont continuation called after the element has been added
251 * @param cont_cls closure for @a cont
252 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
253 * set is invalid (e.g. the set service crashed)
256 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
257 const struct GNUNET_SET_Element *element,
258 GNUNET_SET_Continuation cont,
263 * Remove an element to the given set.
264 * After the element has been removed (in the sense of the
265 * request being transmitted to the set service), cont will be called.
266 * Calls to remove_element can be queued
268 * @param set set to remove element from
269 * @param element element to remove from the set
270 * @param cont continuation called after the element has been removed
271 * @param cont_cls closure for @a cont
272 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
273 * set is invalid (e.g. the set service crashed)
276 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
277 const struct GNUNET_SET_Element *element,
278 GNUNET_SET_Continuation cont,
283 * Destroy the set handle, and free all associated resources.
286 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
290 * Prepare a set operation to be evaluated with another peer.
291 * The evaluation will not start until the client provides
292 * a local set with GNUNET_SET_commit().
294 * @param other_peer peer with the other set
295 * @param app_id hash for the application using the set
296 * @param context_msg additional information for the request
297 * @param salt salt used for the set operation; sometimes set operations
298 * fail due to hash collisions, using a different salt for each operation
299 * makes it harder for an attacker to exploit this
300 * @param result_mode specified how results will be returned,
301 * see `enum GNUNET_SET_ResultMode`.
302 * @param result_cb called on error or success
303 * @param result_cls closure for @a result_cb
304 * @return a handle to cancel the operation
306 struct GNUNET_SET_OperationHandle *
307 GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
308 const struct GNUNET_HashCode *app_id,
309 const struct GNUNET_MessageHeader *context_msg,
311 enum GNUNET_SET_ResultMode result_mode,
312 GNUNET_SET_ResultIterator result_cb,
317 * Wait for set operation requests for the given application ID.
318 * If the connection to the set service is lost, the listener is
319 * re-created transparently with exponential backoff.
321 * @param cfg configuration to use for connecting to
323 * @param operation operation we want to listen for
324 * @param app_id id of the application that handles set operation requests
325 * @param listen_cb called for each incoming request matching the operation
327 * @param listen_cls handle for listen_cb
328 * @return a handle that can be used to cancel the listen operation
330 struct GNUNET_SET_ListenHandle *
331 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
332 enum GNUNET_SET_OperationType op_type,
333 const struct GNUNET_HashCode *app_id,
334 GNUNET_SET_ListenCallback listen_cb,
339 * Cancel the given listen operation.
340 * After calling cancel, the listen callback for this listen handle
341 * will not be called again.
343 * @param lh handle for the listen operation
346 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
350 * Accept a request we got via GNUNET_SET_listen(). Must be called during
351 * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid
353 * Call GNUNET_SET_commit() to provide the local set to use for the operation,
354 * and to begin the exchange with the remote peer.
356 * @param request request to accept
357 * @param result_mode specified how results will be returned,
358 * see `enum GNUNET_SET_ResultMode`.
359 * @param result_cb callback for the results
360 * @param result_cls closure for @a result_cb
361 * @return a handle to cancel the operation
363 struct GNUNET_SET_OperationHandle *
364 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
365 enum GNUNET_SET_ResultMode result_mode,
366 GNUNET_SET_ResultIterator result_cb,
371 * Commit a set to be used with a set operation.
372 * This function is called once we have fully constructed
373 * the set that we want to use for the operation. At this
374 * time, the P2P protocol can then begin to exchange the
375 * set information and call the result callback with the
376 * result information.
378 * @param oh handle to the set operation
379 * @param set the set to use for the operation
380 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
381 * set is invalid (e.g. the set service crashed)
384 GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
385 struct GNUNET_SET_Handle *set);
389 * Cancel the given set operation.
390 * May not be called after the operation's GNUNET_SET_ResultIterator has been
391 * called with a status that indicates error, timeout or done.
393 * @param oh set operation to cancel
396 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
400 * Iterate over all elements in the given set.
401 * Note that this operation involves transferring every element of the set
402 * from the service to the client, and is thus costly.
403 * Only one iteration per set may be active at the same time.
405 * @param set the set to iterate over
406 * @param iter the iterator to call for each element
407 * @param cls closure for 'iter'
408 * @return GNUNET_YES if the iteration started successfuly,
409 * GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
412 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set, GNUNET_SET_ElementIterator iter, void *cls);
415 #if 0 /* keep Emacsens' auto-indent happy */