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