2 This file is part of GNUnet
3 Copyright (C) 2013 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your 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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @author Gabor X Toth
23 * Plugin API for the PSYCstore database backend
25 * @defgroup psycstore-plugin PSYC Store plugin API
26 * Plugin API for the PSYC Store database backend
29 #ifndef GNUNET_PSYCSTORE_PLUGIN_H
30 #define GNUNET_PSYCSTORE_PLUGIN_H
32 #include "gnunet_util_lib.h"
33 #include "gnunet_psycstore_service.h"
38 #if 0 /* keep Emacsens' auto-indent happy */
45 * Struct returned by the initialization function of the plugin.
47 struct GNUNET_PSYCSTORE_PluginFunctions
51 * Closure to pass to all plugin functions.
56 * Store join/leave events for a PSYC channel in order to be able to answer
57 * membership test queries later.
59 * @see GNUNET_PSYCSTORE_membership_store()
61 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
64 (*membership_store) (void *cls,
65 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
66 const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
68 uint64_t announced_at,
69 uint64_t effective_since,
70 uint64_t group_generation);
73 * Test if a member was admitted to the channel at the given message ID.
75 * @see GNUNET_PSYCSTORE_membership_test()
77 * @return #GNUNET_YES if the member was admitted, #GNUNET_NO if not,
78 * #GNUNET_SYSERR if there was en error.
81 (*membership_test) (void *cls,
82 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
83 const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
87 * Store a message fragment sent to a channel.
89 * @see GNUNET_PSYCSTORE_fragment_store()
91 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
94 (*fragment_store) (void *cls,
95 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
96 const struct GNUNET_MULTICAST_MessageHeader *message,
97 uint32_t psycstore_flags);
100 * Set additional flags for a given message.
102 * They are OR'd with any existing flags set.
104 * @param cls Closure.
105 * @param channel_key Public key of the channel.
106 * @param message_id ID of the message.
107 * @param psycstore_flags OR'd GNUNET_PSYCSTORE_MessageFlags.
109 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
112 (*message_add_flags) (void *cls,
113 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
115 uint32_t psycstore_flags);
118 * Retrieve a message fragment range by fragment ID.
120 * @see GNUNET_PSYCSTORE_fragment_get()
122 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
125 (*fragment_get) (void *cls,
126 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
127 uint64_t first_fragment_id,
128 uint64_t last_fragment_id,
129 uint64_t *returned_fragments,
130 GNUNET_PSYCSTORE_FragmentCallback cb,
134 * Retrieve latest message fragments.
136 * @see GNUNET_PSYCSTORE_fragment_get()
138 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
141 (*fragment_get_latest) (void *cls,
142 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
143 uint64_t fragment_limit,
144 uint64_t *returned_fragments,
145 GNUNET_PSYCSTORE_FragmentCallback cb,
149 * Retrieve all fragments of a message ID range.
151 * @see GNUNET_PSYCSTORE_message_get()
153 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
156 (*message_get) (void *cls,
157 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
158 uint64_t first_fragment_id,
159 uint64_t last_fragment_id,
160 uint64_t fragment_limit,
161 uint64_t *returned_fragments,
162 GNUNET_PSYCSTORE_FragmentCallback cb,
166 * Retrieve all fragments of the latest messages.
168 * @see GNUNET_PSYCSTORE_message_get()
170 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
173 (*message_get_latest) (void *cls,
174 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
175 uint64_t fragment_limit,
176 uint64_t *returned_fragments,
177 GNUNET_PSYCSTORE_FragmentCallback cb,
181 * Retrieve a fragment of message specified by its message ID and fragment
184 * @see GNUNET_PSYCSTORE_message_get_fragment()
186 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
189 (*message_get_fragment) (void *cls,
190 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
192 uint64_t fragment_offset,
193 GNUNET_PSYCSTORE_FragmentCallback cb,
197 * Retrieve the max. values of message counters for a channel.
199 * @see GNUNET_PSYCSTORE_counters_get()
201 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
204 (*counters_message_get) (void *cls,
205 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
206 uint64_t *max_fragment_id,
207 uint64_t *max_message_id,
208 uint64_t *max_group_generation);
211 * Retrieve the max. values of state counters for a channel.
213 * @see GNUNET_PSYCSTORE_counters_get()
215 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
218 (*counters_state_get) (void *cls,
219 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
220 uint64_t *max_state_message_id);
224 * Begin modifying current state.
226 * @see GNUNET_PSYCSTORE_state_modify()
228 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
231 (*state_modify_begin) (void *cls,
232 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
233 uint64_t message_id, uint64_t state_delta);
236 * Set the current value of a state variable.
238 * The state modification process is started with state_modify_begin(),
239 * which is followed by one or more calls to this function,
240 * and finished with state_modify_end().
242 * @see GNUNET_PSYCSTORE_state_modify()
244 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
247 (*state_modify_op) (void *cls,
248 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
249 enum GNUNET_PSYC_Operator op,
250 const char *name, const void *value, size_t value_size);
254 * End modifying current state.
256 * @see GNUNET_PSYCSTORE_state_modify()
258 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
261 (*state_modify_end) (void *cls,
262 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
263 uint64_t message_id);
267 * Begin synchronizing state.
269 * @see GNUNET_PSYCSTORE_state_sync()
271 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
274 (*state_sync_begin) (void *cls,
275 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
278 * Assign value of a state variable while synchronizing state.
280 * The state synchronization process is started with state_sync_begin(),
281 * which is followed by one or more calls to this function,
282 * and finished using state_sync_end().
284 * @see GNUNET_PSYCSTORE_state_sync()
286 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
289 (*state_sync_assign) (void *cls,
290 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
291 const char *name, const void *value, size_t value_size);
295 * End synchronizing state.
297 * @see GNUNET_PSYCSTORE_state_sync()
299 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
302 (*state_sync_end) (void *cls,
303 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
304 uint64_t max_state_message_id,
305 uint64_t state_hash_message_id);
309 * Reset the state of a channel.
311 * Delete all state variables stored for the given channel.
313 * @see GNUNET_PSYCSTORE_state_reset()
315 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
318 (*state_reset) (void *cls,
319 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
322 * Update signed state values from the current ones.
324 * Sets value_signed = value_current for each variable for the given channel.
327 (*state_update_signed) (void *cls,
328 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
332 * Retrieve a state variable by name (exact match).
334 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
337 (*state_get) (void *cls,
338 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
340 GNUNET_PSYCSTORE_StateCallback cb,
344 * Retrieve all state variables for a channel with the given prefix.
346 * @see GNUNET_PSYCSTORE_state_get_prefix()
348 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
351 (*state_get_prefix) (void *cls,
352 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
354 GNUNET_PSYCSTORE_StateCallback cb,
359 * Retrieve all signed state variables for a channel.
361 * @return #GNUNET_OK on success, else #GNUNET_SYSERR
364 (*state_get_signed) (void *cls,
365 const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
366 GNUNET_PSYCSTORE_StateCallback cb,
372 #if 0 /* keep Emacsens' auto-indent happy */
381 /** @} */ /* end of group */