gnunet_seti_service.h (10514B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2013, 2014, 2020 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 * @addtogroup Sets 22 * @{ 23 * 24 * @author Florian Dold 25 * @author Christian Grothoff 26 * 27 * @file 28 * Two-peer set intersection operations 29 * 30 * @defgroup set Set intersection service 31 * Two-peer set operations 32 * 33 * @{ 34 */ 35 36 #ifndef GNUNET_SETI_SERVICE_H 37 #define GNUNET_SETI_SERVICE_H 38 39 #ifdef __cplusplus 40 extern "C" 41 { 42 #if 0 /* keep Emacsens' auto-indent happy */ 43 } 44 #endif 45 #endif 46 47 48 #include "gnunet_common.h" 49 #include "gnunet_time_lib.h" 50 #include "gnunet_configuration_lib.h" 51 52 53 /** 54 * Maximum size of a context message for set operation requests. 55 */ 56 #define GNUNET_SETI_CONTEXT_MESSAGE_MAX_SIZE ((1 << 16) - 1024) 57 58 /** 59 * Opaque handle to a set. 60 */ 61 struct GNUNET_SETI_Handle; 62 63 /** 64 * Opaque handle to a set operation request from another peer. 65 */ 66 struct GNUNET_SETI_Request; 67 68 /** 69 * Opaque handle to a listen operation. 70 */ 71 struct GNUNET_SETI_ListenHandle; 72 73 /** 74 * Opaque handle to a set operation. 75 */ 76 struct GNUNET_SETI_OperationHandle; 77 78 79 /** 80 * Status for the result callback 81 */ 82 enum GNUNET_SETI_Status 83 { 84 85 /** 86 * Element should be added to the result set of the local peer, i.e. the 87 * element is in the intersection. 88 */ 89 GNUNET_SETI_STATUS_ADD_LOCAL, 90 91 /** 92 * Element should be delete from the result set of the local peer, i.e. the 93 * local peer is having an element that is not in the intersection. 94 */ 95 GNUNET_SETI_STATUS_DEL_LOCAL, 96 97 /** 98 * The other peer refused to do the operation with us, or something went 99 * wrong. 100 */ 101 GNUNET_SETI_STATUS_FAILURE, 102 103 /** 104 * Success, all elements have been sent (and received). 105 */ 106 GNUNET_SETI_STATUS_DONE 107 }; 108 109 110 /** 111 * Element stored in a set. 112 */ 113 struct GNUNET_SETI_Element 114 { 115 /** 116 * Number of bytes in the buffer pointed to by data. 117 */ 118 uint16_t size; 119 120 /** 121 * Application-specific element type. 122 */ 123 uint16_t element_type; 124 125 /** 126 * Actual data of the element 127 */ 128 const void *data; 129 }; 130 131 132 /** 133 * Possible options to pass to a set operation. 134 * 135 * Used as tag for struct #GNUNET_SETI_Option. 136 */ 137 enum GNUNET_SETI_OptionType 138 { 139 /** 140 * List terminator. 141 */ 142 GNUNET_SETI_OPTION_END = 0, 143 144 /** 145 * Return the elements remaining in the intersection 146 * (#GNUNET_SETI_STATUS_ADD_LOCAL). If not given, the default is to return a 147 * list of the elements to be removed (#GNUNET_SETI_STATUS_DEL_LOCAL). 148 */ 149 GNUNET_SETI_OPTION_RETURN_INTERSECTION = 1, 150 }; 151 152 153 /** 154 * Option for set operations. 155 */ 156 struct GNUNET_SETI_Option 157 { 158 /** 159 * Type of the option. 160 */ 161 enum GNUNET_SETI_OptionType type; 162 163 /** 164 * Value for the option, only used with some options. 165 */ 166 union 167 { 168 uint64_t num; 169 } v; 170 }; 171 172 173 /** 174 * Callback for set union operation results. Called for each element 175 * in the result set. 176 * 177 * @param cls closure 178 * @param element a result element, only valid if status is #GNUNET_SETI_STATUS_OK 179 * @param current_size current set size 180 * @param status see `enum GNUNET_SETI_Status` 181 */ 182 typedef void 183 (*GNUNET_SETI_ResultIterator) (void *cls, 184 const struct GNUNET_SETI_Element *element, 185 uint64_t current_size, 186 enum GNUNET_SETI_Status status); 187 188 189 /** 190 * Called when another peer wants to do a set operation with the 191 * local peer. If a listen error occurs, the @a request is NULL. 192 * 193 * @param cls closure 194 * @param other_peer the other peer 195 * @param context_msg message with application specific information from 196 * the other peer 197 * @param request request from the other peer (never NULL), use GNUNET_SETI_accept() 198 * to accept it, otherwise the request will be refused 199 * Note that we can't just return value from the listen callback, 200 * as it is also necessary to specify the set we want to do the 201 * operation with, with sometimes can be derived from the context 202 * message. It's necessary to specify the timeout. 203 */ 204 typedef void 205 (*GNUNET_SETI_ListenCallback) (void *cls, 206 const struct GNUNET_PeerIdentity *other_peer, 207 const struct GNUNET_MessageHeader *context_msg, 208 struct GNUNET_SETI_Request *request); 209 210 211 /** 212 * Create an empty set, supporting the specified operation. 213 * 214 * @param cfg configuration to use for connecting to the 215 * set service 216 * @return a handle to the set 217 */ 218 struct GNUNET_SETI_Handle * 219 GNUNET_SETI_create (const struct GNUNET_CONFIGURATION_Handle *cfg); 220 221 222 /** 223 * Add an element to the given set. 224 * 225 * @param set set to add element to 226 * @param element element to add to the set 227 * @param cb function to call when finished, can be NULL 228 * @param cb_cls closure for @a cb 229 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the 230 * set is invalid (e.g. the set service crashed) 231 */ 232 int 233 GNUNET_SETI_add_element (struct GNUNET_SETI_Handle *set, 234 const struct GNUNET_SETI_Element *element, 235 GNUNET_SCHEDULER_TaskCallback cb, 236 void *cb_cls); 237 238 239 /** 240 * Destroy the set handle, and free all associated resources. Operations may 241 * still be pending when a set is destroyed (and will be allowed to complete). 242 * 243 * @param set set to destroy 244 */ 245 void 246 GNUNET_SETI_destroy (struct GNUNET_SETI_Handle *set); 247 248 249 /** 250 * Prepare a set operation to be evaluated with another peer. The evaluation 251 * will not start until the client provides a local set with 252 * GNUNET_SETI_commit(). 253 * 254 * @param other_peer peer with the other set 255 * @param app_id hash for the application using the set 256 * @param context_msg additional information for the request 257 * @param options options to use when processing the request 258 * @param result_cb called on error or success 259 * @param result_cls closure for @a result_cb 260 * @return a handle to cancel the operation 261 */ 262 struct GNUNET_SETI_OperationHandle * 263 GNUNET_SETI_prepare (const struct GNUNET_PeerIdentity *other_peer, 264 const struct GNUNET_HashCode *app_id, 265 const struct GNUNET_MessageHeader *context_msg, 266 const struct GNUNET_SETI_Option options[], 267 GNUNET_SETI_ResultIterator result_cb, 268 void *result_cls); 269 270 271 /** 272 * Wait for set operation requests for the given application ID. 273 * If the connection to the set service is lost, the listener is 274 * re-created transparently with exponential backoff. 275 * 276 * @param cfg configuration to use for connecting to 277 * the set service 278 * @param app_id id of the application that handles set operation requests 279 * @param listen_cb called for each incoming request matching the operation 280 * and application id 281 * @param listen_cls handle for @a listen_cb 282 * @return a handle that can be used to cancel the listen operation 283 */ 284 struct GNUNET_SETI_ListenHandle * 285 GNUNET_SETI_listen (const struct GNUNET_CONFIGURATION_Handle *cfg, 286 const struct GNUNET_HashCode *app_id, 287 GNUNET_SETI_ListenCallback listen_cb, 288 void *listen_cls); 289 290 291 /** 292 * Cancel the given listen operation. After calling cancel, the 293 * listen callback for this listen handle will not be called again. 294 * Note that cancelling a listen operation will automatically reject 295 * all operations that have not yet been accepted. 296 * 297 * @param lh handle for the listen operation 298 */ 299 void 300 GNUNET_SETI_listen_cancel (struct GNUNET_SETI_ListenHandle *lh); 301 302 303 /** 304 * Accept a request we got via GNUNET_SETI_listen(). Must be called during 305 * GNUNET_SETI_listen(), as the `struct GNUNET_SETI_Request` becomes invalid 306 * afterwards. 307 * Call GNUNET_SETI_commit() to provide the local set to use for the operation, 308 * and to begin the exchange with the remote peer. 309 * 310 * @param request request to accept 311 * @param options options to use when processing the request 312 * @param result_cb callback for the results 313 * @param result_cls closure for @a result_cb 314 * @return a handle to cancel the operation 315 */ 316 struct GNUNET_SETI_OperationHandle * 317 GNUNET_SETI_accept (struct GNUNET_SETI_Request *request, 318 const struct GNUNET_SETI_Option options[], 319 GNUNET_SETI_ResultIterator result_cb, 320 void *result_cls); 321 322 323 /** 324 * Commit a set to be used with a set operation. 325 * This function is called once we have fully constructed 326 * the set that we want to use for the operation. At this 327 * time, the P2P protocol can then begin to exchange the 328 * set information and call the result callback with the 329 * result information. 330 * 331 * @param oh handle to the set operation 332 * @param set the set to use for the operation 333 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the 334 * set is invalid (e.g. the set service crashed) 335 */ 336 int 337 GNUNET_SETI_commit (struct GNUNET_SETI_OperationHandle *oh, 338 struct GNUNET_SETI_Handle *set); 339 340 341 /** 342 * Cancel the given set operation. May not be called after the operation's 343 * `GNUNET_SETI_ResultIterator` has been called with a status of 344 * #GNUNET_SETI_STATUS_FAILURE or #GNUNET_SETI_STATUS_DONE. 345 * 346 * @param oh set operation to cancel 347 */ 348 void 349 GNUNET_SETI_operation_cancel (struct GNUNET_SETI_OperationHandle *oh); 350 351 352 /** 353 * Hash a set element. 354 * 355 * @param element the element that should be hashed 356 * @param[out] ret_hash a pointer to where the hash of @a element 357 * should be stored 358 */ 359 void 360 GNUNET_SETI_element_hash (const struct GNUNET_SETI_Element *element, 361 struct GNUNET_HashCode *ret_hash); 362 363 364 #if 0 /* keep Emacsens' auto-indent happy */ 365 { 366 #endif 367 #ifdef __cplusplus 368 } 369 #endif 370 371 #endif 372 373 /** @} */ /* end of group */ 374 375 /** @} */ /* end of group addition */