src/include/gnunet_psycstore_service.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_service.h
  23  * @brief PSYCstore service; implements persistent storage for the PSYC service
  24  * @author Gabor X Toth
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_PSYCSTORE_SERVICE_H
  28 #define GNUNET_PSYCSTORE_SERVICE_H
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 #include "gnunet_util_lib.h"
  39 #include "gnunet_env_lib.h"
  40
  41 /**
  42  * Version number of GNUnet PSYCstore API.
  43  */
  44 #define GNUNET_PSYCSTORE_VERSION 0x00000000
  45
  46 /**
  47  * Handle for a PSYCstore
  48  */
  49 struct GNUNET_PSYCSTORE_Handle;
  50
  51
  52 /**
  53  * Connect to the PSYCstore service.
  54  *
  55  * @param cfg Configuration to use.
  56  *
  57  * @return Handle for the connecton.
  58  */
  59 struct GNUNET_PSYCSTORE_Handle *
  60 GNUNET_PSYCSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
  61
  62
  63 /**
  64  * Disconnect from the PSYCstore service.
  65  *
  66  * @param h Handle for the connection.
  67  */
  68 void
  69 GNUNET_PSYCSTORE_disconnect (struct GNUNET_PSYCSTORE_Handle *h);
  70
  71
  72 /**
  73  * Handle for an operation on the PSYCSTORE (useful to cancel the operation).
  74  */
  75 struct GNUNET_PSYCSTORE_OperationHandle;
  76
  77
  78 /**
  79  * Function called with the result of an asynchronous operation.
  80  *
  81  * @param result #GNUNET_SYSERR on error,
  82  *        #GNUNET_YES on success or if the peer was a member,
  83  *        #GNUNET_NO if the peer was not a member
  84  */
  85 typedef void (*GNUNET_PSYCSTORE_ResultCallback)(void *cls,
  86                                                 int result);
  87
  88 /**
  89  * Store join/leave events for a PSYC channel in order to be able to answer
  90  * membership test queries later.
  91  *
  92  * @param h Handle for the PSYCstore.
  93  * @param channel_key The channel where the event happened.
  94  * @param slave_key Public key of joining/leaving slave.
  95  * @param announced_at ID of the message that announced the membership change.
  96  * @param effective_since Message ID this membership change is in effect since.
  97  * @param did_join #GNUNET_YES on join, #GNUNET_NO on part.
  98  * @param rcb Callback to call with the result of the storage operation.
  99  * @param rcb_cls Closure for the callback.
 100  *
 101  * @return Operation handle that can be used to cancel the operation.
 102  */
 103 struct GNUNET_PSYCSTORE_OperationHandle *
 104 GNUNET_PSYCSTORE_membership_store (struct GNUNET_PSYCSTORE_Handle *h,
 105                                    const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 106                                    const struct GNUNET_CRYPTO_EccPublicKey *slave_key,
 107                                    uint64_t announced_at,
 108                                    uint64_t effective_since,
 109                                    int did_join,
 110                                    GNUNET_PSYCSTORE_ResultCallback rcb,
 111                                    void *rcb_cls);
 112
 113
 114 /**
 115  * Test if a peer was a member of the channel when the message fragment with the
 116  * specified ID was sent to the channel.
 117  *
 118  * This is useful in case of retransmissions to check if the peer was authorized
 119  * to see the requested message.
 120  *
 121  * @param h Handle for the PSYCstore.
 122  * @param channel_key The channel we are interested in.
 123  * @param slave_key Public key of slave whose membership to check.
 124  * @param fragment_id Message fragment ID to check.
 125  * @param rcb Callback to call with the test result.
 126  * @param rcb_cls Closure for the callback.
 127  *
 128  * @return Operation handle that can be used to cancel the operation.
 129  */
 130 struct GNUNET_PSYCSTORE_OperationHandle *
 131 GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h,
 132                                   const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 133                                   const struct GNUNET_CRYPTO_EccPublicKey *slave_key,
 134                                   uint64_t fragment_id,
 135                                   GNUNET_PSYCSTORE_ResultCallback rcb,
 136                                   void *rcb_cls);
 137
 138
 139 /**
 140  * Store a message fragment sent to a channel.
 141  *
 142  * @param h Handle for the PSYCstore.
 143  * @param channel_key The channel the message belongs to.
 144  * @param message Message to store.
 145  * @param rcb Callback to call with the result of the operation.
 146  * @param rcb_cls Closure for the callback.
 147  *
 148  * @return Handle that can be used to cancel the operation.
 149  */
 150 struct GNUNET_PSYCSTORE_OperationHandle *
 151 GNUNET_PSYCSTORE_fragment_store (struct GNUNET_PSYCSTORE_Handle *h,
 152                                  const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 153                                  const struct GNUNET_MULTICAST_MessageHeader *message,
 154                                  GNUNET_PSYCSTORE_ResultCallback rcb,
 155                                  void *rcb_cls);
 156
 157
 158 /**
 159  * Function called with one message fragment, as the result of a
 160  * GNUNET_PSYCSTORE_fragment_get() or GNUNET_PSYCSTORE_message_get() call.
 161  *
 162  * @param cls Closure.
 163  * @param message The retrieved message fragment.
 164  * @param flags Message flags indicating fragmentation status.
 165  */
 166 typedef void (*GNUNET_PSYCSTORE_FragmentResultCallback)(void *cls,
 167                                                        const struct GNUNET_MULTICAST_MessageHeader *message,
 168                                                        enum GNUNET_PSYC_MessageFlags flags);
 169
 170
 171 /**
 172  * Retrieve a message fragment by fragment ID.
 173  *
 174  * @param h Handle for the PSYCstore.
 175  * @param channel_key The channel we are interested in.
 176  * @param fragment_id Fragment ID to check.  Use 0 to get the latest message fragment.
 177  * @param rcb Callback to call with the result of the operation.
 178  * @param rcb_cls Closure for the callback.
 179  *
 180  * @return Handle that can be used to cancel the operation.
 181  */
 182 struct GNUNET_PSYCSTORE_OperationHandle *
 183 GNUNET_PSYCSTORE_fragment_get (struct GNUNET_PSYCSTORE_Handle *h,
 184                                const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 185                                uint64_t fragment_id,
 186                                GNUNET_PSYCSTORE_FragmentResultCallback rcb,
 187                                void *rcb_cls);
 188
 189
 190 /**
 191  * Retrieve a message by ID.
 192  *
 193  * @param h Handle for the PSYCstore.
 194  * @param channel_key The channel we are interested in.
 195  * @param message_id Message ID to check.  Use 0 to get the latest message.
 196  * @param rcb Callback to call with the result of the operation.
 197  * @param rcb_cls Closure for the callback.
 198  *
 199  * @return Handle that can be used to cancel the operation.
 200  */
 201 struct GNUNET_PSYCSTORE_OperationHandle *
 202 GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
 203                               const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 204                               uint64_t message_id,
 205                               GNUNET_PSYCSTORE_FragmentResultCallback rcb,
 206                               void *rcb_cls);
 207
 208
 209 /**
 210  * Modify the channel state.
 211  *
 212  * Applies the operation to the current channel state.
 213  *
 214  * An error is returned if there are missing messages containing state
 215  * operations before the current one.
 216  *
 217  * @param h Handle for the PSYCstore.
 218  * @param channel_key The channel we are interested in.
 219  * @param message_id ID of the message that contains this state modifier.
 220  * @param oper Operation to perform.
 221  * @param name Name of variable.
 222  * @param value_size Size of @a value.
 223  * @param value Value of variable.
 224  * @param rcb Callback to call with the result of the operation.
 225  * @param rcb_cls Closure for the callback.
 226  *
 227  * @return Handle that can be used to cancel the operation.
 228  */
 229 struct GNUNET_PSYCSTORE_OperationHandle *
 230 GNUNET_PSYCSTORE_state_modify (struct GNUNET_PSYCSTORE_Handle *h,
 231                                const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 232                                uint64_t message_id,
 233                                enum GNUNET_ENV_Operator *oper,
 234                                const char *name,
 235                                size_t value_size,
 236                                const void *value,
 237                                GNUNET_PSYCSTORE_ResultCallback rcb,
 238                                void *rcb_cls);
 239
 240
 241 /**
 242  * Function called with the value of a state variable.
 243  *
 244  * @param cls Closure.
 245  * @param name Name of variable.
 246  * @param size Size of @a value.
 247  * @param value Value of variable.
 248 t *
 249  */
 250 typedef void (*GNUNET_PSYCSTORE_StateResultCallback)(void *cls,
 251                                                      const char *name,
 252                                                      size_t size,
 253                                                      const void *value);
 254
 255
 256 /**
 257  * Retrieve the given state variable for a channel.
 258  *
 259  * @param h Handle for the PSYCstore.
 260  * @param channel_key The channel we are interested in.
 261  * @param name Name of variable to get.
 262  * @param rcb Callback to call with the result.
 263  * @param rcb_cls Closure for the callback.
 264  *
 265  * @return Handle that can be used to cancel the operation.
 266  */
 267 struct GNUNET_PSYCSTORE_OperationHandle *
 268 GNUNET_PSYCSTORE_state_get (struct GNUNET_PSYCSTORE_Handle *h,
 269                             const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 270                             const char *name,
 271                             GNUNET_PSYCSTORE_StateResultCallback rcb,
 272                             void *rcb_cls);
 273
 274
 275 /**
 276  * Retrieve all state variables for a channel.
 277  *
 278  * @param h Handle for the PSYCstore.
 279  * @param channel_key The channel we are interested in.
 280  * @param rcb Callback to call with the result.
 281  * @param rcb_cls Closure for the callback.
 282  *
 283  * @return Handle that can be used to cancel the operation.
 284  */
 285 struct GNUNET_PSYCSTORE_OperationHandle *
 286 GNUNET_PSYCSTORE_state_get_all (struct GNUNET_PSYCSTORE_Handle *h,
 287                                 const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
 288                                 GNUNET_PSYCSTORE_StateResultCallback rcb,
 289                                 void *rcb_cls);
 290
 291
 292 /**
 293  * Cancel an operation.
 294  *
 295  * @param oh Handle for the operation to cancel.
 296  */
 297 void
 298 GNUNET_PSYCSTORE_operation_cancel (struct GNUNET_PSYCSTORE_OperationHandle *oh);
 299
 300
 301
 302
 303 #if 0                           /* keep Emacsens' auto-indent happy */
 304 {
 305 #endif
 306 #ifdef __cplusplus
 307 }
 308 #endif
 309
 310 /* ifndef GNUNET_PSYCSTORE_SERVICE_H */
 311 #endif
 312 /* end of gnunet_psycstore_service.h */