diff options
author | Christian Grothoff <grothoff@gnunet.org> | 2022-03-12 04:01:02 +0100 |
---|---|---|
committer | Christian Grothoff <grothoff@gnunet.org> | 2022-03-12 04:01:02 +0100 |
commit | ff992f47e6528b00937c3951b812f6938e1ee21a (patch) | |
tree | 96917d63e24d2cc02b0e09a4e1dc29987541ffe8 /src/include | |
parent | 06f6791f2d55ab3a1b4ca4c3ba9ed5c315f8d79b (diff) | |
download | gnunet-ff992f47e6528b00937c3951b812f6938e1ee21a.tar.gz gnunet-ff992f47e6528b00937c3951b812f6938e1ee21a.zip |
revise block API to match latest DHT specs
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_block_lib.h | 136 | ||||
-rw-r--r-- | src/include/gnunet_block_plugin.h | 61 |
2 files changed, 24 insertions, 173 deletions
diff --git a/src/include/gnunet_block_lib.h b/src/include/gnunet_block_lib.h index f6db8d642..463c7af9f 100644 --- a/src/include/gnunet_block_lib.h +++ b/src/include/gnunet_block_lib.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet. | 2 | This file is part of GNUnet. |
3 | Copyright (C) 2010 GNUnet e.V. | 3 | Copyright (C) 2010, 2022 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software: you can redistribute it and/or modify it | 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 | 6 | under the terms of the GNU Affero General Public License as published |
@@ -162,108 +162,35 @@ enum GNUNET_BLOCK_Type | |||
162 | 162 | ||
163 | 163 | ||
164 | /** | 164 | /** |
165 | * Flags that can be set to control the evaluation. | ||
166 | * @deprecated | ||
167 | */ | ||
168 | enum GNUNET_BLOCK_EvaluationOptions | ||
169 | { | ||
170 | /** | ||
171 | * Default behavior. | ||
172 | */ | ||
173 | GNUNET_BLOCK_EO_NONE = 0, | ||
174 | |||
175 | /** | ||
176 | * The block is obtained from the local database, skip cryptographic | ||
177 | * checks. | ||
178 | */ | ||
179 | GNUNET_BLOCK_EO_LOCAL_SKIP_CRYPTO = 1 | ||
180 | }; | ||
181 | |||
182 | |||
183 | /** | ||
184 | * Possible ways for how a block may relate to a query. | 165 | * Possible ways for how a block may relate to a query. |
185 | * @deprecated | ||
186 | */ | 166 | */ |
187 | enum GNUNET_BLOCK_EvaluationResult | 167 | enum GNUNET_BLOCK_ReplyEvaluationResult |
188 | { | 168 | { |
189 | /** | ||
190 | * Valid result, and there may be more. | ||
191 | */ | ||
192 | GNUNET_BLOCK_EVALUATION_OK_MORE = 0, | ||
193 | 169 | ||
194 | /** | 170 | /** |
195 | * Last possible valid result. | 171 | * Specified block type not supported by any plugin. |
196 | */ | 172 | */ |
197 | GNUNET_BLOCK_EVALUATION_OK_LAST = 1, | 173 | GNUNET_BLOCK_REPLY_TYPE_NOT_SUPPORTED = -1, |
198 | 174 | ||
199 | /** | 175 | /** |
200 | * Valid result, but suppressed because it is a duplicate. | 176 | * Valid result, but suppressed because it is a duplicate. |
201 | */ | 177 | */ |
202 | GNUNET_BLOCK_EVALUATION_OK_DUPLICATE = 2, | 178 | GNUNET_BLOCK_REPLY_OK_DUPLICATE = 0, |
203 | |||
204 | /** | ||
205 | * Block does not match query (invalid result) | ||
206 | */ | ||
207 | GNUNET_BLOCK_EVALUATION_RESULT_INVALID = 3, | ||
208 | 179 | ||
209 | /** | 180 | /** |
210 | * Block does not match xquery (valid result, not relevant for the request) | 181 | * Block does not match xquery (valid result, not relevant for the request) |
211 | */ | 182 | */ |
212 | GNUNET_BLOCK_EVALUATION_RESULT_IRRELEVANT = 4, | 183 | GNUNET_BLOCK_REPLY_IRRELEVANT = 1, |
213 | |||
214 | /** | ||
215 | * Query is valid, no reply given. | ||
216 | */ | ||
217 | GNUNET_BLOCK_EVALUATION_REQUEST_VALID = 10, | ||
218 | |||
219 | /** | ||
220 | * Query format does not match block type (invalid query). For | ||
221 | * example, xquery not given or xquery_size not appropriate for | ||
222 | * type. | ||
223 | */ | ||
224 | GNUNET_BLOCK_EVALUATION_REQUEST_INVALID = 11, | ||
225 | |||
226 | /** | ||
227 | * Specified block type not supported by this plugin. | ||
228 | */ | ||
229 | GNUNET_BLOCK_EVALUATION_TYPE_NOT_SUPPORTED = 20 | ||
230 | }; | ||
231 | |||
232 | |||
233 | /** | ||
234 | * Possible ways for how a block may relate to a query. | ||
235 | */ | ||
236 | enum GNUNET_BLOCK_ReplyEvaluationResult | ||
237 | { | ||
238 | /** | ||
239 | * Valid result, but suppressed because it is a duplicate. | ||
240 | */ | ||
241 | GNUNET_BLOCK_REPLY_OK_DUPLICATE = 0, | ||
242 | 184 | ||
243 | /** | 185 | /** |
244 | * Valid result, and there may be more. | 186 | * Valid result, and there may be more. |
245 | */ | 187 | */ |
246 | GNUNET_BLOCK_REPLY_OK_MORE = 1, | 188 | GNUNET_BLOCK_REPLY_OK_MORE = 2, |
247 | 189 | ||
248 | /** | 190 | /** |
249 | * Last possible valid result. | 191 | * Last possible valid result. |
250 | */ | 192 | */ |
251 | GNUNET_BLOCK_REPLY_OK_LAST = 2, | 193 | GNUNET_BLOCK_REPLY_OK_LAST = 3 |
252 | |||
253 | /** | ||
254 | * Specified block type not supported by any plugin. | ||
255 | */ | ||
256 | GNUNET_BLOCK_REPLY_TYPE_NOT_SUPPORTED = -1, | ||
257 | |||
258 | /** | ||
259 | * Block does not match query (invalid result) | ||
260 | */ | ||
261 | GNUNET_BLOCK_REPLY_INVALID = -2, | ||
262 | |||
263 | /** | ||
264 | * Block does not match xquery (valid result, not relevant for the request) | ||
265 | */ | ||
266 | GNUNET_BLOCK_REPLY_IRRELEVANT = -3, | ||
267 | 194 | ||
268 | }; | 195 | }; |
269 | 196 | ||
@@ -362,40 +289,8 @@ GNUNET_BLOCK_group_destroy (struct GNUNET_BLOCK_Group *bg); | |||
362 | 289 | ||
363 | 290 | ||
364 | /** | 291 | /** |
365 | * Function called to validate a reply or a request. For | 292 | * Function called to validate if a reply is good for a |
366 | * request evaluation, simply pass "NULL" for the @a reply_block. | 293 | * particular query. |
367 | * Note that it is assumed that the reply has already been | ||
368 | * matched to the key (and signatures checked) as it would | ||
369 | * be done with the #GNUNET_BLOCK_get_key() function. | ||
370 | * | ||
371 | * @param ctx block contxt | ||
372 | * @param type block type | ||
373 | * @param group block group to use for evaluation | ||
374 | * @param eo evaluation options to control evaluation | ||
375 | * @param query original query (hash) | ||
376 | * @param xquery extrended query data (can be NULL, depending on type) | ||
377 | * @param xquery_size number of bytes in @a xquery | ||
378 | * @param reply_block response to validate | ||
379 | * @param reply_block_size number of bytes in @a reply_block | ||
380 | * @return characterization of result | ||
381 | * @deprecated | ||
382 | */ | ||
383 | enum GNUNET_BLOCK_EvaluationResult | ||
384 | GNUNET_BLOCK_evaluate (struct GNUNET_BLOCK_Context *ctx, | ||
385 | enum GNUNET_BLOCK_Type type, | ||
386 | struct GNUNET_BLOCK_Group *group, | ||
387 | enum GNUNET_BLOCK_EvaluationOptions eo, | ||
388 | const struct GNUNET_HashCode *query, | ||
389 | const void *xquery, | ||
390 | size_t xquery_size, | ||
391 | const void *reply_block, | ||
392 | size_t reply_block_size); | ||
393 | |||
394 | |||
395 | /** | ||
396 | * Function called to validate a reply. | ||
397 | * Also checks the query key against the block contents | ||
398 | * as it would be done with the #GNUNET_BLOCK_get_key() function. | ||
399 | * | 294 | * |
400 | * @param ctx block contxt | 295 | * @param ctx block contxt |
401 | * @param type block type | 296 | * @param type block type |
@@ -442,7 +337,6 @@ GNUNET_BLOCK_check_query (struct GNUNET_BLOCK_Context *ctx, | |||
442 | * | 337 | * |
443 | * @param ctx block contxt | 338 | * @param ctx block contxt |
444 | * @param type block type | 339 | * @param type block type |
445 | * @param query query key (hash) | ||
446 | * @param block payload to put | 340 | * @param block payload to put |
447 | * @param block_size number of bytes in @a block | 341 | * @param block_size number of bytes in @a block |
448 | * @return #GNUNET_OK if the block is fine, #GNUNET_NO if not, | 342 | * @return #GNUNET_OK if the block is fine, #GNUNET_NO if not, |
@@ -451,13 +345,14 @@ GNUNET_BLOCK_check_query (struct GNUNET_BLOCK_Context *ctx, | |||
451 | enum GNUNET_GenericReturnValue | 345 | enum GNUNET_GenericReturnValue |
452 | GNUNET_BLOCK_check_block (struct GNUNET_BLOCK_Context *ctx, | 346 | GNUNET_BLOCK_check_block (struct GNUNET_BLOCK_Context *ctx, |
453 | enum GNUNET_BLOCK_Type type, | 347 | enum GNUNET_BLOCK_Type type, |
454 | const struct GNUNET_HashCode *query, | ||
455 | const void *block, | 348 | const void *block, |
456 | size_t block_size); | 349 | size_t block_size); |
457 | 350 | ||
458 | 351 | ||
459 | /** | 352 | /** |
460 | * Function called to obtain the key for a block. | 353 | * Function called to obtain the @a key for a @a block. |
354 | * If the @a block is malformed, the function should | ||
355 | * zero-out @a key and return #GNUNET_OK. | ||
461 | * | 356 | * |
462 | * @param ctx block context | 357 | * @param ctx block context |
463 | * @param type block type | 358 | * @param type block type |
@@ -465,9 +360,8 @@ GNUNET_BLOCK_check_block (struct GNUNET_BLOCK_Context *ctx, | |||
465 | * @param block_size number of bytes in @a block | 360 | * @param block_size number of bytes in @a block |
466 | * @param key set to the key (query) for the given block | 361 | * @param key set to the key (query) for the given block |
467 | * @return #GNUNET_YES on success, | 362 | * @return #GNUNET_YES on success, |
468 | * #GNUNET_NO if the block is malformed | 363 | * #GNUNET_NO if extracting a key from a block of this @a type does not work |
469 | * #GNUNET_SYSERR if type not supported | 364 | * #GNUNET_SYSERR if @a type not supported |
470 | * (or if extracting a key from a block of this type does not work) | ||
471 | */ | 365 | */ |
472 | enum GNUNET_GenericReturnValue | 366 | enum GNUNET_GenericReturnValue |
473 | GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx, | 367 | GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx, |
diff --git a/src/include/gnunet_block_plugin.h b/src/include/gnunet_block_plugin.h index 2c9a3839d..1fa7ccf8b 100644 --- a/src/include/gnunet_block_plugin.h +++ b/src/include/gnunet_block_plugin.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet | 2 | This file is part of GNUnet |
3 | Copyright (C) 2010,2013,2017 GNUnet e.V. | 3 | Copyright (C) 2010, 2013, 2017, 2021, 2022 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software: you can redistribute it and/or modify it | 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 | 6 | under the terms of the GNU Affero General Public License as published |
@@ -163,43 +163,9 @@ typedef struct GNUNET_BLOCK_Group * | |||
163 | 163 | ||
164 | 164 | ||
165 | /** | 165 | /** |
166 | * Function called to validate a reply or a request. For | ||
167 | * request evaluation, simply pass "NULL" for the @a reply_block. | ||
168 | * Note that it is assumed that the reply has already been | ||
169 | * matched to the key (and signatures checked) as it would | ||
170 | * be done with the "get_key" function. | ||
171 | * | ||
172 | * @param cls closure | ||
173 | * @param ctx block context | ||
174 | * @param type block type | ||
175 | * @param group which block group to use for evaluation | ||
176 | * @param eo evaluation options to control evaluation | ||
177 | * @param query original query (hash) | ||
178 | * @param xquery extrended query data (can be NULL, depending on type) | ||
179 | * @param xquery_size number of bytes in @a xquery | ||
180 | * @param reply_block response to validate | ||
181 | * @param reply_block_size number of bytes in @a reply_block | ||
182 | * @return characterization of result | ||
183 | * @deprecated | ||
184 | */ | ||
185 | typedef enum GNUNET_BLOCK_EvaluationResult | ||
186 | (*GNUNET_BLOCK_EvaluationFunction)(void *cls, | ||
187 | struct GNUNET_BLOCK_Context *ctx, | ||
188 | enum GNUNET_BLOCK_Type type, | ||
189 | struct GNUNET_BLOCK_Group *group, | ||
190 | enum GNUNET_BLOCK_EvaluationOptions eo, | ||
191 | const struct GNUNET_HashCode *query, | ||
192 | const void *xquery, | ||
193 | size_t xquery_size, | ||
194 | const void *reply_block, | ||
195 | size_t reply_block_size); | ||
196 | |||
197 | |||
198 | /** | ||
199 | * Function called to validate a query. | 166 | * Function called to validate a query. |
200 | * | 167 | * |
201 | * @param cls closure | 168 | * @param cls closure |
202 | * @param ctx block context | ||
203 | * @param type block type | 169 | * @param type block type |
204 | * @param query original query (hash) | 170 | * @param query original query (hash) |
205 | * @param xquery extrended query data (can be NULL, depending on type) | 171 | * @param xquery extrended query data (can be NULL, depending on type) |
@@ -215,19 +181,17 @@ typedef enum GNUNET_GenericReturnValue | |||
215 | 181 | ||
216 | 182 | ||
217 | /** | 183 | /** |
218 | * Function called to validate a block for storage. | 184 | * Function called to validate a @a block for storage. |
219 | * | 185 | * |
220 | * @param cls closure | 186 | * @param cls closure |
221 | * @param type block type | 187 | * @param type block type |
222 | * @param query key for the block (hash), must match exactly | ||
223 | * @param block block data to validate | 188 | * @param block block data to validate |
224 | * @param block_size number of bytes in @a block | 189 | * @param block_size number of bytes in @a block |
225 | * @return #GNUNET_OK if the block is fine, #GNUNET_NO if not | 190 | * @return #GNUNET_OK if the @a block is fine, #GNUNET_NO if not, #GNUNET_SYSERR if the @a type is not supported |
226 | */ | 191 | */ |
227 | typedef enum GNUNET_GenericReturnValue | 192 | typedef enum GNUNET_GenericReturnValue |
228 | (*GNUNET_BLOCK_BlockEvaluationFunction)(void *cls, | 193 | (*GNUNET_BLOCK_BlockEvaluationFunction)(void *cls, |
229 | enum GNUNET_BLOCK_Type type, | 194 | enum GNUNET_BLOCK_Type type, |
230 | const struct GNUNET_HashCode *query, | ||
231 | const void *block, | 195 | const void *block, |
232 | size_t block_size); | 196 | size_t block_size); |
233 | 197 | ||
@@ -260,17 +224,18 @@ typedef enum GNUNET_BLOCK_ReplyEvaluationResult | |||
260 | 224 | ||
261 | 225 | ||
262 | /** | 226 | /** |
263 | * Function called to obtain the key for a block. | 227 | * Function called to obtain the @a key for a block. |
228 | * If the @a block is malformed, the function should | ||
229 | * zero-out @a key and return #GNUNET_OK. | ||
264 | * | 230 | * |
265 | * @param cls closure | 231 | * @param cls closure |
266 | * @param type block type | 232 | * @param type block type |
267 | * @param block block to get the key for | 233 | * @param block block to get the @a key for |
268 | * @param block_size number of bytes in @a block | 234 | * @param block_size number of bytes in @a block |
269 | * @param[out] key set to the key (query) for the given block | 235 | * @param[out] key set to the key (query) for the given block |
270 | * @return #GNUNET_YES on success, | 236 | * @return #GNUNET_YES on success, |
271 | * #GNUNET_NO if the block is malformed | 237 | * #GNUNET_NO if extracting a key for this @a type does not work |
272 | * #GNUNET_SYSERR if type not supported | 238 | * #GNUNET_SYSERR if @a type not supported |
273 | * (or if extracting a key from a block of this type does not work) | ||
274 | */ | 239 | */ |
275 | typedef enum GNUNET_GenericReturnValue | 240 | typedef enum GNUNET_GenericReturnValue |
276 | (*GNUNET_BLOCK_GetKeyFunction) (void *cls, | 241 | (*GNUNET_BLOCK_GetKeyFunction) (void *cls, |
@@ -297,14 +262,6 @@ struct GNUNET_BLOCK_PluginFunctions | |||
297 | const enum GNUNET_BLOCK_Type *types; | 262 | const enum GNUNET_BLOCK_Type *types; |
298 | 263 | ||
299 | /** | 264 | /** |
300 | * Main function of a block plugin. Allows us to check if a | ||
301 | * block matches a query. | ||
302 | * | ||
303 | * @param deprecated | ||
304 | */ | ||
305 | GNUNET_BLOCK_EvaluationFunction evaluate; | ||
306 | |||
307 | /** | ||
308 | * Obtain the key for a given block (if possible). | 265 | * Obtain the key for a given block (if possible). |
309 | */ | 266 | */ |
310 | GNUNET_BLOCK_GetKeyFunction get_key; | 267 | GNUNET_BLOCK_GetKeyFunction get_key; |