diff options
author | Christian Grothoff <christian@grothoff.org> | 2020-08-18 11:08:34 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2020-08-18 11:08:34 +0200 |
commit | 53cc51e0df6bcf1417ef058e0d5843c7f89933d5 (patch) | |
tree | 07e2c28fa9ed7e764aa02c2556cda1ffb4e0eec0 /src/include/gnunet_setu_service.h | |
parent | e856a517bde24b4766097bc5c424ec548d11e301 (diff) | |
download | gnunet-53cc51e0df6bcf1417ef058e0d5843c7f89933d5.tar.gz gnunet-53cc51e0df6bcf1417ef058e0d5843c7f89933d5.zip |
add missing header
Diffstat (limited to 'src/include/gnunet_setu_service.h')
-rw-r--r-- | src/include/gnunet_setu_service.h | 378 |
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 | ||
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 | * 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 | */ | ||
103 | struct 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 | */ | ||
127 | enum 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 | */ | ||
161 | struct 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 | */ | ||
187 | typedef 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 | */ | ||
209 | typedef 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 | */ | ||
223 | struct GNUNET_SETU_Handle * | ||
224 | GNUNET_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 | */ | ||
237 | int | ||
238 | GNUNET_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 | */ | ||
250 | void | ||
251 | GNUNET_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 | */ | ||
267 | struct GNUNET_SETU_OperationHandle * | ||
268 | GNUNET_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 | */ | ||
289 | struct GNUNET_SETU_ListenHandle * | ||
290 | GNUNET_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 | */ | ||
304 | void | ||
305 | GNUNET_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 | */ | ||
321 | struct GNUNET_SETU_OperationHandle * | ||
322 | GNUNET_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 | */ | ||
341 | int | ||
342 | GNUNET_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 | */ | ||
353 | void | ||
354 | GNUNET_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 | */ | ||
364 | void | ||
365 | GNUNET_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 */ | ||