diff options
Diffstat (limited to 'src/include/gnunet_block_plugin.h')
-rw-r--r-- | src/include/gnunet_block_plugin.h | 135 |
1 files changed, 89 insertions, 46 deletions
diff --git a/src/include/gnunet_block_plugin.h b/src/include/gnunet_block_plugin.h index ee237ac03..16e93c780 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 |
@@ -19,6 +19,9 @@ | |||
19 | */ | 19 | */ |
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @addtogroup dht_libs DHT and support libraries | ||
23 | * @{ | ||
24 | * | ||
22 | * @author Christian Grothoff | 25 | * @author Christian Grothoff |
23 | * | 26 | * |
24 | * @file | 27 | * @file |
@@ -35,6 +38,7 @@ | |||
35 | #ifndef PLUGIN_BLOCK_H | 38 | #ifndef PLUGIN_BLOCK_H |
36 | #define PLUGIN_BLOCK_H | 39 | #define PLUGIN_BLOCK_H |
37 | 40 | ||
41 | |||
38 | #include "gnunet_util_lib.h" | 42 | #include "gnunet_util_lib.h" |
39 | #include "gnunet_block_lib.h" | 43 | #include "gnunet_block_lib.h" |
40 | 44 | ||
@@ -48,10 +52,10 @@ | |||
48 | * @param seen_results_count number of entries in @a seen_results | 52 | * @param seen_results_count number of entries in @a seen_results |
49 | */ | 53 | */ |
50 | typedef void | 54 | typedef void |
51 | (*GNUNET_BLOCK_GroupMarkSeenFunction)(struct GNUNET_BLOCK_Group *bg, | 55 | (*GNUNET_BLOCK_GroupMarkSeenFunction)( |
52 | const struct | 56 | struct GNUNET_BLOCK_Group *bg, |
53 | GNUNET_HashCode *seen_results, | 57 | const struct GNUNET_HashCode *seen_results, |
54 | unsigned int seen_results_count); | 58 | unsigned int seen_results_count); |
55 | 59 | ||
56 | 60 | ||
57 | /** | 61 | /** |
@@ -63,7 +67,7 @@ typedef void | |||
63 | * @return #GNUNET_OK on success, #GNUNET_NO if the nonces were different and thus | 67 | * @return #GNUNET_OK on success, #GNUNET_NO if the nonces were different and thus |
64 | * we failed. | 68 | * we failed. |
65 | */ | 69 | */ |
66 | typedef int | 70 | typedef enum GNUNET_GenericReturnValue |
67 | (*GNUNET_BLOCK_GroupMergeFunction)(struct GNUNET_BLOCK_Group *bg1, | 71 | (*GNUNET_BLOCK_GroupMergeFunction)(struct GNUNET_BLOCK_Group *bg1, |
68 | const struct GNUNET_BLOCK_Group *bg2); | 72 | const struct GNUNET_BLOCK_Group *bg2); |
69 | 73 | ||
@@ -72,15 +76,13 @@ typedef int | |||
72 | * Serialize state of a block group. | 76 | * Serialize state of a block group. |
73 | * | 77 | * |
74 | * @param bg group to serialize | 78 | * @param bg group to serialize |
75 | * @param[out] nonce set to the nonce of the @a bg | ||
76 | * @param[out] raw_data set to the serialized state | 79 | * @param[out] raw_data set to the serialized state |
77 | * @param[out] raw_data_size set to the number of bytes in @a raw_data | 80 | * @param[out] raw_data_size set to the number of bytes in @a raw_data |
78 | * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not | 81 | * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not |
79 | * supported, #GNUNET_SYSERR on error | 82 | * supported, #GNUNET_SYSERR on error |
80 | */ | 83 | */ |
81 | typedef int | 84 | typedef enum GNUNET_GenericReturnValue |
82 | (*GNUNET_BLOCK_GroupSerializeFunction)(struct GNUNET_BLOCK_Group *bg, | 85 | (*GNUNET_BLOCK_GroupSerializeFunction)(struct GNUNET_BLOCK_Group *bg, |
83 | uint32_t *nonce, | ||
84 | void **raw_data, | 86 | void **raw_data, |
85 | size_t *raw_data_size); | 87 | size_t *raw_data_size); |
86 | 88 | ||
@@ -156,24 +158,54 @@ struct GNUNET_BLOCK_Group | |||
156 | typedef struct GNUNET_BLOCK_Group * | 158 | typedef struct GNUNET_BLOCK_Group * |
157 | (*GNUNET_BLOCK_GroupCreateFunction)(void *cls, | 159 | (*GNUNET_BLOCK_GroupCreateFunction)(void *cls, |
158 | enum GNUNET_BLOCK_Type type, | 160 | enum GNUNET_BLOCK_Type type, |
159 | uint32_t nonce, | ||
160 | const void *raw_data, | 161 | const void *raw_data, |
161 | size_t raw_data_size, | 162 | size_t raw_data_size, |
162 | va_list va); | 163 | va_list va); |
163 | 164 | ||
164 | 165 | ||
165 | /** | 166 | /** |
166 | * Function called to validate a reply or a request. For | 167 | * Function called to validate a query. |
167 | * request evaluation, simply pass "NULL" for the @a reply_block. | 168 | * |
168 | * Note that it is assumed that the reply has already been | 169 | * @param cls closure |
169 | * matched to the key (and signatures checked) as it would | 170 | * @param type block type |
170 | * be done with the "get_key" function. | 171 | * @param query original query (hash) |
172 | * @param xquery extrended query data (can be NULL, depending on type) | ||
173 | * @param xquery_size number of bytes in @a xquery | ||
174 | * @return #GNUNET_OK if the query is fine, #GNUNET_NO if not | ||
175 | */ | ||
176 | typedef enum GNUNET_GenericReturnValue | ||
177 | (*GNUNET_BLOCK_QueryEvaluationFunction)(void *cls, | ||
178 | enum GNUNET_BLOCK_Type type, | ||
179 | const struct GNUNET_HashCode *query, | ||
180 | const void *xquery, | ||
181 | size_t xquery_size); | ||
182 | |||
183 | |||
184 | /** | ||
185 | * Function called to validate a @a block for storage. | ||
186 | * | ||
187 | * @param cls closure | ||
188 | * @param type block type | ||
189 | * @param block block data to validate | ||
190 | * @param block_size number of bytes in @a block | ||
191 | * @return #GNUNET_OK if the @a block is fine, #GNUNET_NO if not, #GNUNET_SYSERR if the @a type is not supported | ||
192 | */ | ||
193 | typedef enum GNUNET_GenericReturnValue | ||
194 | (*GNUNET_BLOCK_BlockEvaluationFunction)(void *cls, | ||
195 | enum GNUNET_BLOCK_Type type, | ||
196 | const void *block, | ||
197 | size_t block_size); | ||
198 | |||
199 | |||
200 | /** | ||
201 | * Function called to validate a reply to a request. Note that it is assumed | ||
202 | * that the reply has already been matched to the key (and signatures checked) | ||
203 | * as it would be done with the GetKeyFunction and the | ||
204 | * BlockEvaluationFunction. | ||
171 | * | 205 | * |
172 | * @param cls closure | 206 | * @param cls closure |
173 | * @param ctx block context | ||
174 | * @param type block type | 207 | * @param type block type |
175 | * @param group which block group to use for evaluation | 208 | * @param group which block group to use for evaluation |
176 | * @param eo evaluation options to control evaluation | ||
177 | * @param query original query (hash) | 209 | * @param query original query (hash) |
178 | * @param xquery extrended query data (can be NULL, depending on type) | 210 | * @param xquery extrended query data (can be NULL, depending on type) |
179 | * @param xquery_size number of bytes in @a xquery | 211 | * @param xquery_size number of bytes in @a xquery |
@@ -181,38 +213,37 @@ typedef struct GNUNET_BLOCK_Group * | |||
181 | * @param reply_block_size number of bytes in @a reply_block | 213 | * @param reply_block_size number of bytes in @a reply_block |
182 | * @return characterization of result | 214 | * @return characterization of result |
183 | */ | 215 | */ |
184 | typedef enum GNUNET_BLOCK_EvaluationResult | 216 | typedef enum GNUNET_BLOCK_ReplyEvaluationResult |
185 | (*GNUNET_BLOCK_EvaluationFunction)(void *cls, | 217 | (*GNUNET_BLOCK_ReplyEvaluationFunction)(void *cls, |
186 | struct GNUNET_BLOCK_Context *ctx, | 218 | enum GNUNET_BLOCK_Type type, |
187 | enum GNUNET_BLOCK_Type type, | 219 | struct GNUNET_BLOCK_Group *group, |
188 | struct GNUNET_BLOCK_Group *group, | 220 | const struct GNUNET_HashCode *query, |
189 | enum GNUNET_BLOCK_EvaluationOptions eo, | 221 | const void *xquery, |
190 | const struct GNUNET_HashCode *query, | 222 | size_t xquery_size, |
191 | const void *xquery, | 223 | const void *reply_block, |
192 | size_t xquery_size, | 224 | size_t reply_block_size); |
193 | const void *reply_block, | ||
194 | size_t reply_block_size); | ||
195 | 225 | ||
196 | 226 | ||
197 | /** | 227 | /** |
198 | * Function called to obtain the key for a block. | 228 | * Function called to obtain the @a key for a block. |
229 | * If the @a block is malformed, the function should | ||
230 | * zero-out @a key and return #GNUNET_OK. | ||
199 | * | 231 | * |
200 | * @param cls closure | 232 | * @param cls closure |
201 | * @param type block type | 233 | * @param type block type |
202 | * @param block block to get the key for | 234 | * @param block block to get the @a key for |
203 | * @param block_size number of bytes in @a block | 235 | * @param block_size number of bytes in @a block |
204 | * @param key set to the key (query) for the given block | 236 | * @param[out] key set to the key (query) for the given block |
205 | * @return #GNUNET_YES on success, | 237 | * @return #GNUNET_YES on success, |
206 | * #GNUNET_NO if the block is malformed | 238 | * #GNUNET_NO if extracting a key for this @a type does not work |
207 | * #GNUNET_SYSERR if type not supported | 239 | * #GNUNET_SYSERR if @a type not supported |
208 | * (or if extracting a key from a block of this type does not work) | ||
209 | */ | 240 | */ |
210 | typedef int | 241 | typedef enum GNUNET_GenericReturnValue |
211 | (*GNUNET_BLOCK_GetKeyFunction) (void *cls, | 242 | (*GNUNET_BLOCK_GetKeyFunction)(void *cls, |
212 | enum GNUNET_BLOCK_Type type, | 243 | enum GNUNET_BLOCK_Type type, |
213 | const void *block, | 244 | const void *block, |
214 | size_t block_size, | 245 | size_t block_size, |
215 | struct GNUNET_HashCode *key); | 246 | struct GNUNET_HashCode *key); |
216 | 247 | ||
217 | 248 | ||
218 | /** | 249 | /** |
@@ -232,12 +263,6 @@ struct GNUNET_BLOCK_PluginFunctions | |||
232 | const enum GNUNET_BLOCK_Type *types; | 263 | const enum GNUNET_BLOCK_Type *types; |
233 | 264 | ||
234 | /** | 265 | /** |
235 | * Main function of a block plugin. Allows us to check if a | ||
236 | * block matches a query. | ||
237 | */ | ||
238 | GNUNET_BLOCK_EvaluationFunction evaluate; | ||
239 | |||
240 | /** | ||
241 | * Obtain the key for a given block (if possible). | 266 | * Obtain the key for a given block (if possible). |
242 | */ | 267 | */ |
243 | GNUNET_BLOCK_GetKeyFunction get_key; | 268 | GNUNET_BLOCK_GetKeyFunction get_key; |
@@ -247,8 +272,26 @@ struct GNUNET_BLOCK_PluginFunctions | |||
247 | * context (i.e. to detect duplicates). | 272 | * context (i.e. to detect duplicates). |
248 | */ | 273 | */ |
249 | GNUNET_BLOCK_GroupCreateFunction create_group; | 274 | GNUNET_BLOCK_GroupCreateFunction create_group; |
275 | |||
276 | /** | ||
277 | * Check that a query is well-formed. | ||
278 | */ | ||
279 | GNUNET_BLOCK_QueryEvaluationFunction check_query; | ||
280 | |||
281 | /** | ||
282 | * Check that a block is well-formed. | ||
283 | */ | ||
284 | GNUNET_BLOCK_BlockEvaluationFunction check_block; | ||
285 | |||
286 | /** | ||
287 | * Check that a reply block matches a query. | ||
288 | */ | ||
289 | GNUNET_BLOCK_ReplyEvaluationFunction check_reply; | ||
290 | |||
250 | }; | 291 | }; |
251 | 292 | ||
252 | #endif | 293 | #endif |
253 | 294 | ||
254 | /** @} */ /* end of group */ | 295 | /** @} */ /* end of group */ |
296 | |||
297 | /** @} */ /* end of group addition */ | ||