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