src/include/gnunet_psycstore_plugin.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2012, 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_EccPublicKey *channel_key,
  64                        const struct GNUNET_CRYPTO_EccPublicKey *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_EccPublicKey *channel_key,
  81                       const struct GNUNET_CRYPTO_EccPublicKey *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_EccPublicKey *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 message_id ID of the message.
 103    * @param psycstore_flags OR'd GNUNET_PSYCSTORE_MessageFlags.
 104    *
 105    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 106    */
 107   int
 108   (*message_add_flags) (void *cls,
 109                         const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 110                         uint64_t message_id,
 111                         uint64_t psycstore_flags);
 112
 113   /**
 114    * Retrieve a message fragment by fragment ID.
 115    *
 116    * @see GNUNET_PSYCSTORE_fragment_get()
 117    *
 118    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 119    */
 120   int
 121   (*fragment_get) (void *cls,
 122                    const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 123                    uint64_t fragment_id,
 124                    GNUNET_PSYCSTORE_FragmentCallback cb,
 125                    void *cb_cls);
 126
 127   /**
 128    * Retrieve all fragments of a message.
 129    *
 130    * @see GNUNET_PSYCSTORE_message_get()
 131    *
 132    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 133    */
 134   int
 135   (*message_get) (void *cls,
 136                   const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 137                   uint64_t message_id,
 138                   GNUNET_PSYCSTORE_FragmentCallback cb,
 139                   void *cb_cls);
 140
 141   /**
 142    * Retrieve a fragment of message specified by its message ID and fragment
 143    * offset.
 144    *
 145    * @see GNUNET_PSYCSTORE_message_get_fragment()
 146    *
 147    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 148    */
 149   int
 150   (*message_get_fragment) (void *cls,
 151                            const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 152                            uint64_t message_id,
 153                            uint64_t fragment_offset,
 154                            GNUNET_PSYCSTORE_FragmentCallback cb,
 155                            void *cb_cls);
 156
 157   /**
 158    * Retrieve latest values of counters for a channel master.
 159    *
 160    * @see GNUNET_PSYCSTORE_counters_get_master()
 161    *
 162    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 163    */
 164   int
 165   (*counters_get_master) (void *cls,
 166                           const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 167                           uint64_t *fragment_id,
 168                           uint64_t *message_id,
 169                           uint64_t *group_generation);
 170
 171   /**
 172    * Retrieve latest values of counters for a channel slave.
 173    *
 174    * @see GNUNET_PSYCSTORE_counters_get_slave()
 175    *
 176    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 177    */
 178   int
 179   (*counters_get_slave) (void *cls,
 180                          const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 181                          uint64_t *max_state_msg_id);
 182
 183   /**
 184    * Set a state variable to the given value.
 185    *
 186    * @see GNUNET_PSYCSTORE_state_modify()
 187    *
 188    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 189    */
 190   int
 191   (*state_set) (void *cls,
 192                 const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 193                 const char *name,
 194                 const void *value,
 195                 size_t value_size);
 196
 197
 198   /**
 199    * Reset the state of a channel.
 200    *
 201    * Delete all state variables stored for the given channel.
 202    *
 203    * @see GNUNET_PSYCSTORE_state_reset()
 204    *
 205    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 206    */
 207   int
 208   (*state_reset) (void *cls,
 209                   const struct GNUNET_CRYPTO_EccPublicKey *channel_key);
 210
 211   /**
 212    * Update signed state values from the current ones.
 213    *
 214    * Sets value_signed = value_current for each variable for the given channel.
 215    */
 216   int
 217   (*state_update_signed) (void *cls,
 218                           const struct GNUNET_CRYPTO_EccPublicKey *channel_key);
 219
 220   /**
 221    * Update signed values of state variables in the state store.
 222    *
 223    * @param h Handle for the PSYCstore.
 224    * @param channel_key The channel we are interested in.
 225    * @param message_id Message ID that contained the state @a hash.
 226    * @param hash Hash of the serialized full state.
 227    * @param rcb Callback to call with the result of the operation.
 228    * @param rcb_cls Closure for the callback.
 229    *
 230    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 231    */
 232   int
 233   (*state_hash_update) (void *cls,
 234                         const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 235                         uint64_t message_id,
 236                         const struct GNUNET_HashCode *hash,
 237                         GNUNET_PSYCSTORE_ResultCallback rcb,
 238                         void *rcb_cls);
 239
 240   /**
 241    * Retrieve a state variable by name (exact match).
 242    *
 243    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 244    */
 245   int
 246   (*state_get) (void *cls,
 247                 const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 248                 const char *name,
 249                 GNUNET_PSYCSTORE_StateCallback cb,
 250                 void *cb_cls);
 251
 252   /**
 253    * Retrieve all state variables for a channel with the given prefix.
 254    *
 255    * @see GNUNET_PSYCSTORE_state_get_all()
 256    *
 257    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 258    */
 259   int
 260   (*state_get_all) (void *cls,
 261                     const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 262                     const char *name,
 263                     GNUNET_PSYCSTORE_StateCallback cb,
 264                     void *cb_cls);
 265
 266
 267   /**
 268    * Retrieve all signed state variables for a channel.
 269    *
 270    * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 271    */
 272   int
 273   (*state_get_signed) (void *cls,
 274                        const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 275                        GNUNET_PSYCSTORE_StateCallback cb,
 276                        void *cb_cls);
 277
 278 };
 279
 280
 281 #if 0                           /* keep Emacsens' auto-indent happy */
 282 {
 283 #endif
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 /* end of gnunet_psycstore_plugin.h */
 289 #endif