diff options
Diffstat (limited to 'src/fs/gnunet-service-fs_pr.h')
-rw-r--r-- | src/fs/gnunet-service-fs_pr.h | 422 |
1 files changed, 0 insertions, 422 deletions
diff --git a/src/fs/gnunet-service-fs_pr.h b/src/fs/gnunet-service-fs_pr.h deleted file mode 100644 index 58fdd334e..000000000 --- a/src/fs/gnunet-service-fs_pr.h +++ /dev/null | |||
@@ -1,422 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2009, 2010, 2011 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 | /** | ||
22 | * @file fs/gnunet-service-fs_pr.h | ||
23 | * @brief API to handle pending requests | ||
24 | * @author Christian Grothoff | ||
25 | */ | ||
26 | #ifndef GNUNET_SERVICE_FS_PR_H | ||
27 | #define GNUNET_SERVICE_FS_PR_H | ||
28 | |||
29 | #include "gnunet-service-fs.h" | ||
30 | |||
31 | |||
32 | /** | ||
33 | * Options for pending requests (bits to be ORed). | ||
34 | */ | ||
35 | enum GSF_PendingRequestOptions | ||
36 | { | ||
37 | /** | ||
38 | * No special options (P2P-default). | ||
39 | */ | ||
40 | GSF_PRO_DEFAULTS = 0, | ||
41 | |||
42 | /** | ||
43 | * Request must only be processed locally. | ||
44 | */ | ||
45 | GSF_PRO_LOCAL_ONLY = 1, | ||
46 | |||
47 | /** | ||
48 | * Request must only be forwarded (no routing) | ||
49 | */ | ||
50 | GSF_PRO_FORWARD_ONLY = 2, | ||
51 | |||
52 | /** | ||
53 | * Request persists indefinitely (no expiration). | ||
54 | */ | ||
55 | GSF_PRO_REQUEST_NEVER_EXPIRES = 4, | ||
56 | |||
57 | /** | ||
58 | * Request is allowed to refresh bloomfilter and change mingle value. | ||
59 | */ | ||
60 | GSF_PRO_BLOOMFILTER_FULL_REFRESH = 8, | ||
61 | |||
62 | /** | ||
63 | * Request priority is allowed to be exceeded. | ||
64 | */ | ||
65 | GSF_PRO_PRIORITY_UNLIMITED = 16, | ||
66 | |||
67 | /** | ||
68 | * Option mask for typical local requests. | ||
69 | */ | ||
70 | GSF_PRO_LOCAL_REQUEST = | ||
71 | (GSF_PRO_BLOOMFILTER_FULL_REFRESH | GSF_PRO_PRIORITY_UNLIMITED | ||
72 | | GSF_PRO_REQUEST_NEVER_EXPIRES) | ||
73 | }; | ||
74 | |||
75 | |||
76 | /** | ||
77 | * Public data (in the sense of not encapsulated within | ||
78 | * 'gnunet-service-fs_pr', not in the sense of network-wide | ||
79 | * known) associated with each pending request. | ||
80 | */ | ||
81 | struct GSF_PendingRequestData | ||
82 | { | ||
83 | /** | ||
84 | * Primary query hash for this request. | ||
85 | */ | ||
86 | struct GNUNET_HashCode query; | ||
87 | |||
88 | /** | ||
89 | * Identity of a peer hosting the content, otherwise NULl. | ||
90 | * Allocated after struct only if needed. Do not free! | ||
91 | */ | ||
92 | const struct GNUNET_PeerIdentity *target; | ||
93 | |||
94 | /** | ||
95 | * Fields for the plan module to track a DLL with the request. | ||
96 | */ | ||
97 | struct GSF_PendingRequestPlanBijection *pr_head; | ||
98 | |||
99 | /** | ||
100 | * Fields for the plan module to track a DLL with the request. | ||
101 | */ | ||
102 | struct GSF_PendingRequestPlanBijection *pr_tail; | ||
103 | |||
104 | /** | ||
105 | * Current TTL for the request. | ||
106 | */ | ||
107 | struct GNUNET_TIME_Absolute ttl; | ||
108 | |||
109 | /** | ||
110 | * When did we start with the request. | ||
111 | */ | ||
112 | struct GNUNET_TIME_Absolute start_time; | ||
113 | |||
114 | /** | ||
115 | * Desired anonymity level. | ||
116 | */ | ||
117 | uint32_t anonymity_level; | ||
118 | |||
119 | /** | ||
120 | * Priority that this request (still) has for us. | ||
121 | */ | ||
122 | uint32_t priority; | ||
123 | |||
124 | /** | ||
125 | * Priority that this request (originally) had for us. | ||
126 | */ | ||
127 | uint32_t original_priority; | ||
128 | |||
129 | /** | ||
130 | * Counter for how often this request has been transmitted (estimate, | ||
131 | * because we might have the same request pending for multiple clients, | ||
132 | * and of course because a transmission may have failed at a lower | ||
133 | * layer). | ||
134 | */ | ||
135 | uint32_t num_transmissions; | ||
136 | |||
137 | /** | ||
138 | * How much respect did we (in total) offer for this request so far (estimate, | ||
139 | * because we might have the same request pending for multiple clients, | ||
140 | * and of course because a transmission may have failed at a lower | ||
141 | * layer). | ||
142 | */ | ||
143 | uint32_t respect_offered; | ||
144 | |||
145 | /** | ||
146 | * Options for the request. | ||
147 | */ | ||
148 | enum GSF_PendingRequestOptions options; | ||
149 | |||
150 | /** | ||
151 | * Type of the requested block. | ||
152 | */ | ||
153 | enum GNUNET_BLOCK_Type type; | ||
154 | |||
155 | /** | ||
156 | * Number of results we have found for this request so far. | ||
157 | */ | ||
158 | unsigned int results_found; | ||
159 | |||
160 | /** | ||
161 | * Has this request been started yet (local/p2p operations)? Or are | ||
162 | * we still constructing it? | ||
163 | */ | ||
164 | int has_started; | ||
165 | }; | ||
166 | |||
167 | |||
168 | /** | ||
169 | * Handle a reply to a pending request. Also called if a request | ||
170 | * expires (then with data == NULL). The handler may be called | ||
171 | * many times (depending on the request type), but will not be | ||
172 | * called during or after a call to GSF_pending_request_cancel | ||
173 | * and will also not be called anymore after a call signalling | ||
174 | * expiration. | ||
175 | * | ||
176 | * @param cls user-specified closure | ||
177 | * @param eval evaluation of the result | ||
178 | * @param pr handle to the original pending request | ||
179 | * @param reply_anonymity_level anonymity level for the reply, UINT32_MAX for "unknown" | ||
180 | * @param expiration when does @a data expire? | ||
181 | * @param last_transmission the last time we've tried to get this block (FOREVER if unknown) | ||
182 | * @param type type of the block | ||
183 | * @param data response data, NULL on request expiration | ||
184 | * @param data_len number of bytes in @a data | ||
185 | */ | ||
186 | typedef void | ||
187 | (*GSF_PendingRequestReplyHandler) (void *cls, | ||
188 | enum GNUNET_BLOCK_EvaluationResult eval, | ||
189 | struct GSF_PendingRequest *pr, | ||
190 | uint32_t reply_anonymity_level, | ||
191 | struct GNUNET_TIME_Absolute expiration, | ||
192 | struct GNUNET_TIME_Absolute | ||
193 | last_transmission, | ||
194 | enum GNUNET_BLOCK_Type type, | ||
195 | const void *data, | ||
196 | size_t data_len); | ||
197 | |||
198 | |||
199 | /** | ||
200 | * Create a new pending request. | ||
201 | * | ||
202 | * @param options request options | ||
203 | * @param type type of the block that is being requested | ||
204 | * @param query key for the lookup | ||
205 | * @param target preferred target for the request, NULL for none | ||
206 | * @param bf_data raw data for bloom filter for known replies, can be NULL | ||
207 | * @param bf_size number of bytes in bf_data | ||
208 | * @param mingle mingle value for bf | ||
209 | * @param anonymity_level desired anonymity level | ||
210 | * @param priority maximum outgoing cumulative request priority to use | ||
211 | * @param ttl current time-to-live for the request | ||
212 | * @param sender_pid peer ID to use for the sender when forwarding, 0 for none; | ||
213 | * reference counter is taken over by this function | ||
214 | * @param origin_pid peer ID of origin of query (do not loop back) | ||
215 | * @param replies_seen hash codes of known local replies | ||
216 | * @param replies_seen_count size of the 'replies_seen' array | ||
217 | * @param rh handle to call when we get a reply | ||
218 | * @param rh_cls closure for rh | ||
219 | * @return handle for the new pending request | ||
220 | */ | ||
221 | struct GSF_PendingRequest * | ||
222 | GSF_pending_request_create_ (enum GSF_PendingRequestOptions options, | ||
223 | enum GNUNET_BLOCK_Type type, | ||
224 | const struct GNUNET_HashCode *query, | ||
225 | const struct GNUNET_PeerIdentity *target, | ||
226 | const char *bf_data, | ||
227 | size_t bf_size, | ||
228 | uint32_t mingle, | ||
229 | uint32_t anonymity_level, | ||
230 | uint32_t priority, | ||
231 | int32_t ttl, | ||
232 | GNUNET_PEER_Id sender_pid, | ||
233 | GNUNET_PEER_Id origin_pid, | ||
234 | const struct GNUNET_HashCode *replies_seen, | ||
235 | unsigned int replies_seen_count, | ||
236 | GSF_PendingRequestReplyHandler rh, | ||
237 | void *rh_cls); | ||
238 | |||
239 | |||
240 | /** | ||
241 | * Update a given pending request with additional replies | ||
242 | * that have been seen. | ||
243 | * | ||
244 | * @param pr request to update | ||
245 | * @param replies_seen hash codes of replies that we've seen | ||
246 | * @param replies_seen_count size of the @a replies_seen array | ||
247 | */ | ||
248 | void | ||
249 | GSF_pending_request_update_ (struct GSF_PendingRequest *pr, | ||
250 | const struct GNUNET_HashCode *replies_seen, | ||
251 | unsigned int replies_seen_count); | ||
252 | |||
253 | |||
254 | /** | ||
255 | * Obtain the public data associated with a pending request | ||
256 | * | ||
257 | * @param pr pending request | ||
258 | * @return associated public data | ||
259 | */ | ||
260 | struct GSF_PendingRequestData * | ||
261 | GSF_pending_request_get_data_ (struct GSF_PendingRequest *pr); | ||
262 | |||
263 | |||
264 | /** | ||
265 | * Check if the given request is still active. | ||
266 | * | ||
267 | * @param pr pending request | ||
268 | * @return #GNUNET_YES if the request is still active | ||
269 | */ | ||
270 | int | ||
271 | GSF_pending_request_test_active_ (struct GSF_PendingRequest *pr); | ||
272 | |||
273 | |||
274 | /** | ||
275 | * Test if two pending requests are compatible (would generate | ||
276 | * the same query modulo filters and should thus be processed | ||
277 | * jointly). | ||
278 | * | ||
279 | * @param pra a pending request | ||
280 | * @param prb another pending request | ||
281 | * @return #GNUNET_OK if the requests are compatible | ||
282 | */ | ||
283 | int | ||
284 | GSF_pending_request_is_compatible_ (struct GSF_PendingRequest *pra, | ||
285 | struct GSF_PendingRequest *prb); | ||
286 | |||
287 | |||
288 | /** | ||
289 | * Generate the message corresponding to the given pending request for | ||
290 | * transmission to other peers. | ||
291 | * | ||
292 | * @param pr request to generate the message for | ||
293 | * @return envelope with the request message | ||
294 | */ | ||
295 | struct GNUNET_MQ_Envelope * | ||
296 | GSF_pending_request_get_message_ (struct GSF_PendingRequest *pr); | ||
297 | |||
298 | |||
299 | /** | ||
300 | * Explicitly cancel a pending request. | ||
301 | * | ||
302 | * @param pr request to cancel | ||
303 | * @param full_cleanup fully purge the request | ||
304 | */ | ||
305 | void | ||
306 | GSF_pending_request_cancel_ (struct GSF_PendingRequest *pr, | ||
307 | int full_cleanup); | ||
308 | |||
309 | |||
310 | /** | ||
311 | * Signature of function called on each request. | ||
312 | * (Note: 'subtype' of GNUNET_CONTAINER_HashMapIterator). | ||
313 | * | ||
314 | * @param cls closure | ||
315 | * @param key query for the request | ||
316 | * @param pr handle to the pending request | ||
317 | * @return #GNUNET_YES to continue to iterate | ||
318 | */ | ||
319 | typedef int | ||
320 | (*GSF_PendingRequestIterator) (void *cls, | ||
321 | const struct GNUNET_HashCode *key, | ||
322 | struct GSF_PendingRequest *pr); | ||
323 | |||
324 | |||
325 | /** | ||
326 | * Iterate over all pending requests. | ||
327 | * | ||
328 | * @param it function to call for each request | ||
329 | * @param cls closure for it | ||
330 | */ | ||
331 | void | ||
332 | GSF_iterate_pending_requests_ (GSF_PendingRequestIterator it, | ||
333 | void *cls); | ||
334 | |||
335 | |||
336 | /** | ||
337 | * Handle P2P "CONTENT" message. Checks that the message is | ||
338 | * well-formed and then checks if there are any pending requests for | ||
339 | * this content and possibly passes it on (to local clients or other | ||
340 | * peers). Does NOT perform migration (content caching at this peer). | ||
341 | * | ||
342 | * @param cls the other peer involved (sender) | ||
343 | * @param put the actual message | ||
344 | */ | ||
345 | void | ||
346 | handle_p2p_put (void *cls, | ||
347 | const struct PutMessage *put); | ||
348 | |||
349 | |||
350 | /** | ||
351 | * Consider looking up the data in the DHT (anonymity-level permitting). | ||
352 | * | ||
353 | * @param pr the pending request to process | ||
354 | */ | ||
355 | void | ||
356 | GSF_dht_lookup_ (struct GSF_PendingRequest *pr); | ||
357 | |||
358 | |||
359 | /** | ||
360 | * Consider downloading via cadet (if possible) | ||
361 | * | ||
362 | * @param pr the pending request to process | ||
363 | */ | ||
364 | void | ||
365 | GSF_cadet_lookup_ (struct GSF_PendingRequest *pr); | ||
366 | |||
367 | |||
368 | /** | ||
369 | * Function to be called after we're done processing | ||
370 | * replies from the local lookup. | ||
371 | * | ||
372 | * @param cls closure | ||
373 | * @param pr the pending request we were processing | ||
374 | * @param result final datastore lookup result | ||
375 | */ | ||
376 | typedef void | ||
377 | (*GSF_LocalLookupContinuation) (void *cls, | ||
378 | struct GSF_PendingRequest *pr, | ||
379 | enum GNUNET_BLOCK_EvaluationResult result); | ||
380 | |||
381 | |||
382 | /** | ||
383 | * Look up the request in the local datastore. | ||
384 | * | ||
385 | * @param pr the pending request to process | ||
386 | * @param cont function to call at the end | ||
387 | * @param cont_cls closure for @a cont | ||
388 | */ | ||
389 | void | ||
390 | GSF_local_lookup_ (struct GSF_PendingRequest *pr, | ||
391 | GSF_LocalLookupContinuation cont, | ||
392 | void *cont_cls); | ||
393 | |||
394 | |||
395 | /** | ||
396 | * Is the given target a legitimate peer for forwarding the given request? | ||
397 | * | ||
398 | * @param pr request | ||
399 | * @param target | ||
400 | * @return #GNUNET_YES if this request could be forwarded to the given peer | ||
401 | */ | ||
402 | int | ||
403 | GSF_pending_request_test_target_ (struct GSF_PendingRequest *pr, | ||
404 | const struct GNUNET_PeerIdentity *target); | ||
405 | |||
406 | |||
407 | /** | ||
408 | * Setup the subsystem. | ||
409 | */ | ||
410 | void | ||
411 | GSF_pending_request_init_ (void); | ||
412 | |||
413 | |||
414 | /** | ||
415 | * Shutdown the subsystem. | ||
416 | */ | ||
417 | void | ||
418 | GSF_pending_request_done_ (void); | ||
419 | |||
420 | |||
421 | #endif | ||
422 | /* end of gnunet-service-fs_pr.h */ | ||