2 This file is part of GNUnet
3 Copyright (C) 2013 Christian Grothoff (and other contributing authors)
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.
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.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @file include/gnunet_psycstore_plugin.h
23 * @brief plugin API for the PSYCstore database backend
24 * @author Gabor X Toth
26 #ifndef GNUNET_PSYCSTORE_PLUGIN_H
27 #define GNUNET_PSYCSTORE_PLUGIN_H
29 #include "gnunet_util_lib.h"
30 #include "gnunet_psycstore_service.h"
35 #if 0 /* keep Emacsens' auto-indent happy */
42 * Struct returned by the initialization function of the plugin.
44 struct GNUNET_PSYCSTORE_PluginFunctions
48 * Closure to pass to all plugin functions.
53 * Store join/leave events for a PSYC channel in order to be able to answer
54 * membership test queries later.
56 * @see GNUNET_PSYCSTORE_membership_store()
58 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
61 (*membership_store) (void *cls,
62 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
63 const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
65 uint64_t announced_at,
66 uint64_t effective_since,
67 uint64_t group_generation);
70 * Test if a member was admitted to the channel at the given message ID.
72 * @see GNUNET_PSYCSTORE_membership_test()
74 * @return #GNUNET_YES if the member was admitted, #GNUNET_NO if not,
75 * #GNUNET_SYSERR if there was en error.
78 (*membership_test) (void *cls,
79 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
80 const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
84 * Store a message fragment sent to a channel.
86 * @see GNUNET_PSYCSTORE_fragment_store()
88 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
91 (*fragment_store) (void *cls,
92 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
93 const struct GNUNET_MULTICAST_MessageHeader *message,
94 uint32_t psycstore_flags);
97 * Set additional flags for a given message.
99 * They are OR'd with any existing flags set.
101 * @param cls Closure.
102 * @param channel_key Public key of the channel.
103 * @param message_id ID of the message.
104 * @param psycstore_flags OR'd GNUNET_PSYCSTORE_MessageFlags.
106 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
109 (*message_add_flags) (void *cls,
110 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
112 uint64_t psycstore_flags);
115 * Retrieve a message fragment range by fragment ID.
117 * @see GNUNET_PSYCSTORE_fragment_get()
119 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
122 (*fragment_get) (void *cls,
123 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
124 uint64_t first_fragment_id,
125 uint64_t last_fragment_id,
126 uint64_t *returned_fragments,
127 GNUNET_PSYCSTORE_FragmentCallback cb,
131 * Retrieve latest message fragments.
133 * @see GNUNET_PSYCSTORE_fragment_get()
135 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
138 (*fragment_get_latest) (void *cls,
139 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
140 uint64_t fragment_limit,
141 uint64_t *returned_fragments,
142 GNUNET_PSYCSTORE_FragmentCallback cb,
146 * Retrieve all fragments of a message ID range.
148 * @see GNUNET_PSYCSTORE_message_get()
150 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
153 (*message_get) (void *cls,
154 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
155 uint64_t first_fragment_id,
156 uint64_t last_fragment_id,
157 uint64_t *returned_fragments,
158 GNUNET_PSYCSTORE_FragmentCallback cb,
162 * Retrieve all fragments of the latest messages.
164 * @see GNUNET_PSYCSTORE_message_get()
166 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
169 (*message_get_latest) (void *cls,
170 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
171 uint64_t fragment_limit,
172 uint64_t *returned_fragments,
173 GNUNET_PSYCSTORE_FragmentCallback cb,
177 * Retrieve a fragment of message specified by its message ID and fragment
180 * @see GNUNET_PSYCSTORE_message_get_fragment()
182 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
185 (*message_get_fragment) (void *cls,
186 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
188 uint64_t fragment_offset,
189 GNUNET_PSYCSTORE_FragmentCallback cb,
193 * Retrieve the max. values of message counters for a channel.
195 * @see GNUNET_PSYCSTORE_counters_get()
197 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
200 (*counters_message_get) (void *cls,
201 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
202 uint64_t *max_fragment_id,
203 uint64_t *max_message_id,
204 uint64_t *max_group_generation);
207 * Retrieve the max. values of state counters for a channel.
209 * @see GNUNET_PSYCSTORE_counters_get()
211 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
214 (*counters_state_get) (void *cls,
215 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
216 uint64_t *max_state_message_id);
220 * Begin modifying current state.
222 * @see GNUNET_PSYCSTORE_state_modify()
224 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
227 (*state_modify_begin) (void *cls,
228 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
229 uint64_t message_id, uint64_t state_delta);
232 * Set the current value of a state variable.
234 * The state modification process is started with state_modify_begin(),
235 * which is followed by one or more calls to this function,
236 * and finished with state_modify_end().
238 * @see GNUNET_PSYCSTORE_state_modify()
240 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
243 (*state_modify_op) (void *cls,
244 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
245 enum GNUNET_ENV_Operator op,
246 const char *name, const void *value, size_t value_size);
250 * End modifying current state.
252 * @see GNUNET_PSYCSTORE_state_modify()
254 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
257 (*state_modify_end) (void *cls,
258 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
259 uint64_t message_id);
263 * Begin synchronizing state.
265 * @see GNUNET_PSYCSTORE_state_sync()
267 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
270 (*state_sync_begin) (void *cls,
271 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
274 * Assign value of a state variable while synchronizing state.
276 * The state synchronization process is started with state_sync_begin(),
277 * which is followed by one or more calls to this function,
278 * and finished using state_sync_end().
280 * @see GNUNET_PSYCSTORE_state_sync()
282 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
285 (*state_sync_assign) (void *cls,
286 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
287 const char *name, const void *value, size_t value_size);
291 * End synchronizing state.
293 * @see GNUNET_PSYCSTORE_state_sync()
295 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
298 (*state_sync_end) (void *cls,
299 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
300 uint64_t max_state_message_id,
301 uint64_t state_hash_message_id);
305 * Reset the state of a channel.
307 * Delete all state variables stored for the given channel.
309 * @see GNUNET_PSYCSTORE_state_reset()
311 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
314 (*state_reset) (void *cls,
315 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
318 * Update signed state values from the current ones.
320 * Sets value_signed = value_current for each variable for the given channel.
323 (*state_update_signed) (void *cls,
324 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
328 * Retrieve a state variable by name (exact match).
330 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
333 (*state_get) (void *cls,
334 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
336 GNUNET_PSYCSTORE_StateCallback cb,
340 * Retrieve all state variables for a channel with the given prefix.
342 * @see GNUNET_PSYCSTORE_state_get_prefix()
344 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
347 (*state_get_prefix) (void *cls,
348 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
350 GNUNET_PSYCSTORE_StateCallback cb,
355 * Retrieve all signed state variables for a channel.
357 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
360 (*state_get_signed) (void *cls,
361 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
362 GNUNET_PSYCSTORE_StateCallback cb,
368 #if 0 /* keep Emacsens' auto-indent happy */
375 /* end of gnunet_psycstore_plugin.h */