diff options
author | t3sserakt <t3ss@posteo.de> | 2020-08-28 17:57:44 +0200 |
---|---|---|
committer | t3sserakt <t3ss@posteo.de> | 2020-08-28 17:57:53 +0200 |
commit | 2b552a5f5e85fab1c14af73735c0de61b46cc3dc (patch) | |
tree | 1ed739ddb116d77a7f2dfcc69c013f0eb9f731e7 /src/include/gnunet_seti_service.h | |
parent | 03f6a0233f72c2c4c3925f0d6f6f7a81987c6530 (diff) | |
parent | bbf9540c93da3c6b950920ee7eaae479c95403c5 (diff) | |
download | gnunet-2b552a5f5e85fab1c14af73735c0de61b46cc3dc.tar.gz gnunet-2b552a5f5e85fab1c14af73735c0de61b46cc3dc.zip |
Merge branch 'master' of ssh://gnunet.org/gnunet
Diffstat (limited to 'src/include/gnunet_seti_service.h')
-rw-r--r-- | src/include/gnunet_seti_service.h | 369 |
1 files changed, 369 insertions, 0 deletions
diff --git a/src/include/gnunet_seti_service.h b/src/include/gnunet_seti_service.h new file mode 100644 index 000000000..c0b6f41a5 --- /dev/null +++ b/src/include/gnunet_seti_service.h | |||
@@ -0,0 +1,369 @@ | |||
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 intersection operations | ||
26 | * | ||
27 | * @defgroup set Set intersection service | ||
28 | * Two-peer set operations | ||
29 | * | ||
30 | * @{ | ||
31 | */ | ||
32 | |||
33 | #ifndef GNUNET_SETI_SERVICE_H | ||
34 | #define GNUNET_SETI_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_SETI_CONTEXT_MESSAGE_MAX_SIZE ((1 << 16) - 1024) | ||
53 | |||
54 | /** | ||
55 | * Opaque handle to a set. | ||
56 | */ | ||
57 | struct GNUNET_SETI_Handle; | ||
58 | |||
59 | /** | ||
60 | * Opaque handle to a set operation request from another peer. | ||
61 | */ | ||
62 | struct GNUNET_SETI_Request; | ||
63 | |||
64 | /** | ||
65 | * Opaque handle to a listen operation. | ||
66 | */ | ||
67 | struct GNUNET_SETI_ListenHandle; | ||
68 | |||
69 | /** | ||
70 | * Opaque handle to a set operation. | ||
71 | */ | ||
72 | struct GNUNET_SETI_OperationHandle; | ||
73 | |||
74 | |||
75 | /** | ||
76 | * Status for the result callback | ||
77 | */ | ||
78 | enum GNUNET_SETI_Status | ||
79 | { | ||
80 | |||
81 | /** | ||
82 | * Element should be added to the result set of the local peer, i.e. the | ||
83 | * element is in the intersection. | ||
84 | */ | ||
85 | GNUNET_SETI_STATUS_ADD_LOCAL, | ||
86 | |||
87 | /** | ||
88 | * Element should be delete from the result set of the local peer, i.e. the | ||
89 | * local peer is having an element that is not in the intersection. | ||
90 | */ | ||
91 | GNUNET_SETI_STATUS_DEL_LOCAL, | ||
92 | |||
93 | /** | ||
94 | * The other peer refused to do the operation with us, or something went | ||
95 | * wrong. | ||
96 | */ | ||
97 | GNUNET_SETI_STATUS_FAILURE, | ||
98 | |||
99 | /** | ||
100 | * Success, all elements have been sent (and received). | ||
101 | */ | ||
102 | GNUNET_SETI_STATUS_DONE | ||
103 | }; | ||
104 | |||
105 | |||
106 | /** | ||
107 | * Element stored in a set. | ||
108 | */ | ||
109 | struct GNUNET_SETI_Element | ||
110 | { | ||
111 | /** | ||
112 | * Number of bytes in the buffer pointed to by data. | ||
113 | */ | ||
114 | uint16_t size; | ||
115 | |||
116 | /** | ||
117 | * Application-specific element type. | ||
118 | */ | ||
119 | uint16_t element_type; | ||
120 | |||
121 | /** | ||
122 | * Actual data of the element | ||
123 | */ | ||
124 | const void *data; | ||
125 | }; | ||
126 | |||
127 | |||
128 | /** | ||
129 | * Possible options to pass to a set operation. | ||
130 | * | ||
131 | * Used as tag for struct #GNUNET_SETI_Option. | ||
132 | */ | ||
133 | enum GNUNET_SETI_OptionType | ||
134 | { | ||
135 | /** | ||
136 | * List terminator. | ||
137 | */ | ||
138 | GNUNET_SETI_OPTION_END = 0, | ||
139 | |||
140 | /** | ||
141 | * Return the elements remaining in the intersection | ||
142 | * (#GNUNET_SETI_STATUS_ADD_LOCAL). If not given, the default is to return a | ||
143 | * list of the elements to be removed (#GNUNET_SETI_STATUS_DEL_LOCAL). | ||
144 | */ | ||
145 | GNUNET_SETI_OPTION_RETURN_INTERSECTION = 1, | ||
146 | }; | ||
147 | |||
148 | |||
149 | /** | ||
150 | * Option for set operations. | ||
151 | */ | ||
152 | struct GNUNET_SETI_Option | ||
153 | { | ||
154 | /** | ||
155 | * Type of the option. | ||
156 | */ | ||
157 | enum GNUNET_SETI_OptionType type; | ||
158 | |||
159 | /** | ||
160 | * Value for the option, only used with some options. | ||
161 | */ | ||
162 | union | ||
163 | { | ||
164 | uint64_t num; | ||
165 | } v; | ||
166 | }; | ||
167 | |||
168 | |||
169 | /** | ||
170 | * Callback for set union operation results. Called for each element | ||
171 | * in the result set. | ||
172 | * | ||
173 | * @param cls closure | ||
174 | * @param element a result element, only valid if status is #GNUNET_SETI_STATUS_OK | ||
175 | * @param current_size current set size | ||
176 | * @param status see `enum GNUNET_SETI_Status` | ||
177 | */ | ||
178 | typedef void | ||
179 | (*GNUNET_SETI_ResultIterator) (void *cls, | ||
180 | const struct GNUNET_SETI_Element *element, | ||
181 | uint64_t current_size, | ||
182 | enum GNUNET_SETI_Status status); | ||
183 | |||
184 | |||
185 | /** | ||
186 | * Called when another peer wants to do a set operation with the | ||
187 | * local peer. If a listen error occurs, the @a request is NULL. | ||
188 | * | ||
189 | * @param cls closure | ||
190 | * @param other_peer the other peer | ||
191 | * @param context_msg message with application specific information from | ||
192 | * the other peer | ||
193 | * @param request request from the other peer (never NULL), use GNUNET_SETI_accept() | ||
194 | * to accept it, otherwise the request will be refused | ||
195 | * Note that we can't just return value from the listen callback, | ||
196 | * as it is also necessary to specify the set we want to do the | ||
197 | * operation with, whith sometimes can be derived from the context | ||
198 | * message. It's necessary to specify the timeout. | ||
199 | */ | ||
200 | typedef void | ||
201 | (*GNUNET_SETI_ListenCallback) (void *cls, | ||
202 | const struct GNUNET_PeerIdentity *other_peer, | ||
203 | const struct GNUNET_MessageHeader *context_msg, | ||
204 | struct GNUNET_SETI_Request *request); | ||
205 | |||
206 | |||
207 | /** | ||
208 | * Create an empty set, supporting the specified operation. | ||
209 | * | ||
210 | * @param cfg configuration to use for connecting to the | ||
211 | * set service | ||
212 | * @return a handle to the set | ||
213 | */ | ||
214 | struct GNUNET_SETI_Handle * | ||
215 | GNUNET_SETI_create (const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
216 | |||
217 | |||
218 | /** | ||
219 | * Add an element to the given set. | ||
220 | * | ||
221 | * @param set set to add element to | ||
222 | * @param element element to add to the set | ||
223 | * @param cb function to call when finished, can be NULL | ||
224 | * @param cb_cls closure for @a cb | ||
225 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if the | ||
226 | * set is invalid (e.g. the set service crashed) | ||
227 | */ | ||
228 | int | ||
229 | GNUNET_SETI_add_element (struct GNUNET_SETI_Handle *set, | ||
230 | const struct GNUNET_SETI_Element *element, | ||
231 | GNUNET_SCHEDULER_TaskCallback cb, | ||
232 | void *cb_cls); | ||
233 | |||
234 | |||
235 | /** | ||
236 | * Destroy the set handle, and free all associated resources. Operations may | ||
237 | * still be pending when a set is destroyed (and will be allowed to complete). | ||
238 | * | ||
239 | * @param set set to destroy | ||
240 | */ | ||
241 | void | ||
242 | GNUNET_SETI_destroy (struct GNUNET_SETI_Handle *set); | ||
243 | |||
244 | |||
245 | /** | ||
246 | * Prepare a set operation to be evaluated with another peer. The evaluation | ||
247 | * will not start until the client provides a local set with | ||
248 | * GNUNET_SETI_commit(). | ||
249 | * | ||
250 | * @param other_peer peer with the other set | ||
251 | * @param app_id hash for the application using the set | ||
252 | * @param context_msg additional information for the request | ||
253 | * @param options options to use when processing the request | ||
254 | * @param result_cb called on error or success | ||
255 | * @param result_cls closure for @a result_cb | ||
256 | * @return a handle to cancel the operation | ||
257 | */ | ||
258 | struct GNUNET_SETI_OperationHandle * | ||
259 | GNUNET_SETI_prepare (const struct GNUNET_PeerIdentity *other_peer, | ||
260 | const struct GNUNET_HashCode *app_id, | ||
261 | const struct GNUNET_MessageHeader *context_msg, | ||
262 | const struct GNUNET_SETI_Option options[], | ||
263 | GNUNET_SETI_ResultIterator result_cb, | ||
264 | void *result_cls); | ||
265 | |||
266 | |||
267 | /** | ||
268 | * Wait for set operation requests for the given application ID. | ||
269 | * If the connection to the set service is lost, the listener is | ||
270 | * re-created transparently with exponential backoff. | ||
271 | * | ||
272 | * @param cfg configuration to use for connecting to | ||
273 | * the set service | ||
274 | * @param app_id id of the application that handles set operation requests | ||
275 | * @param listen_cb called for each incoming request matching the operation | ||
276 | * and application id | ||
277 | * @param listen_cls handle for @a listen_cb | ||
278 | * @return a handle that can be used to cancel the listen operation | ||
279 | */ | ||
280 | struct GNUNET_SETI_ListenHandle * | ||
281 | GNUNET_SETI_listen (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
282 | const struct GNUNET_HashCode *app_id, | ||
283 | GNUNET_SETI_ListenCallback listen_cb, | ||
284 | void *listen_cls); | ||
285 | |||
286 | |||
287 | /** | ||
288 | * Cancel the given listen operation. After calling cancel, the | ||
289 | * listen callback for this listen handle will not be called again. | ||
290 | * Note that cancelling a listen operation will automatically reject | ||
291 | * all operations that have not yet been accepted. | ||
292 | * | ||
293 | * @param lh handle for the listen operation | ||
294 | */ | ||
295 | void | ||
296 | GNUNET_SETI_listen_cancel (struct GNUNET_SETI_ListenHandle *lh); | ||
297 | |||
298 | |||
299 | /** | ||
300 | * Accept a request we got via GNUNET_SETI_listen(). Must be called during | ||
301 | * GNUNET_SETI_listen(), as the `struct GNUNET_SETI_Request` becomes invalid | ||
302 | * afterwards. | ||
303 | * Call GNUNET_SETI_commit() to provide the local set to use for the operation, | ||
304 | * and to begin the exchange with the remote peer. | ||
305 | * | ||
306 | * @param request request to accept | ||
307 | * @param options options to use when processing the request | ||
308 | * @param result_cb callback for the results | ||
309 | * @param result_cls closure for @a result_cb | ||
310 | * @return a handle to cancel the operation | ||
311 | */ | ||
312 | struct GNUNET_SETI_OperationHandle * | ||
313 | GNUNET_SETI_accept (struct GNUNET_SETI_Request *request, | ||
314 | const struct GNUNET_SETI_Option options[], | ||
315 | GNUNET_SETI_ResultIterator result_cb, | ||
316 | void *result_cls); | ||
317 | |||
318 | |||
319 | /** | ||
320 | * Commit a set to be used with a set operation. | ||
321 | * This function is called once we have fully constructed | ||
322 | * the set that we want to use for the operation. At this | ||
323 | * time, the P2P protocol can then begin to exchange the | ||
324 | * set information and call the result callback with the | ||
325 | * result information. | ||
326 | * | ||
327 | * @param oh handle to the set operation | ||
328 | * @param set the set to use for the operation | ||
329 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if the | ||
330 | * set is invalid (e.g. the set service crashed) | ||
331 | */ | ||
332 | int | ||
333 | GNUNET_SETI_commit (struct GNUNET_SETI_OperationHandle *oh, | ||
334 | struct GNUNET_SETI_Handle *set); | ||
335 | |||
336 | |||
337 | /** | ||
338 | * Cancel the given set operation. May not be called after the operation's | ||
339 | * `GNUNET_SETI_ResultIterator` has been called with a status of | ||
340 | * #GNUNET_SETI_STATUS_FAILURE or #GNUNET_SETI_STATUS_DONE. | ||
341 | * | ||
342 | * @param oh set operation to cancel | ||
343 | */ | ||
344 | void | ||
345 | GNUNET_SETI_operation_cancel (struct GNUNET_SETI_OperationHandle *oh); | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Hash a set element. | ||
350 | * | ||
351 | * @param element the element that should be hashed | ||
352 | * @param[out] ret_hash a pointer to where the hash of @a element | ||
353 | * should be stored | ||
354 | */ | ||
355 | void | ||
356 | GNUNET_SETI_element_hash (const struct GNUNET_SETI_Element *element, | ||
357 | struct GNUNET_HashCode *ret_hash); | ||
358 | |||
359 | |||
360 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
361 | { | ||
362 | #endif | ||
363 | #ifdef __cplusplus | ||
364 | } | ||
365 | #endif | ||
366 | |||
367 | #endif | ||
368 | |||
369 | /** @} */ /* end of group */ | ||