src/include/gnunet_peerstore_service.h

   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  * @author Omar Tarabai
  23  *
  24  * @file
  25  * API to the peerstore service
  26  *
  27  * @defgroup peerstore  Peer Store service
  28  *
  29  * @see [Documentation](https://gnunet.org/gnunets-peerstore-subsystem)
  30  *
  31  * @{
  32  */
  33 #ifndef GNUNET_PEERSTORE_SERVICE_H
  34 #define GNUNET_PEERSTORE_SERVICE_H
  35
  36 #include "gnunet_util_lib.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #if 0 /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45
  46 /**
  47  * Key used for storing addresses in URL format in the peerstore
  48  */
  49 #define GNUNET_PEERSTORE_TRANSPORT_URLADDRESS_KEY "transport-communicator-url"
  50
  51 /**
  52  * Key used for storing HELLOs in the peerstore
  53  */
  54 #define GNUNET_PEERSTORE_TRANSPORT_HELLO_KEY "transport-peer-hello"
  55
  56 /**
  57  * Key used to store sender's monotonic time from backchannel
  58  * messages.
  59  */
  60 #define GNUNET_PEERSTORE_TRANSPORT_BACKCHANNEL_MONOTIME \
  61   "transport-backchannel-monotonic-time"
  62
  63 /**
  64  * Key used to store sender's monotonic time from DV learn
  65  * messages.
  66  */
  67 #define GNUNET_PEERSTORE_TRANSPORT_DVLEARN_MONOTIME \
  68   "transport-dv-learn-monotonic-time"
  69
  70
  71 /**
  72  * Options for storing values in PEERSTORE
  73  */
  74 enum GNUNET_PEERSTORE_StoreOption
  75 {
  76
  77   /**
  78    * Possibly store multiple values under given key.
  79    */
  80   GNUNET_PEERSTORE_STOREOPTION_MULTIPLE = 0,
  81
  82   /**
  83    * Delete any previous values for the given key before
  84    * storing the given value.
  85    */
  86   GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1
  87
  88 };
  89
  90 /**
  91  * Handle to the peerstore service.
  92  */
  93 struct GNUNET_PEERSTORE_Handle;
  94
  95 /**
  96  * Context for a store request
  97  */
  98 struct GNUNET_PEERSTORE_StoreContext;
  99
 100 /**
 101  * Single PEERSTORE record
 102  */
 103 struct GNUNET_PEERSTORE_Record
 104 {
 105
 106   /**
 107    * Responsible sub system string
 108    */
 109   char *sub_system;
 110
 111   /**
 112    * Peer Identity
 113    */
 114   struct GNUNET_PeerIdentity peer;
 115
 116   /**
 117    * Record key string
 118    */
 119   char *key;
 120
 121   /**
 122    * Record value BLOB
 123    */
 124   void *value;
 125
 126   /**
 127    * Size of @e value BLOB
 128    */
 129   size_t value_size;
 130
 131   /**
 132    * Expiry time of entry
 133    */
 134   struct GNUNET_TIME_Absolute expiry;
 135
 136   /**
 137    * Client from which this record originated.
 138    * NOTE: This is internal to the service.
 139    */
 140   struct GNUNET_SERVICE_Client *client;
 141 };
 142
 143
 144 /**
 145  * Continuation called with a status result.
 146  *
 147  * @param cls closure
 148  * @param success #GNUNET_OK or #GNUNET_SYSERR
 149  */
 150 typedef void (*GNUNET_PEERSTORE_Continuation) (void *cls, int success);
 151
 152
 153 /**
 154  * Function called by PEERSTORE for each matching record.
 155  *
 156  * @param cls closure
 157  * @param record peerstore record information
 158  * @param emsg error message, or NULL if no errors
 159  */
 160 typedef void (*GNUNET_PEERSTORE_Processor) (
 161   void *cls,
 162   const struct GNUNET_PEERSTORE_Record *record,
 163   const char *emsg);
 164
 165
 166 /**
 167  * Connect to the PEERSTORE service.
 168  *
 169  * @return NULL on error
 170  */
 171 struct GNUNET_PEERSTORE_Handle *
 172 GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 173
 174
 175 /**
 176  * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH requests
 177  * will be canceled.
 178  * Any pending STORE requests will depend on @e snyc_first flag.
 179  *
 180  * @param h handle to disconnect
 181  * @param sync_first send any pending STORE requests before disconnecting
 182  */
 183 void
 184 GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first);
 185
 186
 187 /**
 188  * Store a new entry in the PEERSTORE.
 189  * Note that stored entries can be lost in some cases
 190  * such as power failure.
 191  *
 192  * @param h Handle to the PEERSTORE service
 193  * @param sub_system name of the sub system
 194  * @param peer Peer Identity
 195  * @param key entry key
 196  * @param value entry value BLOB
 197  * @param size size of @e value
 198  * @param expiry absolute time after which the entry is (possibly) deleted
 199  * @param options options specific to the storage operation
 200  * @param cont Continuation function after the store request is sent
 201  * @param cont_cls Closure for @a cont
 202  */
 203 struct GNUNET_PEERSTORE_StoreContext *
 204 GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h,
 205                         const char *sub_system,
 206                         const struct GNUNET_PeerIdentity *peer,
 207                         const char *key,
 208                         const void *value,
 209                         size_t size,
 210                         struct GNUNET_TIME_Absolute expiry,
 211                         enum GNUNET_PEERSTORE_StoreOption options,
 212                         GNUNET_PEERSTORE_Continuation cont,
 213                         void *cont_cls);
 214
 215
 216 /**
 217  * Cancel a store request
 218  *
 219  * @param sc Store request context
 220  */
 221 void
 222 GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc);
 223
 224
 225 /**
 226  * Iterate over records matching supplied key information
 227  *
 228  * @param h handle to the PEERSTORE service
 229  * @param sub_system name of sub system
 230  * @param peer Peer identity (can be NULL)
 231  * @param key entry key string (can be NULL)
 232  * @param callback function called with each matching record, all NULL's on end
 233  * @param callback_cls closure for @a callback
 234  */
 235 struct GNUNET_PEERSTORE_IterateContext *
 236 GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h,
 237                           const char *sub_system,
 238                           const struct GNUNET_PeerIdentity *peer,
 239                           const char *key,
 240                           GNUNET_PEERSTORE_Processor callback,
 241                           void *callback_cls);
 242
 243
 244 /**
 245  * Cancel an iterate request
 246  * Please do not call after the iterate request is done
 247  *
 248  * @param ic Iterate request context as returned by GNUNET_PEERSTORE_iterate()
 249  */
 250 void
 251 GNUNET_PEERSTORE_iterate_cancel (struct GNUNET_PEERSTORE_IterateContext *ic);
 252
 253
 254 /**
 255  * Request watching a given key
 256  * User will be notified with any new values added to key.
 257  *
 258  * @param h handle to the PEERSTORE service
 259  * @param sub_system name of sub system
 260  * @param peer Peer identity
 261  * @param key entry key string
 262  * @param callback function called with each new value
 263  * @param callback_cls closure for @a callback
 264  * @return Handle to watch request
 265  */
 266 struct GNUNET_PEERSTORE_WatchContext *
 267 GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h,
 268                         const char *sub_system,
 269                         const struct GNUNET_PeerIdentity *peer,
 270                         const char *key,
 271                         GNUNET_PEERSTORE_Processor callback,
 272                         void *callback_cls);
 273
 274
 275 /**
 276  * Cancel a watch request
 277  *
 278  * @param wc handle to the watch request
 279  */
 280 void
 281 GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc);
 282
 283
 284 #if 0 /* keep Emacsens' auto-indent happy */
 285 {
 286 #endif
 287 #ifdef __cplusplus
 288 }
 289 #endif
 290
 291 #endif
 292
 293 /** @} */ /* end of group */