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