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