src/include/gnunet_psycstore_plugin.h

   1 /*
   2      This file is part of GNUnet
   3      Copyright (C) 2013 GNUnet e.V.
   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
  16 /**
  17  * @author Gabor X Toth
  18  *
  19  * @file
  20  * Plugin API for the PSYCstore database backend
  21  *
  22  * @defgroup psycstore-plugin  PSYC Store plugin API
  23  * Plugin API for the PSYC Store database backend
  24  * @{
  25  */
  26 #ifndef GNUNET_PSYCSTORE_PLUGIN_H
  27 #define GNUNET_PSYCSTORE_PLUGIN_H
  28
  29 #include "gnunet_util_lib.h"
  30 #include "gnunet_psycstore_service.h"
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40
  41 /**
  42  * Struct returned by the initialization function of the plugin.
  43  */
  44 struct GNUNET_PSYCSTORE_PluginFunctions
  45 {
  46
  47   /**
  48    * Closure to pass to all plugin functions.
  49    */
  50   void *cls;
  51
  52   /**
  53    * Store join/leave events for a PSYC channel in order to be able to answer
  54    * membership test queries later.
  55    *
  56    * @see GNUNET_PSYCSTORE_membership_store()
  57    *
  58    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
  59    */
  60   int
  61   (*membership_store) (void *cls,
  62                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
  63                        const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
  64                        int did_join,
  65                        uint64_t announced_at,
  66                        uint64_t effective_since,
  67                        uint64_t group_generation);
  68
  69   /**
  70    * Test if a member was admitted to the channel at the given message ID.
  71    *
  72    * @see GNUNET_PSYCSTORE_membership_test()
  73    *
  74    * @return #GNUNET_YES if the member was admitted, #GNUNET_NO if not,
  75    *         #GNUNET_SYSERR if there was en error.
  76    */
  77   int
  78   (*membership_test) (void *cls,
  79                       const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
  80                       const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
  81                       uint64_t message_id);
  82
  83   /**
  84    * Store a message fragment sent to a channel.
  85    *
  86    * @see GNUNET_PSYCSTORE_fragment_store()
  87    *
  88    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
  89    */
  90   int
  91   (*fragment_store) (void *cls,
  92                      const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
  93                      const struct GNUNET_MULTICAST_MessageHeader *message,
  94                      uint32_t psycstore_flags);
  95
  96   /**
  97    * Set additional flags for a given message.
  98    *
  99    * They are OR'd with any existing flags set.
 100    *
 101    * @param cls Closure.
 102    * @param channel_key Public key of the channel.
 103    * @param message_id ID of the message.
 104    * @param psycstore_flags OR'd GNUNET_PSYCSTORE_MessageFlags.
 105    *
 106    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 107    */
 108   int
 109   (*message_add_flags) (void *cls,
 110                         const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 111                         uint64_t message_id,
 112                         uint32_t psycstore_flags);
 113
 114   /**
 115    * Retrieve a message fragment range by fragment ID.
 116    *
 117    * @see GNUNET_PSYCSTORE_fragment_get()
 118    *
 119    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 120    */
 121   int
 122   (*fragment_get) (void *cls,
 123                    const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 124                    uint64_t first_fragment_id,
 125                    uint64_t last_fragment_id,
 126                    uint64_t *returned_fragments,
 127                    GNUNET_PSYCSTORE_FragmentCallback cb,
 128                    void *cb_cls);
 129
 130   /**
 131    * Retrieve latest message fragments.
 132    *
 133    * @see GNUNET_PSYCSTORE_fragment_get()
 134    *
 135    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 136    */
 137   int
 138   (*fragment_get_latest) (void *cls,
 139                           const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 140                           uint64_t fragment_limit,
 141                           uint64_t *returned_fragments,
 142                           GNUNET_PSYCSTORE_FragmentCallback cb,
 143                           void *cb_cls);
 144
 145   /**
 146    * Retrieve all fragments of a message ID range.
 147    *
 148    * @see GNUNET_PSYCSTORE_message_get()
 149    *
 150    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 151    */
 152   int
 153   (*message_get) (void *cls,
 154                   const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 155                   uint64_t first_fragment_id,
 156                   uint64_t last_fragment_id,
 157                   uint64_t fragment_limit,
 158                   uint64_t *returned_fragments,
 159                   GNUNET_PSYCSTORE_FragmentCallback cb,
 160                   void *cb_cls);
 161
 162   /**
 163    * Retrieve all fragments of the latest messages.
 164    *
 165    * @see GNUNET_PSYCSTORE_message_get()
 166    *
 167    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 168    */
 169   int
 170   (*message_get_latest) (void *cls,
 171                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 172                          uint64_t fragment_limit,
 173                          uint64_t *returned_fragments,
 174                          GNUNET_PSYCSTORE_FragmentCallback cb,
 175                          void *cb_cls);
 176
 177   /**
 178    * Retrieve a fragment of message specified by its message ID and fragment
 179    * offset.
 180    *
 181    * @see GNUNET_PSYCSTORE_message_get_fragment()
 182    *
 183    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 184    */
 185   int
 186   (*message_get_fragment) (void *cls,
 187                            const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 188                            uint64_t message_id,
 189                            uint64_t fragment_offset,
 190                            GNUNET_PSYCSTORE_FragmentCallback cb,
 191                            void *cb_cls);
 192
 193   /**
 194    * Retrieve the max. values of message counters for a channel.
 195    *
 196    * @see GNUNET_PSYCSTORE_counters_get()
 197    *
 198    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 199    */
 200   int
 201   (*counters_message_get) (void *cls,
 202                            const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 203                            uint64_t *max_fragment_id,
 204                            uint64_t *max_message_id,
 205                            uint64_t *max_group_generation);
 206
 207   /**
 208    * Retrieve the max. values of state counters for a channel.
 209    *
 210    * @see GNUNET_PSYCSTORE_counters_get()
 211    *
 212    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 213    */
 214   int
 215   (*counters_state_get) (void *cls,
 216                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 217                          uint64_t *max_state_message_id);
 218
 219
 220   /**
 221    * Begin modifying current state.
 222    *
 223    * @see GNUNET_PSYCSTORE_state_modify()
 224    *
 225    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 226    */
 227   int
 228   (*state_modify_begin) (void *cls,
 229                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 230                          uint64_t message_id, uint64_t state_delta);
 231
 232   /**
 233    * Set the current value of a state variable.
 234    *
 235    * The state modification process is started with state_modify_begin(),
 236    * which is followed by one or more calls to this function,
 237    * and finished with state_modify_end().
 238    *
 239    * @see GNUNET_PSYCSTORE_state_modify()
 240    *
 241    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 242    */
 243   int
 244   (*state_modify_op) (void *cls,
 245                       const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 246                       enum GNUNET_PSYC_Operator op,
 247                       const char *name, const void *value, size_t value_size);
 248
 249
 250   /**
 251    * End modifying current state.
 252    *
 253    * @see GNUNET_PSYCSTORE_state_modify()
 254    *
 255    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 256    */
 257   int
 258   (*state_modify_end) (void *cls,
 259                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 260                        uint64_t message_id);
 261
 262
 263   /**
 264    * Begin synchronizing state.
 265    *
 266    * @see GNUNET_PSYCSTORE_state_sync()
 267    *
 268    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 269    */
 270   int
 271   (*state_sync_begin) (void *cls,
 272                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
 273
 274   /**
 275    * Assign value of a state variable while synchronizing state.
 276    *
 277    * The state synchronization process is started with state_sync_begin(),
 278    * which is followed by one or more calls to this function,
 279    * and finished using state_sync_end().
 280    *
 281    * @see GNUNET_PSYCSTORE_state_sync()
 282    *
 283    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 284    */
 285   int
 286   (*state_sync_assign) (void *cls,
 287                         const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 288                         const char *name, const void *value, size_t value_size);
 289
 290
 291   /**
 292    * End synchronizing state.
 293    *
 294    * @see GNUNET_PSYCSTORE_state_sync()
 295    *
 296    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 297    */
 298   int
 299   (*state_sync_end) (void *cls,
 300                      const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 301                      uint64_t max_state_message_id,
 302                      uint64_t state_hash_message_id);
 303
 304
 305   /**
 306    * Reset the state of a channel.
 307    *
 308    * Delete all state variables stored for the given channel.
 309    *
 310    * @see GNUNET_PSYCSTORE_state_reset()
 311    *
 312    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 313    */
 314   int
 315   (*state_reset) (void *cls,
 316                   const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
 317
 318   /**
 319    * Update signed state values from the current ones.
 320    *
 321    * Sets value_signed = value_current for each variable for the given channel.
 322    */
 323   int
 324   (*state_update_signed) (void *cls,
 325                           const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
 326
 327
 328   /**
 329    * Retrieve a state variable by name (exact match).
 330    *
 331    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 332    */
 333   int
 334   (*state_get) (void *cls,
 335                 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 336                 const char *name,
 337                 GNUNET_PSYCSTORE_StateCallback cb,
 338                 void *cb_cls);
 339
 340   /**
 341    * Retrieve all state variables for a channel with the given prefix.
 342    *
 343    * @see GNUNET_PSYCSTORE_state_get_prefix()
 344    *
 345    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 346    */
 347   int
 348   (*state_get_prefix) (void *cls,
 349                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 350                        const char *name,
 351                        GNUNET_PSYCSTORE_StateCallback cb,
 352                        void *cb_cls);
 353
 354
 355   /**
 356    * Retrieve all signed state variables for a channel.
 357    *
 358    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 359    */
 360   int
 361   (*state_get_signed) (void *cls,
 362                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 363                        GNUNET_PSYCSTORE_StateCallback cb,
 364                        void *cb_cls);
 365
 366 };
 367
 368
 369 #if 0                           /* keep Emacsens' auto-indent happy */
 370 {
 371 #endif
 372 #ifdef __cplusplus
 373 }
 374 #endif
 375
 376 #endif
 377
 378 /** @} */  /* end of group */