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