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 tg
  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  *
  79  * @param result GNUNET_SYSERR on error,
  80  *        GNUNET_YES on success or if the peer was a member,
  81  *        GNUNET_NO if the peer was not a member
  82  */
  83 typedef void (*GNUNET_PSYCSTORE_ContinuationCallback)(void *cls,
  84                                                       int result);
  85
  86 /**
  87  * Store join/leave events for a PSYC channel in order to be able to answer
  88  * membership test queries later.
  89  *
  90  * @param h Handle for the PSYCstore.
  91  * @param channel_id ID of the channel where the event happened.
  92  * @param message_id ID of the message in which this event was announced.
  93  * @param peer Identity of joining/leaving peer.
  94  * @param did_join GNUNET_YES on join, GNUNET_NO on leave.
  95  * @param ccb Callback to call with the result of the storage operation.
  96  * @param ccb_cls Closure for the callback.
  97  *
  98  * @return Operation handle that can be used to cancel the operation.
  99  */
 100 struct GNUNET_PSYCSTORE_OperationHandle *
 101 GNUNET_PSYCSTORE_membership_store (struct GNUNET_PSYCSTORE_Handle *h,
 102                                    const struct GNUNET_HashCode *channel_id,
 103                                    uint64_t message_id,
 104                                    const struct GNUNET_PeerIdentity *peer,
 105                                    int did_join,
 106                                    GNUNET_PSYCSTORE_ContinuationCallback ccb,
 107                                    void *ccb_cls);
 108
 109
 110 /**
 111  * Test if a peer was a member of the channel when the message with the
 112  * specified ID was sent to the channel. This is useful in case of
 113  * retransmissions to check if the peer was authorized to see the requested
 114  * message.
 115  *
 116  * @param h Handle for the PSYCstore.
 117  * @param channel_id The channel we are interested in.
 118  * @param message_id Message ID to check.
 119  * @param peer Peer whose membership to check.
 120  * @param ccb Callback to call with the test result.
 121  * @param ccb_cls Closure for the callback.
 122  *
 123  * @return Operation handle that can be used to cancel the operation.
 124  */struct GNUNET_PSYCSTORE_OperationHandle *
 125 GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h,
 126                                   const struct GNUNET_HashCode *channel_id,
 127                                   uint64_t message_id,
 128                                   const struct GNUNET_PeerIdentity *peer,
 129                                   GNUNET_PSYCSTORE_ContinuationCallback ccb,
 130                                   void *ccb_cls);
 131
 132
 133 struct GNUNET_PSYCSTORE_OperationHandle *
 134 GNUNET_PSYCSTORE_message_store (struct GNUNET_PSYCSTORE_Handle *h,
 135                                 const struct GNUNET_HashCode *channel_id,
 136                                 const struct GNUNET_MULTICAST_MessageHeader *message,
 137                                 GNUNET_PSYCSTORE_ContinuationCallback ccb,
 138                                 void *ccb_cls);
 139
 140
 141 typedef void (*GNUNET_PSYCSTORE_MessageResultCallback)(void *cls,
 142                                                        uint64_t message_id,
 143                                                        const struct GNUNET_MULTICAST_MessageHeader *message);
 144
 145
 146 struct GNUNET_PSYCSTORE_OperationHandle *
 147 GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
 148                               const struct GNUNET_HashCode *channel_id,
 149                               uint64_t message_id,
 150                               GNUNET_PSYCSTORE_MessageResultCallback rcb,
 151                               void *rcb_cls);
 152
 153
 154 struct GNUNET_PSYCSTORE_OperationHandle *
 155 GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
 156                                      const struct GNUNET_HashCode *channel_id,
 157                                      GNUNET_PSYCSTORE_MessageResultCallback rcb,
 158                                      void *rcb_cls);
 159
 160
 161 struct GNUNET_PSYCSTORE_OperationHandle *
 162 GNUNET_PSYCSTORE_state_set (struct GNUNET_PSYCSTORE_Handle *h,
 163                             const struct GNUNET_HashCode *channel_id,
 164                             const char *state_name,
 165                             size_t size,
 166                             const void *value,
 167                             GNUNET_PSYCSTORE_ContinuationCallback ccb,
 168                             void *ccb_cls);
 169
 170
 171 typedef void (*GNUNET_PSYCSTORE_StateResultCallback)(void *cls,
 172                                                      const char *state_name,
 173                                                      size_t size,
 174                                                      const void *value);
 175
 176
 177 struct GNUNET_PSYCSTORE_OperationHandle *
 178 GNUNET_PSYCSTORE_state_get (struct GNUNET_PSYCSTORE_Handle *h,
 179                             const struct GNUNET_HashCode *channel_id,
 180                             const char *state_name,
 181                             GNUNET_PSYCSTORE_StateResultCallback rcb,
 182                             void *rcb_cls);
 183
 184
 185 struct GNUNET_PSYCSTORE_OperationHandle *
 186 GNUNET_PSYCSTORE_state_get_all (struct GNUNET_PSYCSTORE_Handle *h,
 187                                 const struct GNUNET_HashCode *channel_id,
 188                                 GNUNET_PSYCSTORE_StateResultCallback rcb,
 189                                 void *rcb_cls);
 190
 191
 192 void
 193 GNUNET_PSYCSTORE_operation_cancel (struct GNUNET_PSYCSTORE_OperationHandle *oh);
 194
 195
 196
 197
 198 #if 0                           /* keep Emacsens' auto-indent happy */
 199 {
 200 #endif
 201 #ifdef __cplusplus
 202 }
 203 #endif
 204
 205 /* ifndef GNUNET_PSYCSTORE_SERVICE_H */
 206 #endif
 207 /* end of gnunet_psycstore_service.h */