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