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