aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_setu_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_setu_service.h')
-rw-r--r--src/include/gnunet_setu_service.h378
1 files changed, 378 insertions, 0 deletions
diff --git a/src/include/gnunet_setu_service.h b/src/include/gnunet_setu_service.h
new file mode 100644
index 000000000..092c03198
--- /dev/null
+++ b/src/include/gnunet_setu_service.h
@@ -0,0 +1,378 @@
1/*
2 This file is part of GNUnet
3 Copyright (C) 2013, 2014, 2020 GNUnet e.V.
4
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.
9
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.
14
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/>.
17
18 SPDX-License-Identifier: AGPL3.0-or-later
19 */
20/**
21 * @author Florian Dold
22 * @author Christian Grothoff
23 *
24 * @file
25 * Two-peer set operations
26 *
27 * @defgroup set Set service
28 * Two-peer set operations
29 *
30 * @{
31 */
32
33#ifndef GNUNET_SETU_SERVICE_H
34#define GNUNET_SETU_SERVICE_H
35
36#ifdef __cplusplus
37extern "C"
38{
39#if 0 /* keep Emacsens' auto-indent happy */
40}
41#endif
42#endif
43
44#include "gnunet_common.h"
45#include "gnunet_time_lib.h"
46#include "gnunet_configuration_lib.h"
47
48
49/**
50 * Maximum size of a context message for set operation requests.
51 */
52#define GNUNET_SETU_CONTEXT_MESSAGE_MAX_SIZE ((1 << 16) - 1024)
53
54/**
55 * Opaque handle to a set.
56 */
57struct GNUNET_SETU_Handle;
58
59/**
60 * Opaque handle to a set operation request from another peer.
61 */
62struct GNUNET_SETU_Request;
63
64/**
65 * Opaque handle to a listen operation.
66 */
67struct GNUNET_SETU_ListenHandle;
68
69/**
70 * Opaque handle to a set operation.
71 */
72struct GNUNET_SETU_OperationHandle;
73
74
75/**
76 * Status for the result callback
77 */
78enum GNUNET_SETU_Status
79{
80
81 /**
82 * Element should be added to the result set of the local peer, i.e. the
83 * local peer is missing an element.
84 */
85 GNUNET_SETU_STATUS_ADD_LOCAL,
86
87 /**
88 * The other peer refused to do the operation with us, or something went
89 * wrong.
90 */
91 GNUNET_SETU_STATUS_FAILURE,
92
93 /**
94 * Success, all elements have been sent (and received).
95 */
96 GNUNET_SETU_STATUS_DONE
97};
98
99
100/**
101 * Element stored in a set.
102 */
103struct GNUNET_SETU_Element
104{
105 /**
106 * Number of bytes in the buffer pointed to by data.
107 */
108 uint16_t size;
109
110 /**
111 * Application-specific element type.
112 */
113 uint16_t element_type;
114
115 /**
116 * Actual data of the element
117 */
118 const void *data;
119};
120
121
122/**
123 * Possible options to pass to a set operation.
124 *
125 * Used as tag for struct #GNUNET_SETU_Option.
126 */
127enum GNUNET_SETU_OptionType
128{
129 /**
130 * List terminator.
131 */
132 GNUNET_SETU_OPTION_END=0,
133
134 /**
135 * Fail set operations when the other peer shows weird behavior
136 * that might by a Byzantine fault.
137 *
138 * For set union, 'v.num' is a lower bound on elements that the other peer
139 * must have in common with us.
140 */
141 GNUNET_SETU_OPTION_BYZANTINE=1,
142
143 /**
144 * Do not use the optimized set operation, but send full sets. Might
145 * trigger Byzantine fault detection.
146 */
147 GNUNET_SETU_OPTION_FORCE_FULL=2,
148
149 /**
150 * Only use optimized set operations, even though for this particular set
151 * operation they might be much slower. Might trigger Byzantine fault
152 * detection.
153 */
154 GNUNET_SETU_OPTION_FORCE_DELTA=4,
155};
156
157
158/**
159 * Option for set operations.
160 */
161struct GNUNET_SETU_Option
162{
163 /**
164 * Type of the option.
165 */
166 enum GNUNET_SETU_OptionType type;
167
168 /**
169 * Value for the option, only used with some options.
170 */
171 union
172 {
173 uint64_t num;
174 } v;
175};
176
177
178/**
179 * Callback for set union operation results. Called for each element
180 * in the result set.
181 *
182 * @param cls closure
183 * @param element a result element, only valid if status is #GNUNET_SETU_STATUS_OK
184 * @param current_size current set size
185 * @param status see `enum GNUNET_SETU_Status`
186 */
187typedef void
188(*GNUNET_SETU_ResultIterator) (void *cls,
189 const struct GNUNET_SETU_Element *element,
190 uint64_t current_size,
191 enum GNUNET_SETU_Status status);
192
193
194/**
195 * Called when another peer wants to do a set operation with the
196 * local peer. If a listen error occurs, the @a request is NULL.
197 *
198 * @param cls closure
199 * @param other_peer the other peer
200 * @param context_msg message with application specific information from
201 * the other peer
202 * @param request request from the other peer (never NULL), use GNUNET_SETU_accept()
203 * to accept it, otherwise the request will be refused
204 * Note that we can't just return value from the listen callback,
205 * as it is also necessary to specify the set we want to do the
206 * operation with, whith sometimes can be derived from the context
207 * message. It's necessary to specify the timeout.
208 */
209typedef void
210(*GNUNET_SETU_ListenCallback) (void *cls,
211 const struct GNUNET_PeerIdentity *other_peer,
212 const struct GNUNET_MessageHeader *context_msg,
213 struct GNUNET_SETU_Request *request);
214
215
216/**
217 * Create an empty set, supporting the specified operation.
218 *
219 * @param cfg configuration to use for connecting to the
220 * set service
221 * @return a handle to the set
222 */
223struct GNUNET_SETU_Handle *
224GNUNET_SETU_create (const struct GNUNET_CONFIGURATION_Handle *cfg);
225
226
227/**
228 * Add an element to the given set.
229 *
230 * @param set set to add element to
231 * @param element element to add to the set
232 * @param cb function to call when finished, can be NULL
233 * @param cb_cls closure for @a cb
234 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
235 * set is invalid (e.g. the set service crashed)
236 */
237int
238GNUNET_SETU_add_element (struct GNUNET_SETU_Handle *set,
239 const struct GNUNET_SETU_Element *element,
240 GNUNET_SCHEDULER_TaskCallback cb,
241 void *cb_cls);
242
243
244/**
245 * Destroy the set handle, and free all associated resources. Operations may
246 * still be pending when a set is destroyed (and will be allowed to complete).
247 *
248 * @param set set to destroy
249 */
250void
251GNUNET_SETU_destroy (struct GNUNET_SETU_Handle *set);
252
253
254/**
255 * Prepare a set operation to be evaluated with another peer. The evaluation
256 * will not start until the client provides a local set with
257 * GNUNET_SETU_commit().
258 *
259 * @param other_peer peer with the other set
260 * @param app_id hash for the application using the set
261 * @param context_msg additional information for the request
262 * @param options options to use when processing the request
263 * @param result_cb called on error or success
264 * @param result_cls closure for @a result_cb
265 * @return a handle to cancel the operation
266 */
267struct GNUNET_SETU_OperationHandle *
268GNUNET_SETU_prepare (const struct GNUNET_PeerIdentity *other_peer,
269 const struct GNUNET_HashCode *app_id,
270 const struct GNUNET_MessageHeader *context_msg,
271 const struct GNUNET_SETU_Option options[],
272 GNUNET_SETU_ResultIterator result_cb,
273 void *result_cls);
274
275
276/**
277 * Wait for set operation requests for the given application ID.
278 * If the connection to the set service is lost, the listener is
279 * re-created transparently with exponential backoff.
280 *
281 * @param cfg configuration to use for connecting to
282 * the set service
283 * @param app_id id of the application that handles set operation requests
284 * @param listen_cb called for each incoming request matching the operation
285 * and application id
286 * @param listen_cls handle for @a listen_cb
287 * @return a handle that can be used to cancel the listen operation
288 */
289struct GNUNET_SETU_ListenHandle *
290GNUNET_SETU_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
291 const struct GNUNET_HashCode *app_id,
292 GNUNET_SETU_ListenCallback listen_cb,
293 void *listen_cls);
294
295
296/**
297 * Cancel the given listen operation. After calling cancel, the
298 * listen callback for this listen handle will not be called again.
299 * Note that cancelling a listen operation will automatically reject
300 * all operations that have not yet been accepted.
301 *
302 * @param lh handle for the listen operation
303 */
304void
305GNUNET_SETU_listen_cancel (struct GNUNET_SETU_ListenHandle *lh);
306
307
308/**
309 * Accept a request we got via GNUNET_SETU_listen(). Must be called during
310 * GNUNET_SETU_listen(), as the `struct GNUNET_SETU_Request` becomes invalid
311 * afterwards.
312 * Call GNUNET_SETU_commit() to provide the local set to use for the operation,
313 * and to begin the exchange with the remote peer.
314 *
315 * @param request request to accept
316 * @param options options to use when processing the request
317 * @param result_cb callback for the results
318 * @param result_cls closure for @a result_cb
319 * @return a handle to cancel the operation
320 */
321struct GNUNET_SETU_OperationHandle *
322GNUNET_SETU_accept (struct GNUNET_SETU_Request *request,
323 const struct GNUNET_SETU_Option options[],
324 GNUNET_SETU_ResultIterator result_cb,
325 void *result_cls);
326
327
328/**
329 * Commit a set to be used with a set operation.
330 * This function is called once we have fully constructed
331 * the set that we want to use for the operation. At this
332 * time, the P2P protocol can then begin to exchange the
333 * set information and call the result callback with the
334 * result information.
335 *
336 * @param oh handle to the set operation
337 * @param set the set to use for the operation
338 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
339 * set is invalid (e.g. the set service crashed)
340 */
341int
342GNUNET_SETU_commit (struct GNUNET_SETU_OperationHandle *oh,
343 struct GNUNET_SETU_Handle *set);
344
345
346/**
347 * Cancel the given set operation. May not be called after the operation's
348 * `GNUNET_SETU_ResultIterator` has been called with a status of
349 * #GNUNET_SETU_STATUS_FAILURE or #GNUNET_SETU_STATUS_DONE.
350 *
351 * @param oh set operation to cancel
352 */
353void
354GNUNET_SETU_operation_cancel (struct GNUNET_SETU_OperationHandle *oh);
355
356
357/**
358 * Hash a set element.
359 *
360 * @param element the element that should be hashed
361 * @param[out] ret_hash a pointer to where the hash of @a element
362 * should be stored
363 */
364void
365GNUNET_SETU_element_hash (const struct GNUNET_SETU_Element *element,
366 struct GNUNET_HashCode *ret_hash);
367
368
369#if 0 /* keep Emacsens' auto-indent happy */
370{
371#endif
372#ifdef __cplusplus
373}
374#endif
375
376#endif
377
378/** @} */ /* end of group */