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