Merge branch 'master' of gnunet.org:gnunet

[oweals/gnunet.git] / src / include / gnunet_datacache_plugin.h

diff --git a/src/include/gnunet_datacache_plugin.h b/src/include/gnunet_datacache_plugin.h
index cc5209ab42b14b2d6e14a993586daff1fe138b6f..166c7bc3b63cf7bcca1a3fec914bc1d890f9151b 100644 (file)
--- a/src/include/gnunet_datacache_plugin.h
+++ b/src/include/gnunet_datacache_plugin.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet
-     (C) 2006, 2009 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2006, 2009, 2015 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
@@ -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_datacache_plugin.h
- * @brief API for database backends for the datacache
  * @author Christian Grothoff
+ *
+ * @file
+ * API for database backends for the datacache
+ *
+ * @defgroup datacache-plugin  Data Cache plugin API
+ * API for database backends for the datacache
+ * @{
  */
 #ifndef PLUGIN_DATACACHE_H
 #define PLUGIN_DATACACHE_H
@@ -45,9 +50,10 @@ extern "C"
  * @param key key of the content that was deleted
  * @param size number of bytes that were made available
  */
-typedef void (*GNUNET_DATACACHE_DeleteNotifyCallback) (void *cls,
-                                                       const struct GNUNET_HashCode *
-                                                       key, size_t size);
+typedef void
+(*GNUNET_DATACACHE_DeleteNotifyCallback) (void *cls,
+                                          const struct GNUNET_HashCode *key,
+                                          size_t size);
 
 
 /**
@@ -58,7 +64,6 @@ typedef void (*GNUNET_DATACACHE_DeleteNotifyCallback) (void *cls,
 struct GNUNET_DATACACHE_PluginEnvironment
 {
 
-
   /**
    * Configuration to use.
    */
@@ -103,46 +108,81 @@ struct GNUNET_DATACACHE_PluginFunctions
    * Store an item in the datastore.
    *
    * @param cls closure (internal context for the plugin)
-   * @param size number of bytes in data
+   * @param key key to store the value under
+   * @param size number of bytes in @a data
    * @param data data to store
    * @param type type of the value
    * @param discard_time when to discard the value in any case
-   * @param path_info_len number of entries in 'path_info'
+   * @param path_info_len number of entries in @a path_info
    * @param path_info a path through the network
    * @return 0 if duplicate, -1 on error, number of bytes used otherwise
    */
-  ssize_t (*put) (void *cls, const struct GNUNET_HashCode * key, size_t size,
-                 const char *data, enum GNUNET_BLOCK_Type type,
+  ssize_t (*put) (void *cls,
+                  const struct GNUNET_HashCode *key,
+                  size_t size,
+                 const char *data,
+                  enum GNUNET_BLOCK_Type type,
                  struct GNUNET_TIME_Absolute discard_time,
                  unsigned int path_info_len,
                  const struct GNUNET_PeerIdentity *path_info);
 
-
   /**
    * Iterate over the results for a particular key
    * in the datastore.
    *
    * @param cls closure (internal context for the plugin)
-   * @param key
+   * @param key key to look for
    * @param type entries of which type are relevant?
    * @param iter maybe NULL (to just count)
-   * @param iter_cls closure for iter
+   * @param iter_cls closure for @a iter
    * @return the number of results found
    */
-  unsigned int (*get) (void *cls, const struct GNUNET_HashCode * key,
+  unsigned int (*get) (void *cls,
+                       const struct GNUNET_HashCode *key,
                        enum GNUNET_BLOCK_Type type,
-                       GNUNET_DATACACHE_Iterator iter, void *iter_cls);
-
+                       GNUNET_DATACACHE_Iterator iter,
+                       void *iter_cls);
 
   /**
    * Delete the entry with the lowest expiration value
    * from the datacache right now.
    *
    * @param cls closure (internal context for the plugin)
-   * @return GNUNET_OK on success, GNUNET_SYSERR on error
+   * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
    */
   int (*del) (void *cls);
 
+  /**
+   * Return a random value from the datastore.
+   *
+   * @param cls closure (internal context for the plugin)
+   * @param iter maybe NULL (to just count)
+   * @param iter_cls closure for @a iter
+   * @return the number of results found (zero or one)
+   */
+  unsigned int (*get_random) (void *cls,
+                              GNUNET_DATACACHE_Iterator iter,
+                              void *iter_cls);
+
+
+  /**
+   * Iterate over the results that are "close" to a particular key in
+   * the datacache.  "close" is defined as numerically larger than @a
+   * key (when interpreted as a circular address space), with small
+   * distance.
+   *
+   * @param cls closure (internal context for the plugin)
+   * @param key area of the keyspace to look into
+   * @param num_results number of results that should be returned to @a iter
+   * @param iter maybe NULL (to just count)
+   * @param iter_cls closure for @a iter
+   * @return the number of results found
+   */
+  unsigned int (*get_closest) (void *cls,
+                               const struct GNUNET_HashCode *key,
+                               unsigned int num_results,
+                               GNUNET_DATACACHE_Iterator iter,
+                               void *iter_cls);
 
 };
 
@@ -154,5 +194,6 @@ struct GNUNET_DATACACHE_PluginFunctions
 }
 #endif
 
-/* end of gnunet_datacache_plugin.h */
 #endif
+
+/** @} */  /* end of group */