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