X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_datastore_plugin.h;h=36a3fbec2c9893e445f5018da26221915c59988f;hb=ca391c48238c36462ca11be9299cc7c9a09e6bbe;hp=fb1dff51d217b167b4fa36661a72f18b683e1d30;hpb=cddbdf5b928c68ab71b40c950b9f01ea68a9fbdb;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_datastore_plugin.h b/src/include/gnunet_datastore_plugin.h index fb1dff51d..36a3fbec2 100644 --- a/src/include/gnunet_datastore_plugin.h +++ b/src/include/gnunet_datastore_plugin.h @@ -1,10 +1,10 @@ /* This file is part of GNUnet - (C) 2009, 2011 Christian Grothoff (and other contributing authors) + Copyright (C) 2009, 2011 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 - by the Free Software Foundation; either version 2, or (at your + by the Free Software Foundation; either version 3, or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but @@ -14,14 +14,19 @@ 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_datastore_plugin.h - * @brief API for the database backend plugins. * @author Christian Grothoff + * + * @file + * API for the database backend plugins. + * + * @defgroup datastore-plugin Data Store service plugin API + * API for the database backend plugins. + * @{ */ #ifndef PLUGIN_DATASTORE_H #define PLUGIN_DATASTORE_H @@ -48,7 +53,9 @@ * @param delta change in disk utilization, * 0 for "reset to empty" */ -typedef void (*DiskUtilizationChange) (void *cls, int delta); +typedef void +(*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls, + int delta); /** @@ -66,7 +73,7 @@ struct GNUNET_DATASTORE_PluginEnvironment /** * Function to call on disk utilization change. */ - DiskUtilizationChange duc; + GNUNET_DATASTORE_DiskUtilizationChange duc; /** * Closure. @@ -86,27 +93,57 @@ struct GNUNET_DATASTORE_PluginEnvironment * @param type type of the content * @param priority priority of the content * @param anonymity anonymity-level for the content + * @param replication replication-level for the content * @param expiration expiration time for the content * @param uid unique identifier for the datum - * - * @return GNUNET_OK to keep the item - * GNUNET_NO to delete the item + * @return #GNUNET_OK to keep the item + * #GNUNET_NO to delete the item */ -typedef int (*PluginDatumProcessor) (void *cls, const GNUNET_HashCode * key, - uint32_t size, const void *data, - enum GNUNET_BLOCK_Type type, - uint32_t priority, uint32_t anonymity, - struct GNUNET_TIME_Absolute expiration, - uint64_t uid); +typedef int +(*PluginDatumProcessor) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + const void *data, + enum GNUNET_BLOCK_Type type, + uint32_t priority, + uint32_t anonymity, + uint32_t replication, + struct GNUNET_TIME_Absolute expiration, + uint64_t uid); + /** * Get an estimate of how much space the database is * currently using. * + * NB: estimate is an output parameter because emscripten cannot handle + * returning 64-bit integers from dynamically loaded modules. + * * @param cls closure + * @param estimate location to store estimate * @return number of bytes used on disk */ -typedef unsigned long long (*PluginEstimateSize) (void *cls); +typedef void +(*PluginEstimateSize) (void *cls, + unsigned long long *estimate); + + +/** + * Put continuation. + * + * @param cls closure + * @param key key for the item stored + * @param size size of the item stored + * @param status #GNUNET_OK if inserted, #GNUNET_NO if updated, + * or #GNUNET_SYSERROR if error + * @param msg error message on error + */ +typedef void +(*PluginPutCont) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + int status, + const char *msg); /** @@ -116,106 +153,151 @@ typedef unsigned long long (*PluginEstimateSize) (void *cls); * * @param cls closure * @param key key for the item - * @param size number of bytes in data + * @param absent true if the key was not found in the bloom filter + * @param size number of bytes in @a data * @param data content stored * @param type type of the content * @param priority priority of the content * @param anonymity anonymity-level for the content * @param replication replication-level for the content * @param expiration expiration time for the content - * @param msg set to an error message (on failure) - * @return GNUNET_OK on success, - * GNUNET_SYSERR on failure + * @param cont continuation called with success or failure status + * @param cont_cls continuation closure for @a cont */ -typedef int (*PluginPut) (void *cls, const GNUNET_HashCode * key, uint32_t size, - const void *data, enum GNUNET_BLOCK_Type type, - uint32_t priority, uint32_t anonymity, - uint32_t replication, - struct GNUNET_TIME_Absolute expiration, char **msg); +typedef void +(*PluginPut) (void *cls, + const struct GNUNET_HashCode *key, + bool absent, + uint32_t size, + const void *data, + enum GNUNET_BLOCK_Type type, + uint32_t priority, + uint32_t anonymity, + uint32_t replication, + struct GNUNET_TIME_Absolute expiration, + PluginPutCont cont, + void *cont_cls); + + +/** + * An processor over a set of keys stored in the datastore. + * + * @param cls closure + * @param key key in the data store, if NULL iteration is finished + * @param count how many values are stored under this key in the datastore + */ +typedef void +(*PluginKeyProcessor) (void *cls, + const struct GNUNET_HashCode *key, + unsigned int count); + + +/** + * Get all of the keys in the datastore. + * + * @param cls closure + * @param proc function to call on each key + * @param proc_cls closure for @a proc + */ +typedef void +(*PluginGetKeys) (void *cls, + PluginKeyProcessor proc, + void *proc_cls); /** * Get one of the results for a particular key in the datastore. * * @param cls closure - * @param offset offset of the result (modulo num-results); - * specific ordering does not matter for the offset - * @param key key to match, never NULL - * @param vhash hash of the value, maybe NULL (to - * match all values that have the right key). - * Note that for DBlocks there is no difference - * betwen key and vhash, but for other blocks - * there may be! + * @param next_uid return the result with lowest uid >= next_uid + * @param random if true, return a random result instead of using next_uid + * @param key maybe NULL (to match all entries) * @param type entries of which type are relevant? * Use 0 for any type. * @param proc function to call on the matching value; - * proc should be called with NULL if there is no result - * @param proc_cls closure for proc + * will be called with NULL if nothing matches + * @param proc_cls closure for @a proc */ -typedef void (*PluginGetKey) (void *cls, uint64_t offset, - const GNUNET_HashCode * key, - const GNUNET_HashCode * vhash, - enum GNUNET_BLOCK_Type type, - PluginDatumProcessor proc, void *proc_cls); - +typedef void +(*PluginGetKey) (void *cls, + uint64_t next_uid, + bool random, + const struct GNUNET_HashCode *key, + enum GNUNET_BLOCK_Type type, + PluginDatumProcessor proc, + void *proc_cls); /** - * Get a random item (additional constraints may apply depending on - * the specific implementation). Calls 'proc' with all values ZERO or - * NULL if no item applies, otherwise 'proc' is called once and only - * once with an item. + * Remove continuation. * * @param cls closure - * @param proc function to call the value (once only). - * @param proc_cls closure for proc + * @param key key for the content removed + * @param size number of bytes removed + * @param status #GNUNET_OK if removed, #GNUNET_NO if not found, + * or #GNUNET_SYSERROR if error + * @param msg error message on error */ -typedef void (*PluginGetRandom) (void *cls, PluginDatumProcessor proc, - void *proc_cls); +typedef void +(*PluginRemoveCont) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + int status, + const char *msg); /** - * Update the priority for a particular key in the datastore. If - * the expiration time in value is different than the time found in - * the datastore, the higher value should be kept. For the - * anonymity level, the lower value is to be used. The specified - * priority should be added to the existing priority, ignoring the - * priority in value. + * Remove a particular key in the datastore. * - * Note that it is possible for multiple values to match this put. - * In that case, all of the respective values are updated. + * @param cls closure + * @param key key for the content + * @param size number of bytes in data + * @param data content stored + * @param cont continuation called with success or failure status + * @param cont_cls continuation closure for @a cont + */ +typedef void +(*PluginRemoveKey) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + const void *data, + PluginRemoveCont cont, + void *cont_cls); + + +/** + * Get a random item (additional constraints may apply depending on + * the specific implementation). Calls @a proc with all values ZERO or + * NULL if no item applies, otherwise @a proc is called once and only + * once with an item. * * @param cls closure - * @param uid unique identifier of the datum - * @param delta by how much should the priority - * change? If priority + delta < 0 the - * priority should be set to 0 (never go - * negative). - * @param expire new expiration time should be the - * MAX of any existing expiration time and - * this value - * @param msg set to an error message (on error) - * @return GNUNET_OK on success + * @param proc function to call the value (once only). + * @param proc_cls closure for @a proc */ -typedef int (*PluginUpdate) (void *cls, uint64_t uid, int delta, - struct GNUNET_TIME_Absolute expire, char **msg); +typedef void +(*PluginGetRandom) (void *cls, + PluginDatumProcessor proc, + void *proc_cls); /** - * Select a single item from the datastore at the specified offset - * (among those applicable). + * Select a single item from the datastore (among those applicable). * * @param cls closure - * @param offset offset of the result (modulo num-results); - * specific ordering does not matter for the offset + * @param next_uid return the result with lowest uid >= next_uid * @param type entries of which type should be considered? * Must not be zero (ANY). - * @param proc function to call on the matching value - * @param proc_cls closure for proc + * @param proc function to call on the matching value; + * will be called with NULL if no value matches + * @param proc_cls closure for @a proc */ -typedef void (*PluginGetType) (void *cls, uint64_t offset, - enum GNUNET_BLOCK_Type type, - PluginDatumProcessor proc, void *proc_cls); +typedef void +(*PluginGetType) (void *cls, + uint64_t next_uid, + enum GNUNET_BLOCK_Type type, + PluginDatumProcessor proc, + void *proc_cls); /** @@ -223,8 +305,8 @@ typedef void (*PluginGetType) (void *cls, uint64_t offset, * * @param cls closure */ -typedef void (*PluginDrop) (void *cls); - +typedef void +(*PluginDrop) (void *cls); /** @@ -251,16 +333,6 @@ struct GNUNET_DATASTORE_PluginFunctions */ PluginPut put; - /** - * Update the priority for a particular key in the datastore. If - * the expiration time in value is different than the time found in - * the datastore, the higher value should be kept. For the - * anonymity level, the lower value is to be used. The specified - * priority should be added to the existing priority, ignoring the - * priority in value. - */ - PluginUpdate update; - /** * Get a particular datum matching a given hash from the datastore. */ @@ -268,9 +340,6 @@ struct GNUNET_DATASTORE_PluginFunctions /** * Get datum (of the specified type) with anonymity level zero. - * This function is allowed to ignore the 'offset' argument - * and instead return a random result (with zero anonymity of - * the correct type) if implementing an offset is expensive. */ PluginGetType get_zero_anonymity; @@ -296,7 +365,17 @@ struct GNUNET_DATASTORE_PluginFunctions */ PluginDrop drop; -}; + /** + * Iterate over all keys in the database. + */ + PluginGetKeys get_keys; + /** + * Function to remove an item from the database. + */ + PluginRemoveKey remove_key; +}; #endif + +/** @} */ /* end of group */