src/include/gnunet_psycstore_plugin.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2013 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_psycstore_plugin.h
  23  * @brief plugin API for the PSYCstore database backend
  24  * @author Gabor X Toth
  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_EddsaPublicKey *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_EddsaPublicKey *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                         uint64_t psycstore_flags);
 113
 114   /**
 115    * Retrieve a message fragment 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 fragment_id,
 125                    GNUNET_PSYCSTORE_FragmentCallback cb,
 126                    void *cb_cls);
 127
 128   /**
 129    * Retrieve all fragments of a message.
 130    *
 131    * @see GNUNET_PSYCSTORE_message_get()
 132    *
 133    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 134    */
 135   int
 136   (*message_get) (void *cls,
 137                   const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 138                   uint64_t message_id,
 139                   uint64_t *returned_fragments,
 140                   GNUNET_PSYCSTORE_FragmentCallback cb,
 141                   void *cb_cls);
 142
 143   /**
 144    * Retrieve a fragment of message specified by its message ID and fragment
 145    * offset.
 146    *
 147    * @see GNUNET_PSYCSTORE_message_get_fragment()
 148    *
 149    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 150    */
 151   int
 152   (*message_get_fragment) (void *cls,
 153                            const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 154                            uint64_t message_id,
 155                            uint64_t fragment_offset,
 156                            GNUNET_PSYCSTORE_FragmentCallback cb,
 157                            void *cb_cls);
 158
 159   /**
 160    * Retrieve the max. values of message counters for a channel.
 161    *
 162    * @see GNUNET_PSYCSTORE_counters_get()
 163    *
 164    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 165    */
 166   int
 167   (*counters_message_get) (void *cls,
 168                            const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 169                            uint64_t *max_fragment_id,
 170                            uint64_t *max_message_id,
 171                            uint64_t *max_group_generation);
 172
 173   /**
 174    * Retrieve the max. values of state counters for a channel.
 175    *
 176    * @see GNUNET_PSYCSTORE_counters_get()
 177    *
 178    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 179    */
 180   int
 181   (*counters_state_get) (void *cls,
 182                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 183                          uint64_t *max_state_message_id);
 184
 185
 186   /**
 187    * Begin modifying current state.
 188    *
 189    * @see GNUNET_PSYCSTORE_state_modify()
 190    *
 191    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 192    */
 193   int
 194   (*state_modify_begin) (void *cls,
 195                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 196                          uint64_t message_id, uint64_t state_delta);
 197
 198   /**
 199    * Set the current value of a state variable.
 200    *
 201    * The state modification process is started with state_modify_begin(),
 202    * which is followed by one or more calls to this function,
 203    * and finished with state_modify_end().
 204    *
 205    * @see GNUNET_PSYCSTORE_state_modify()
 206    *
 207    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 208    */
 209   int
 210   (*state_modify_set) (void *cls,
 211                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 212                        const char *name, const void *value, size_t value_size);
 213
 214
 215   /**
 216    * End modifying current state.
 217    *
 218    * @see GNUNET_PSYCSTORE_state_modify()
 219    *
 220    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 221    */
 222   int
 223   (*state_modify_end) (void *cls,
 224                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 225                        uint64_t message_id);
 226
 227
 228   /**
 229    * Begin synchronizing state.
 230    *
 231    * @see GNUNET_PSYCSTORE_state_sync()
 232    *
 233    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 234    */
 235   int
 236   (*state_sync_begin) (void *cls,
 237                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
 238
 239   /**
 240    * Set the value of a state variable while synchronizing state.
 241    *
 242    * The state synchronization process is started with state_sync_begin(),
 243    * which is followed by one or more calls to this function,
 244    * and finished with state_sync_end().
 245    *
 246    * @see GNUNET_PSYCSTORE_state_sync()
 247    *
 248    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 249    */
 250   int
 251   (*state_sync_set) (void *cls,
 252                      const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 253                      const char *name, const void *value, size_t value_size);
 254
 255
 256   /**
 257    * End synchronizing state.
 258    *
 259    * @see GNUNET_PSYCSTORE_state_sync()
 260    *
 261    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 262    */
 263   int
 264   (*state_sync_end) (void *cls,
 265                      const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 266                      uint64_t message_id);
 267
 268
 269   /**
 270    * Reset the state of a channel.
 271    *
 272    * Delete all state variables stored for the given channel.
 273    *
 274    * @see GNUNET_PSYCSTORE_state_reset()
 275    *
 276    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 277    */
 278   int
 279   (*state_reset) (void *cls,
 280                   const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
 281
 282   /**
 283    * Update signed state values from the current ones.
 284    *
 285    * Sets value_signed = value_current for each variable for the given channel.
 286    */
 287   int
 288   (*state_update_signed) (void *cls,
 289                           const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
 290
 291
 292   /**
 293    * Retrieve a state variable by name (exact match).
 294    *
 295    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 296    */
 297   int
 298   (*state_get) (void *cls,
 299                 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 300                 const char *name,
 301                 GNUNET_PSYCSTORE_StateCallback cb,
 302                 void *cb_cls);
 303
 304   /**
 305    * Retrieve all state variables for a channel with the given prefix.
 306    *
 307    * @see GNUNET_PSYCSTORE_state_get_prefix()
 308    *
 309    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 310    */
 311   int
 312   (*state_get_prefix) (void *cls,
 313                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 314                        const char *name,
 315                        GNUNET_PSYCSTORE_StateCallback cb,
 316                        void *cb_cls);
 317
 318
 319   /**
 320    * Retrieve all signed state variables for a channel.
 321    *
 322    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 323    */
 324   int
 325   (*state_get_signed) (void *cls,
 326                        const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
 327                        GNUNET_PSYCSTORE_StateCallback cb,
 328                        void *cb_cls);
 329
 330 };
 331
 332
 333 #if 0                           /* keep Emacsens' auto-indent happy */
 334 {
 335 #endif
 336 #ifdef __cplusplus
 337 }
 338 #endif
 339
 340 /* end of gnunet_psycstore_plugin.h */
 341 #endif