gnunet_block_lib.h (9083B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2010, 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 * Library for data block manipulation 29 * 30 * @defgroup block Block library 31 * Library for data block manipulation 32 * @{ 33 */ 34 #ifndef GNUNET_BLOCK_LIB_H 35 #define GNUNET_BLOCK_LIB_H 36 37 38 #include "gnunet_util_lib.h" 39 #include "gnunet_dht_block_types.h" 40 41 #ifdef __cplusplus 42 extern "C" 43 { 44 #if 0 /* keep Emacsens' auto-indent happy */ 45 } 46 #endif 47 #endif 48 49 50 /** 51 * Possible ways for how a block may relate to a query. 52 */ 53 enum GNUNET_BLOCK_ReplyEvaluationResult 54 { 55 56 /** 57 * Specified block type not supported by any plugin. 58 */ 59 GNUNET_BLOCK_REPLY_TYPE_NOT_SUPPORTED = -1, 60 61 /** 62 * Valid result, but suppressed because it is a duplicate. 63 */ 64 GNUNET_BLOCK_REPLY_OK_DUPLICATE = 0, 65 66 /** 67 * Block does not match xquery (valid result, not relevant for the request) 68 */ 69 GNUNET_BLOCK_REPLY_IRRELEVANT = 1, 70 71 /** 72 * Valid result, and there may be more. 73 */ 74 GNUNET_BLOCK_REPLY_OK_MORE = 2, 75 76 /** 77 * Last possible valid result. 78 */ 79 GNUNET_BLOCK_REPLY_OK_LAST = 3 80 81 }; 82 83 84 /** 85 * Handle to an initialized block library. 86 */ 87 struct GNUNET_BLOCK_Context; 88 89 90 /** 91 * Mingle hash with the mingle_number to produce different bits. 92 * 93 * @param in original hash code 94 * @param mingle_number number for hash permutation 95 * @param hc where to store the result. 96 */ 97 void 98 GNUNET_BLOCK_mingle_hash (const struct GNUNET_HashCode *in, 99 uint32_t mingle_number, 100 struct GNUNET_HashCode *hc); 101 102 103 /** 104 * Create a block context. Loads the block plugins. 105 * 106 * @param cfg configuration to use 107 * @return NULL on error 108 */ 109 struct GNUNET_BLOCK_Context * 110 GNUNET_BLOCK_context_create (const struct GNUNET_CONFIGURATION_Handle *cfg); 111 112 113 /** 114 * Destroy the block context. 115 * 116 * @param ctx context to destroy 117 */ 118 void 119 GNUNET_BLOCK_context_destroy (struct GNUNET_BLOCK_Context *ctx); 120 121 122 /** 123 * Handle for a group of elements that will be evaluated together. 124 * They must all be of the same type. A block group allows the 125 * plugin to keep some state across individual evaluations. 126 */ 127 struct GNUNET_BLOCK_Group; 128 129 130 /** 131 * Create a new block group. 132 * 133 * @param ctx block context in which the block group is created 134 * @param type type of the block for which we are creating the group 135 * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh 136 * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh 137 * @param ... type-specific additional data, can be empty 138 * @return block group handle, NULL if block groups are not supported 139 * by this @a type of block (this is not an error) 140 */ 141 struct GNUNET_BLOCK_Group * 142 GNUNET_BLOCK_group_create (struct GNUNET_BLOCK_Context *ctx, 143 enum GNUNET_BLOCK_Type type, 144 const void *raw_data, 145 size_t raw_data_size, 146 ...); 147 148 149 /** 150 * Serialize state of a block group. 151 * 152 * @param bg group to serialize 153 * @param[out] raw_data set to the serialized state 154 * @param[out] raw_data_size set to the number of bytes in @a raw_data 155 * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not 156 * supported, #GNUNET_SYSERR on error 157 */ 158 enum GNUNET_GenericReturnValue 159 GNUNET_BLOCK_group_serialize (struct GNUNET_BLOCK_Group *bg, 160 void **raw_data, 161 size_t *raw_data_size); 162 163 164 /** 165 * Destroy resources used by a block group. 166 * 167 * @param bg group to destroy, NULL is allowed 168 */ 169 void 170 GNUNET_BLOCK_group_destroy (struct GNUNET_BLOCK_Group *bg); 171 172 173 /** 174 * Function called to validate if a reply is good for a 175 * particular query. 176 * 177 * @param ctx block contxt 178 * @param type block type 179 * @param[in,out] group block group to use for evaluation 180 * @param query original query (hash) 181 * @param xquery extrended query data (can be NULL, depending on type) 182 * @param xquery_size number of bytes in @a xquery 183 * @param reply_block response to validate 184 * @param reply_block_size number of bytes in @a reply_block 185 * @return characterization of result 186 */ 187 enum GNUNET_BLOCK_ReplyEvaluationResult 188 GNUNET_BLOCK_check_reply (struct GNUNET_BLOCK_Context *ctx, 189 enum GNUNET_BLOCK_Type type, 190 struct GNUNET_BLOCK_Group *group, 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 request. 200 * 201 * @param ctx block contxt 202 * @param type block type 203 * @param query original query (hash) 204 * @param xquery extrended query data (can be NULL, depending on type) 205 * @param xquery_size number of bytes in @a xquery 206 * @return #GNUNET_OK if the block is fine, #GNUNET_NO if not, 207 * #GNUNET_SYSERR if @a type is not supported 208 */ 209 enum GNUNET_GenericReturnValue 210 GNUNET_BLOCK_check_query (struct GNUNET_BLOCK_Context *ctx, 211 enum GNUNET_BLOCK_Type type, 212 const struct GNUNET_HashCode *query, 213 const void *xquery, 214 size_t xquery_size); 215 216 217 /** 218 * Function called to validate a block. 219 * 220 * @param ctx block contxt 221 * @param type block type 222 * @param block payload to put 223 * @param block_size number of bytes in @a block 224 * @return #GNUNET_OK if the block is fine, #GNUNET_NO if not, 225 * #GNUNET_SYSERR if @a type is not supported 226 */ 227 enum GNUNET_GenericReturnValue 228 GNUNET_BLOCK_check_block (struct GNUNET_BLOCK_Context *ctx, 229 enum GNUNET_BLOCK_Type type, 230 const void *block, 231 size_t block_size); 232 233 234 /** 235 * Function called to obtain the @a key for a @a block. 236 * If the @a block is malformed, the function should 237 * zero-out @a key and return #GNUNET_OK. 238 * 239 * @param ctx block context 240 * @param type block type 241 * @param block block to get the key for 242 * @param block_size number of bytes in @a block 243 * @param key set to the key (query) for the given block 244 * @return #GNUNET_YES on success, 245 * #GNUNET_NO if extracting a key from a block of this @a type does not work 246 * #GNUNET_SYSERR if @a type not supported 247 */ 248 enum GNUNET_GenericReturnValue 249 GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx, 250 enum GNUNET_BLOCK_Type type, 251 const void *block, 252 size_t block_size, 253 struct GNUNET_HashCode *key); 254 255 256 /** 257 * Update block group to filter out the given results. Note that the 258 * use of a hash for seen results implies that the caller magically 259 * knows how the specific block engine hashes for filtering 260 * duplicates, so this API may not always apply. 261 * 262 * @param bf_mutator mutation value to use 263 * @param seen_results results already seen 264 * @param seen_results_count number of entries in @a seen_results 265 * @return #GNUNET_SYSERR if not supported, #GNUNET_OK on success 266 */ 267 enum GNUNET_GenericReturnValue 268 GNUNET_BLOCK_group_set_seen (struct GNUNET_BLOCK_Group *bg, 269 const struct GNUNET_HashCode *seen_results, 270 unsigned int seen_results_count); 271 272 273 /** 274 * Try merging two block groups. Afterwards, @a bg1 should remain 275 * valid and contain the rules from both @a bg1 and @a bg2, and 276 * @a bg2 should be destroyed (as part of this call). The latter 277 * should happen even if merging is not supported. 278 * 279 * @param[in,out] bg1 first group to merge, is updated 280 * @param bg2 second group to merge, is destroyed 281 * @return #GNUNET_OK on success, 282 * #GNUNET_NO if merge failed due to different nonce 283 * #GNUNET_SYSERR if merging is not supported 284 */ 285 enum GNUNET_GenericReturnValue 286 GNUNET_BLOCK_group_merge (struct GNUNET_BLOCK_Group *bg1, 287 struct GNUNET_BLOCK_Group *bg2); 288 289 290 #if 0 /* keep Emacsens' auto-indent happy */ 291 { 292 #endif 293 #ifdef __cplusplus 294 } 295 #endif 296 297 /* ifndef GNUNET_BLOCK_LIB_H */ 298 #endif 299 300 /** @} */ /* end of group */ 301 302 /** @} */ /* end of group addition */ 303 304 /* end of gnunet_block_lib.h */