gnunet_block_plugin.h (9166B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2010, 2013, 2017, 2021, 2022 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 * @addtogroup dht_libs DHT and support libraries 23 * @{ 24 * 25 * @author Christian Grothoff 26 * 27 * @file 28 * API for block plugins. 29 * 30 * @defgroup block-plugin Block plugin API 31 * To be implemented by applications storing data in the DHT. 32 * 33 * Each block plugin must conform to the API specified by this header. 34 * 35 * @{ 36 */ 37 38 #ifndef PLUGIN_BLOCK_H 39 #define PLUGIN_BLOCK_H 40 41 42 #include "gnunet_util_lib.h" 43 #include "gnunet_block_lib.h" 44 45 46 /** 47 * Mark elements as "seen" using a hash of the element. Not supported 48 * by all block plugins. 49 * 50 * @param bg group to update 51 * @param seen_results results already seen 52 * @param seen_results_count number of entries in @a seen_results 53 */ 54 typedef void 55 (*GNUNET_BLOCK_GroupMarkSeenFunction)( 56 struct GNUNET_BLOCK_Group *bg, 57 const struct GNUNET_HashCode *seen_results, 58 unsigned int seen_results_count); 59 60 61 /** 62 * Merge two groups, if possible. Not supported by all block plugins, 63 * can also fail if the nonces were different. 64 * 65 * @param bg1 group to update 66 * @param bg2 group to merge into @a bg1 67 * @return #GNUNET_OK on success, #GNUNET_NO if the nonces were different and thus 68 * we failed. 69 */ 70 typedef enum GNUNET_GenericReturnValue 71 (*GNUNET_BLOCK_GroupMergeFunction)(struct GNUNET_BLOCK_Group *bg1, 72 const struct GNUNET_BLOCK_Group *bg2); 73 74 75 /** 76 * Serialize state of a block group. 77 * 78 * @param bg group to serialize 79 * @param[out] raw_data set to the serialized state 80 * @param[out] raw_data_size set to the number of bytes in @a raw_data 81 * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not 82 * supported, #GNUNET_SYSERR on error 83 */ 84 typedef enum GNUNET_GenericReturnValue 85 (*GNUNET_BLOCK_GroupSerializeFunction)(struct GNUNET_BLOCK_Group *bg, 86 void **raw_data, 87 size_t *raw_data_size); 88 89 90 /** 91 * Destroy resources used by a block group. 92 * 93 * @param bg group to destroy, NULL is allowed 94 */ 95 typedef void 96 (*GNUNET_BLOCK_GroupDestroyFunction)(struct GNUNET_BLOCK_Group *bg); 97 98 99 /** 100 * Block group data. The plugin must initialize the callbacks 101 * and can use the @e internal_cls as it likes. 102 */ 103 struct GNUNET_BLOCK_Group 104 { 105 /** 106 * Context owning the block group. Set by the main block library. 107 */ 108 struct GNUENT_BLOCK_Context *ctx; 109 110 /** 111 * Type for the block group. Set by the main block library. 112 */ 113 enum GNUNET_BLOCK_Type type; 114 115 /** 116 * Serialize the block group data, can be NULL if 117 * not supported. 118 */ 119 GNUNET_BLOCK_GroupSerializeFunction serialize_cb; 120 121 /** 122 * Function to call to mark elements as seen in the group. 123 * Can be NULL if not supported. 124 */ 125 GNUNET_BLOCK_GroupMarkSeenFunction mark_seen_cb; 126 127 /** 128 * Function to call to merge two groups. 129 * Can be NULL if not supported. 130 */ 131 GNUNET_BLOCK_GroupMergeFunction merge_cb; 132 133 /** 134 * Function to call to destroy the block group. 135 * Must not be NULL. 136 */ 137 GNUNET_BLOCK_GroupDestroyFunction destroy_cb; 138 139 /** 140 * Internal data structure of the plugin. 141 */ 142 void *internal_cls; 143 }; 144 145 146 /** 147 * Create a new block group. 148 * 149 * @param ctx block context in which the block group is created 150 * @param type type of the block for which we are creating the group 151 * @param nonce random value used to seed the group creation 152 * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh 153 * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh 154 * @param va variable arguments specific to @a type 155 * @return block group handle, NULL if block groups are not supported 156 * by this @a type of block (this is not an error) 157 */ 158 typedef struct GNUNET_BLOCK_Group * 159 (*GNUNET_BLOCK_GroupCreateFunction)(void *cls, 160 enum GNUNET_BLOCK_Type type, 161 const void *raw_data, 162 size_t raw_data_size, 163 va_list va); 164 165 166 /** 167 * Function called to validate a query. 168 * 169 * @param cls closure 170 * @param type block type 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. 205 * 206 * @param cls closure 207 * @param type block type 208 * @param group which block group to use for evaluation 209 * @param query original query (hash) 210 * @param xquery extrended query data (can be NULL, depending on type) 211 * @param xquery_size number of bytes in @a xquery 212 * @param reply_block response to validate 213 * @param reply_block_size number of bytes in @a reply_block 214 * @return characterization of result 215 */ 216 typedef enum GNUNET_BLOCK_ReplyEvaluationResult 217 (*GNUNET_BLOCK_ReplyEvaluationFunction)(void *cls, 218 enum GNUNET_BLOCK_Type type, 219 struct GNUNET_BLOCK_Group *group, 220 const struct GNUNET_HashCode *query, 221 const void *xquery, 222 size_t xquery_size, 223 const void *reply_block, 224 size_t reply_block_size); 225 226 227 /** 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. 231 * 232 * @param cls closure 233 * @param type block type 234 * @param block block to get the @a key for 235 * @param block_size number of bytes in @a block 236 * @param[out] key set to the key (query) for the given block 237 * @return #GNUNET_YES on success, 238 * #GNUNET_NO if extracting a key for this @a type does not work 239 * #GNUNET_SYSERR if @a type not supported 240 */ 241 typedef enum GNUNET_GenericReturnValue 242 (*GNUNET_BLOCK_GetKeyFunction)(void *cls, 243 enum GNUNET_BLOCK_Type type, 244 const void *block, 245 size_t block_size, 246 struct GNUNET_HashCode *key); 247 248 249 /** 250 * Each plugin is required to return a pointer to a struct of this 251 * type as the return value from its entry point. 252 */ 253 struct GNUNET_BLOCK_PluginFunctions 254 { 255 /** 256 * Closure for all of the callbacks. 257 */ 258 void *cls; 259 260 /** 261 * 0-terminated array of block types supported by this plugin. 262 */ 263 const enum GNUNET_BLOCK_Type *types; 264 265 /** 266 * Obtain the key for a given block (if possible). 267 */ 268 GNUNET_BLOCK_GetKeyFunction get_key; 269 270 /** 271 * Create a block group to process a bunch of blocks in a shared 272 * context (i.e. to detect duplicates). 273 */ 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 291 }; 292 293 #endif 294 295 /** @} */ /* end of group */ 296 297 /** @} */ /* end of group addition */