/*
This file is part of GNUnet
- (C) 2012, 2013 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2013 GNUnet e.V.
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
You should have received a copy of the GNU General Public License
along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_psycstore_plugin.h
- * @brief plugin API for the PSYCstore database backend
* @author Gabor X Toth
+ *
+ * @file
+ * Plugin API for the PSYCstore database backend
+ *
+ * @defgroup psycstore-plugin PSYC Store plugin API
+ * Plugin API for the PSYC Store database backend
+ * @{
*/
#ifndef GNUNET_PSYCSTORE_PLUGIN_H
#define GNUNET_PSYCSTORE_PLUGIN_H
-#include "gnunet_common.h"
#include "gnunet_util_lib.h"
#include "gnunet_psycstore_service.h"
/**
- * @brief struct returned by the initialization function of the plugin
+ * Struct returned by the initialization function of the plugin.
*/
struct GNUNET_PSYCSTORE_PluginFunctions
{
*/
void *cls;
- /**
+ /**
* Store join/leave events for a PSYC channel in order to be able to answer
* membership test queries later.
*
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
- (*membership_store) (void *cls,
- const struct GNUNET_HashCode *channel_key,
- const struct GNUNET_HashCode *slave_key,
+ (*membership_store) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
int did_join,
uint64_t announced_at,
uint64_t effective_since,
uint64_t group_generation);
- /**
+ /**
* Test if a member was admitted to the channel at the given message ID.
*
* @see GNUNET_PSYCSTORE_membership_test()
- *
+ *
* @return #GNUNET_YES if the member was admitted, #GNUNET_NO if not,
* #GNUNET_SYSERR if there was en error.
*/
int
(*membership_test) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- const struct GNUNET_CRYPTO_EccPublicKey *slave_key,
- uint64_t message_id,
- uint64_t group_generation);
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
+ uint64_t message_id);
- /**
+ /**
* Store a message fragment sent to a channel.
*
* @see GNUNET_PSYCSTORE_fragment_store()
- *
+ *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
(*fragment_store) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- const struct GNUNET_MULTICAST_MessageHeader *message);
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ const struct GNUNET_MULTICAST_MessageHeader *message,
+ uint32_t psycstore_flags);
- /**
+ /**
* Set additional flags for a given message.
*
+ * They are OR'd with any existing flags set.
+ *
+ * @param cls Closure.
+ * @param channel_key Public key of the channel.
* @param message_id ID of the message.
- * @param flags Flags to add.
- *
+ * @param psycstore_flags OR'd GNUNET_PSYCSTORE_MessageFlags.
+ *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
- (*fragment_add_flags) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- uint64_t message_id,
- uint64_t multicast_flags,
- uint64_t psyc_flags);
+ (*message_add_flags) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t message_id,
+ uint32_t psycstore_flags);
- /**
- * Retrieve a message fragment by fragment ID.
+ /**
+ * Retrieve a message fragment range by fragment ID.
*
* @see GNUNET_PSYCSTORE_fragment_get()
- *
+ *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
(*fragment_get) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- uint64_t fragment_id,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t first_fragment_id,
+ uint64_t last_fragment_id,
+ uint64_t *returned_fragments,
GNUNET_PSYCSTORE_FragmentCallback cb,
void *cb_cls);
- /**
- * Retrieve all fragments of a message.
+ /**
+ * Retrieve latest message fragments.
+ *
+ * @see GNUNET_PSYCSTORE_fragment_get()
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*fragment_get_latest) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t fragment_limit,
+ uint64_t *returned_fragments,
+ GNUNET_PSYCSTORE_FragmentCallback cb,
+ void *cb_cls);
+
+ /**
+ * Retrieve all fragments of a message ID range.
*
* @see GNUNET_PSYCSTORE_message_get()
- *
+ *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
(*message_get) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- uint64_t message_id,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t first_fragment_id,
+ uint64_t last_fragment_id,
+ uint64_t fragment_limit,
+ uint64_t *returned_fragments,
GNUNET_PSYCSTORE_FragmentCallback cb,
void *cb_cls);
- /**
+ /**
+ * Retrieve all fragments of the latest messages.
+ *
+ * @see GNUNET_PSYCSTORE_message_get()
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*message_get_latest) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t fragment_limit,
+ uint64_t *returned_fragments,
+ GNUNET_PSYCSTORE_FragmentCallback cb,
+ void *cb_cls);
+
+ /**
* Retrieve a fragment of message specified by its message ID and fragment
* offset.
*
* @see GNUNET_PSYCSTORE_message_get_fragment()
- *
+ *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
(*message_get_fragment) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
uint64_t message_id,
uint64_t fragment_offset,
GNUNET_PSYCSTORE_FragmentCallback cb,
void *cb_cls);
- /**
- * Retrieve latest values of counters for a channel master.
+ /**
+ * Retrieve the max. values of message counters for a channel.
+ *
+ * @see GNUNET_PSYCSTORE_counters_get()
*
- * @see GNUNET_PSYCSTORE_counters_get_master()
- *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
- (*counters_get_master) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- uint64_t *fragment_id,
- uint64_t *message_id,
- uint64_t *group_generation);
+ (*counters_message_get) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t *max_fragment_id,
+ uint64_t *max_message_id,
+ uint64_t *max_group_generation);
- /**
- * Retrieve latest values of counters for a channel slave.
+ /**
+ * Retrieve the max. values of state counters for a channel.
+ *
+ * @see GNUNET_PSYCSTORE_counters_get()
*
- * @see GNUNET_PSYCSTORE_counters_get_slave()
- *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
- (*counters_get_slave) (void *cls,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- uint64_t *max_state_msg_id);
+ (*counters_state_get) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t *max_state_message_id);
- /**
- * Set a state variable to the given value.
+
+ /**
+ * Begin modifying current state.
*
* @see GNUNET_PSYCSTORE_state_modify()
- *
+ *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
- (*state_set) (struct GNUNET_PSYCSTORE_Handle *h,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- const char *name,
- size_t value_size,
- const void *value);
+ (*state_modify_begin) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t message_id, uint64_t state_delta);
+
+ /**
+ * Set the current value of a state variable.
+ *
+ * The state modification process is started with state_modify_begin(),
+ * which is followed by one or more calls to this function,
+ * and finished with state_modify_end().
+ *
+ * @see GNUNET_PSYCSTORE_state_modify()
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*state_modify_op) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ enum GNUNET_PSYC_Operator op,
+ const char *name, const void *value, size_t value_size);
+
+
+ /**
+ * End modifying current state.
+ *
+ * @see GNUNET_PSYCSTORE_state_modify()
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*state_modify_end) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t message_id);
+
+
+ /**
+ * Begin synchronizing state.
+ *
+ * @see GNUNET_PSYCSTORE_state_sync()
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*state_sync_begin) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
- /**
- * Retrieve a state variable by name.
+ /**
+ * Assign value of a state variable while synchronizing state.
+ *
+ * The state synchronization process is started with state_sync_begin(),
+ * which is followed by one or more calls to this function,
+ * and finished using state_sync_end().
+ *
+ * @see GNUNET_PSYCSTORE_state_sync()
*
- * @param name Name of the variable to retrieve.
- * @param[out] value_size Size of value.
- * @param[out] value Returned value.
- *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
- (*state_get) (struct GNUNET_PSYCSTORE_Handle *h,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
+ (*state_sync_assign) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ const char *name, const void *value, size_t value_size);
+
+
+ /**
+ * End synchronizing state.
+ *
+ * @see GNUNET_PSYCSTORE_state_sync()
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*state_sync_end) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ uint64_t max_state_message_id,
+ uint64_t state_hash_message_id);
+
+
+ /**
+ * Reset the state of a channel.
+ *
+ * Delete all state variables stored for the given channel.
+ *
+ * @see GNUNET_PSYCSTORE_state_reset()
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*state_reset) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
+
+ /**
+ * Update signed state values from the current ones.
+ *
+ * Sets value_signed = value_current for each variable for the given channel.
+ */
+ int
+ (*state_update_signed) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key);
+
+
+ /**
+ * Retrieve a state variable by name (exact match).
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*state_get) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
const char *name,
GNUNET_PSYCSTORE_StateCallback cb,
void *cb_cls);
- /**
+ /**
* Retrieve all state variables for a channel with the given prefix.
*
- * @see GNUNET_PSYCSTORE_state_get_all()
- *
+ * @see GNUNET_PSYCSTORE_state_get_prefix()
+ *
* @return #GNUNET_OK on success, else #GNUNET_SYSERR
*/
int
- (*state_get_all) (struct GNUNET_PSYCSTORE_Handle *h,
- const struct GNUNET_CRYPTO_EccPublicKey *channel_key,
- const char *name,
- GNUNET_PSYCSTORE_StateCallback cb,
- void *cb_cls);
+ (*state_get_prefix) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ const char *name,
+ GNUNET_PSYCSTORE_StateCallback cb,
+ void *cb_cls);
+
+
+ /**
+ * Retrieve all signed state variables for a channel.
+ *
+ * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+ */
+ int
+ (*state_get_signed) (void *cls,
+ const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+ GNUNET_PSYCSTORE_StateCallback cb,
+ void *cb_cls);
};
}
#endif
-/* end of gnunet_psycstore_plugin.h */
#endif
+
+/** @} */ /* end of group */