gnunet_peerstore_service.h (12634B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) GNUnet e.V. 2004--2019 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 Backbone 23 * @{ 24 * 25 * @author Omar Tarabai 26 * 27 * @file 28 * API to the peerstore service 29 * 30 * @defgroup peerstore Peer Store service 31 * 32 * @see [Documentation](https://gnunet.org/gnunets-peerstore-subsystem) 33 * 34 * @{ 35 */ 36 #ifndef GNUNET_PEERSTORE_SERVICE_H 37 #define GNUNET_PEERSTORE_SERVICE_H 38 39 40 #include "gnunet_util_lib.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #if 0 /* keep Emacsens' auto-indent happy */ 45 } 46 #endif 47 #endif 48 49 /** 50 * Key used for storing HELLO in the peerstore 51 */ 52 #define GNUNET_PEERSTORE_HELLO_KEY "peerstore-peer-hello-uri" 53 54 /** 55 * Key used for storing addresses in URL format in the peerstore 56 */ 57 #define GNUNET_PEERSTORE_TRANSPORT_URLADDRESS_KEY "transport-communicator-url" 58 59 /** 60 * Key used for storing HELLOs in the peerstore 61 */ 62 #define GNUNET_PEERSTORE_TRANSPORT_HELLO_KEY "transport-peer-hello" 63 64 /** 65 * Key used to store sender's monotonic time from backchannel 66 * messages. 67 */ 68 #define GNUNET_PEERSTORE_TRANSPORT_BACKCHANNEL_MONOTIME \ 69 "transport-backchannel-monotonic-time" 70 71 /** 72 * Key used to store sender's monotonic time from DV learn 73 * messages. 74 */ 75 #define GNUNET_PEERSTORE_TRANSPORT_DVLEARN_MONOTIME \ 76 "transport-dv-learn-monotonic-time" 77 78 /** 79 * Key used to store sender's monotonic time from handshake message. 80 */ 81 #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE \ 82 "transport-tcp-communicator-handshake" 83 84 /** 85 * Key used to store sender's monotonic time from handshake ack message. 86 */ 87 #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE_ACK \ 88 "transport-tcp-communicator-handshake-ack" 89 90 /** 91 * Key used to store sender's monotonic time from rekey message. 92 */ 93 #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_REKEY \ 94 "transport-tcp-communicator-rekey" 95 96 97 /** 98 * Options for storing values in PEERSTORE 99 */ 100 enum GNUNET_PEERSTORE_StoreOption 101 { 102 /** 103 * Possibly store multiple values under given key. 104 */ 105 GNUNET_PEERSTORE_STOREOPTION_MULTIPLE = 0, 106 107 /** 108 * Delete any previous values for the given key before 109 * storing the given value. 110 */ 111 GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1, 112 113 }; 114 115 /** 116 * Handle to the peerstore service. 117 */ 118 struct GNUNET_PEERSTORE_Handle; 119 120 /** 121 * Context for a store request 122 */ 123 struct GNUNET_PEERSTORE_StoreContext; 124 125 /** 126 * Context for the info handler. 127 */ 128 struct GNUNET_PEERSTORE_NotifyContext; 129 130 /** 131 * Single PEERSTORE record 132 */ 133 struct GNUNET_PEERSTORE_Record 134 { 135 /** 136 * Responsible sub system string 137 */ 138 char *sub_system; 139 140 /** 141 * Peer Identity 142 */ 143 struct GNUNET_PeerIdentity peer; 144 145 /** 146 * Record key string 147 */ 148 char *key; 149 150 /** 151 * Record value BLOB 152 */ 153 void *value; 154 155 /** 156 * Size of @e value BLOB 157 */ 158 size_t value_size; 159 160 /** 161 * Expiry time of entry 162 */ 163 struct GNUNET_TIME_Absolute expiry; 164 165 }; 166 167 168 /** 169 * Continuation called with a status result. 170 * 171 * @param cls closure 172 * @param success #GNUNET_OK or #GNUNET_SYSERR 173 */ 174 typedef void (*GNUNET_PEERSTORE_Continuation) (void *cls, int success); 175 176 177 /** 178 * Context for a add hello uri request. 179 */ 180 struct GNUNET_PEERSTORE_StoreHelloContext; 181 182 183 /** 184 * Function called by PEERSTORE for each matching record. 185 * 186 * @param cls closure 187 * @param seq sequence in interation 188 * @param record peerstore record information 189 * @param emsg error message, or NULL if no errors 190 */ 191 typedef void (*GNUNET_PEERSTORE_Processor) ( 192 void *cls, 193 const struct GNUNET_PEERSTORE_Record *record, 194 const char *emsg); 195 196 /** 197 * Function called by PEERSTORE when notifying a client about a changed hello. 198 * 199 * @param cls closure 200 * @param hello_uri Hello uri. 201 */ 202 typedef void (*GNUNET_PEERSTORE_hello_notify_cb) ( 203 void *cls, 204 const struct GNUNET_PeerIdentity *peer, 205 const struct GNUNET_MessageHeader *hello, 206 const char *err_msg); 207 208 /** 209 * Add hello to peerstore. 210 * 211 * @param h handle for peerstore. 212 * @param msg The hello to add. 213 * @param cont The continuation function to execute after storing. 214 * @param cont_cls The continuation function closure. 215 * @return The context for storing. 216 */ 217 struct GNUNET_PEERSTORE_StoreHelloContext * 218 GNUNET_PEERSTORE_hello_add (struct GNUNET_PEERSTORE_Handle *h, 219 const struct GNUNET_MessageHeader *msg, 220 GNUNET_PEERSTORE_Continuation cont, 221 void *cont_cls); 222 223 224 /** 225 * Cancel the request to add a hello. 226 * 227 * @param huc The context for storing a hello. 228 */ 229 void 230 GNUNET_PEERSTORE_hello_add_cancel (struct 231 GNUNET_PEERSTORE_StoreHelloContext *huc); 232 233 234 /** 235 * Connect to the PEERSTORE service. 236 * 237 * @return NULL on error 238 */ 239 struct GNUNET_PEERSTORE_Handle * 240 GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); 241 242 243 /** 244 * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH and 245 * STORE requests will be canceled. 246 * 247 * @param h handle to disconnect 248 */ 249 void 250 GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h); 251 252 253 /** 254 * Store a new entry in the PEERSTORE. 255 * Note that stored entries can be lost in some cases 256 * such as power failure. 257 * 258 * @param h Handle to the PEERSTORE service 259 * @param sub_system name of the sub system 260 * @param peer Peer Identity 261 * @param key entry key 262 * @param value entry value BLOB 263 * @param size size of @e value 264 * @param expiry absolute time after which the entry is (possibly) deleted 265 * @param options options specific to the storage operation 266 * @param cont Continuation function after the store request is sent 267 * @param cont_cls Closure for @a cont 268 */ 269 struct GNUNET_PEERSTORE_StoreContext * 270 GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h, 271 const char *sub_system, 272 const struct GNUNET_PeerIdentity *peer, 273 const char *key, 274 const void *value, 275 size_t size, 276 struct GNUNET_TIME_Absolute expiry, 277 enum GNUNET_PEERSTORE_StoreOption options, 278 GNUNET_PEERSTORE_Continuation cont, 279 void *cont_cls); 280 281 282 /** 283 * Cancel a store request 284 * 285 * @param sc Store request context 286 */ 287 void 288 GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc); 289 290 291 /** 292 * Iterate over peerstore entries. 293 * The iteration can be filtered to contain only records 294 * matching @a peer and/or @a key. 295 * The @a sub_system to match must be provided. 296 * @a callback will be called with (each) matching record. 297 * #GNUNET_PEERSTORE_iteration_next() must be invoked 298 * to continue processing until the end of the iteration is 299 * reached. 300 * 301 * @param h handle to the PEERSTORE service 302 * @param sub_system name of sub system 303 * @param peer Peer identity (can be NULL) 304 * @param key entry key string (can be NULL) 305 * @param callback function called with each matching record. The record will be NULL to indicate end. 306 * @param callback_cls closure for @a callback 307 * @return Handle to iteration request 308 */ 309 struct GNUNET_PEERSTORE_IterateContext * 310 GNUNET_PEERSTORE_iteration_start (struct GNUNET_PEERSTORE_Handle *h, 311 const char *sub_system, 312 const struct GNUNET_PeerIdentity *peer, 313 const char *key, 314 GNUNET_PEERSTORE_Processor callback, 315 void *callback_cls); 316 317 318 /** 319 * Continue an iteration. 320 * Do NOT call after the iterate request is done. 321 * 322 * @param ic Iterate request context as returned by #GNUNET_PEERSTORE_iteration_start() 323 * @param limit how many records to return max until #GNUNET_PEERSTORE_iterate_next() needs to be called again. 324 */ 325 void 326 GNUNET_PEERSTORE_iteration_next (struct GNUNET_PEERSTORE_IterateContext *ic, 327 uint64_t limit); 328 329 330 /** 331 * Cancel an iteration. 332 * Do NOT call after the iterate request is done 333 * 334 * @param ic Iterate request context as returned by #GNUNET_PEERSTORE_iteration_start() 335 */ 336 void 337 GNUNET_PEERSTORE_iteration_stop (struct GNUNET_PEERSTORE_IterateContext *ic); 338 339 /** 340 * Request watching a given key 341 * The monitoring can be filtered to contain only records 342 * matching @a peer and/or @a key. 343 * The @a sub_system to match must be provided. 344 * @a callback will be called with (each) matching new record. 345 * #GNUNET_PEERSTORE_monitor_next() must be invoked 346 * to continue processing until @a sync_cb is 347 * called, indicating that the caller should be up-to-date. 348 * The caller will be notified with any new values added to key 349 * through @a callback. 350 * If @a iterate_first is set to GNUNET_YES, the monitor will first 351 * iterate over all existing, matching records. In any case, 352 * after @a sync_cb is called the first time monitoring starts. 353 * 354 * @param h handle to the PEERSTORE service 355 * @param iterate_first first iterated of all results if GNUNET_YES 356 * @param sub_system name of sub system 357 * @param peer Peer identity 358 * @param key entry key string 359 * @param error_cb function to call on error (i.e. disconnect); note that 360 * unlike the other error callbacks in this API, a call to this 361 * function does NOT destroy the monitor handle, it merely signals 362 * that monitoring is down. You need to still explicitly call 363 * #GNUNET_PEERSTORE_monitor_stop(). 364 * @param error_cb_cls closure for @a error_cb 365 * @param sync_cb function called when we're in sync with the peerstore 366 * @param sync_cb_cls closure for @a sync_cb 367 * @param callback function called with each new value 368 * @param callback_cls closure for @a callback 369 * @return Handle to watch request 370 */ 371 struct GNUNET_PEERSTORE_Monitor * 372 GNUNET_PEERSTORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg, 373 int iterate_first, 374 const char *sub_system, 375 const struct GNUNET_PeerIdentity *peer, 376 const char *key, 377 GNUNET_SCHEDULER_TaskCallback error_cb, 378 void *error_cb_cls, 379 GNUNET_SCHEDULER_TaskCallback sync_cb, 380 void *sync_cb_cls, 381 GNUNET_PEERSTORE_Processor callback, 382 void *callback_cls); 383 384 /** 385 * Calls the monitor processor specified in #GNUNET_PEERSTORE_monitor_start 386 * for the next record(s). This function is used to allow clients that merely 387 * monitor the NAMESTORE to still throttle namestore operations, so we can be 388 * sure that the monitors can keep up. 389 * 390 * Note that #GNUNET_PEERSTORE_store() only waits for this 391 * call if the previous limit set by the client was already reached. 392 * Thus, by using a @a limit greater than 1, monitors basically enable 393 * a queue of notifications to be processed asynchronously with some 394 * delay. Note that even with a limit of 1 the 395 * #GNUNET_PEERSTORE_store() function will run asynchronously 396 * and the continuation may be invoked before the monitors completed 397 * (or even started) processing the notification. Thus, monitors will 398 * only closely track the current state of the peerstore, but not 399 * be involved in the transactions. 400 * 401 * @param zm the monitor 402 * @param limit number of records to return to the iterator in one shot 403 * (before #GNUNET_PEERSTORE_monitor_next is to be called again) 404 */ 405 void 406 GNUNET_PEERSTORE_monitor_next (struct GNUNET_PEERSTORE_Monitor *zm, 407 uint64_t limit); 408 409 /** 410 * Stop monitoring. 411 * 412 * @param zm handle to the monitor activity to stop 413 */ 414 void 415 GNUNET_PEERSTORE_monitor_stop (struct GNUNET_PEERSTORE_Monitor *zm); 416 417 #if 0 /* keep Emacsens' auto-indent happy */ 418 { 419 #endif 420 #ifdef __cplusplus 421 } 422 #endif 423 424 #endif 425 426 /** @} */ /* end of group */ 427 428 /** @} */ /* end of group addition */