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 2, 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
27 #ifndef GNUNET_SET_SERVICE_H
28 #define GNUNET_SET_SERVICE_H
33 #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 * Opaque handle to a set.
47 struct GNUNET_SET_Handle;
50 * Opaque handle to a set operation request from another peer.
52 struct GNUNET_SET_Request;
55 * Opaque handle to a listen operation.
57 struct GNUNET_SET_ListenHandle;
60 * Opaque handle to a set operation.
62 struct GNUNET_SET_OperationHandle;
66 * The operation that a set set supports.
68 enum GNUNET_SET_OperationType
71 * Set intersection, only return elements that are in both sets.
73 GNUNET_SET_OPERATION_INTERSECTION,
75 * Set union, return all elements that are in at least one of the sets.
77 GNUNET_SET_OPERATION_UNION
81 * Status for the result callback
83 enum GNUNET_SET_Status
91 * There was a timeout.
93 GNUNET_SET_STATUS_TIMEOUT,
96 * The other peer refused to to the operation with us,
97 * or something went wrong.
99 GNUNET_SET_STATUS_FAILURE,
102 * Success, all elements have been returned (but the other
103 * peer might still be receiving some from us, so we are not done).
105 GNUNET_SET_STATUS_HALF_DONE,
108 * Success, all elements have been sent (and received).
110 GNUNET_SET_STATUS_DONE
114 * The way results are given to the client.
116 enum GNUNET_SET_ResultMode
119 * Client gets every element in the resulting set.
121 GNUNET_SET_RESULT_FULL,
123 * Client gets only elements that have been added to the set.
124 * Only works with set union.
126 GNUNET_SET_RESULT_ADDED,
128 * Client gets only elements that have been removed from the set.
129 * Only works with set intersection.
131 GNUNET_SET_RESULT_REMOVED
135 * Element stored in a set.
137 struct GNUNET_SET_Element
140 * Number of bytes in the buffer pointed to by data.
145 * Application-specific element type.
150 * Actual data of the element
157 * Continuation used for some of the set operations
161 typedef void (*GNUNET_SET_Continuation) (void *cls);
165 * Callback for set operation results. Called for each element
169 * @param element a result element, only valid if status is GNUNET_SET_STATUS_OK
170 * @param status see enum GNUNET_SET_Status
172 typedef void (*GNUNET_SET_ResultIterator) (void *cls,
173 const struct GNUNET_SET_Element *element,
174 enum GNUNET_SET_Status status);
178 * Called when another peer wants to do a set operation with the
181 * @param other_peer the other peer
182 * @param context_msg message with application specific information from
184 * @param request request from the other peer, use GNUNET_SET_accept
185 * to accept it, otherwise the request will be refused
186 * Note that we don't use a return value here, as it is also
187 * necessary to specify the set we want to do the operation with,
188 * whith sometimes can be derived from the context message.
189 * Also necessary to specify the timeout.
192 (*GNUNET_SET_ListenCallback) (void *cls,
193 const struct GNUNET_PeerIdentity *other_peer,
194 const struct GNUNET_MessageHeader *context_msg,
195 struct GNUNET_SET_Request *request);
200 * Create an empty set, supporting the specified operation.
202 * @param cfg configuration to use for connecting to the
204 * @param op operation supported by the set
205 * Note that the operation has to be specified
206 * beforehand, as certain set operations need to maintain
207 * data structures spefific to the operation
208 * @return a handle to the set
210 struct GNUNET_SET_Handle *
211 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
212 enum GNUNET_SET_OperationType op);
216 * Add an element to the given set.
217 * After the element has been added (in the sense of being
218 * transmitted to the set service), cont will be called.
219 * Calls to add_element can be queued
221 * @param set set to add element to
222 * @param element element to add to the set
223 * @param cont continuation called after the element has been added
224 * @param cont_cls closure for cont
227 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
228 const struct GNUNET_SET_Element *element,
229 GNUNET_SET_Continuation cont,
234 * Remove an element to the given set.
235 * After the element has been removed (in the sense of the
236 * request being transmitted to the set service), cont will be called.
237 * Calls to remove_element can be queued
239 * @param set set to remove element from
240 * @param element element to remove from the set
241 * @param cont continuation called after the element has been removed
242 * @param cont_cls closure for cont
245 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
246 const struct GNUNET_SET_Element *element,
247 GNUNET_SET_Continuation cont,
252 * Destroy the set handle, and free all associated resources.
255 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
259 * Evaluate a set operation with our set and the set of another peer.
261 * @param set set to use
262 * @param salt salt for HKDF (explain more here)
263 * @param other_peer peer with the other set
264 * @param app_id hash for the application using the set
265 * @param context_msg additional information for the request
266 * @param salt salt used for the set operation; sometimes set operations
267 * fail due to hash collisions, using a different salt for each operation
268 * makes it harder for an attacker to exploit this
269 * @param timeout result_cb will be called with GNUNET_SET_STATUS_TIMEOUT
270 * if the operation is not done after the specified time; @deprecated
271 * @param result_mode specified how results will be returned,
272 * see 'GNUNET_SET_ResultMode'.
273 * @param result_cb called on error or success
274 * @param result_cls closure for result_cb
275 * @return a handle to cancel the operation
277 struct GNUNET_SET_OperationHandle *
278 GNUNET_SET_evaluate (struct GNUNET_SET_Handle *set,
279 const struct GNUNET_PeerIdentity *other_peer,
280 const struct GNUNET_HashCode *app_id,
281 const struct GNUNET_MessageHeader *context_msg,
283 struct GNUNET_TIME_Relative timeout,
284 enum GNUNET_SET_ResultMode result_mode,
285 GNUNET_SET_ResultIterator result_cb,
290 * Wait for set operation requests for the given application id
292 * @param cfg configuration to use for connecting to
294 * @param operation operation we want to listen for
295 * @param app_id id of the application that handles set operation requests
296 * @param listen_cb called for each incoming request matching the operation
298 * @param listen_cls handle for listen_cb
299 * @return a handle that can be used to cancel the listen operation
301 struct GNUNET_SET_ListenHandle *
302 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
303 enum GNUNET_SET_OperationType op_type,
304 const struct GNUNET_HashCode *app_id,
305 GNUNET_SET_ListenCallback listen_cb,
311 * Cancel the given listen operation.
313 * @param lh handle for the listen operation
316 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
321 * Accept a request we got via GNUNET_SET_listen.
323 * @param request request to accept
324 * @param set set used for the requested operation
325 * @param timeout timeout for the set operation, @deprecated
326 * @param result_mode specified how results will be returned,
327 * see 'GNUNET_SET_ResultMode'.
328 * @param result_cb callback for the results
329 * @param result_cls closure for result_cb
330 * @return a handle to cancel the operation
332 struct GNUNET_SET_OperationHandle *
333 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
334 struct GNUNET_SET_Handle *set,
335 struct GNUNET_TIME_Relative timeout,
336 enum GNUNET_SET_ResultMode result_mode,
337 GNUNET_SET_ResultIterator result_cb,
342 * Cancel the given set operation.
344 * @param oh set operation to cancel
347 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
350 #if 0 /* keep Emacsens' auto-indent happy */