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 c7ce0bef1596004f8482e937b6af9688bc216501..166c7bc3b63cf7bcca1a3fec914bc1d890f9151b 100644 (file)
--- a/src/include/gnunet_datacache_plugin.h
+++ b/src/include/gnunet_datacache_plugin.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet
 /*
      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
 
      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
      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
 
      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
  * @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
  */
 #ifndef PLUGIN_DATACACHE_H
 #define PLUGIN_DATACACHE_H


@@ -40,14 +45,15 @@ extern "C"
 /**
  * Function called by plugins to notify the datacache
  * about content deletions.
 /**
  * Function called by plugins to notify the datacache
  * about content deletions.

- * 
+ *

  * @param cls closure
  * @param key key of the content that was deleted
  * @param size number of bytes that were made available
  */
  * @param cls closure
  * @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 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
 {
 
 struct GNUNET_DATACACHE_PluginEnvironment
 {
 

-

   /**
    * Configuration to use.
    */
   /**
    * 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)
    * 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 data data to store
    * @param type type of the value
    * @param discard_time when to discard the value in any case

-   * @return 0 on error, number of bytes used otherwise
+   * @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

    */
    */

-       size_t (*put) (void *cls,
-                      const GNUNET_HashCode * key,
-                      size_t size,
-                      const char *data,
-                      enum GNUNET_BLOCK_Type type,
-                      struct GNUNET_TIME_Absolute discard_time);
-
+  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)
 
   /**
    * 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 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,
    * @return the number of results found
    */
   unsigned int (*get) (void *cls,

-                       const GNUNET_HashCode * key,
+                       const struct GNUNET_HashCode *key,

                        enum GNUNET_BLOCK_Type type,
                        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.
 
   /**
    * Delete the entry with the lowest expiration value
    * from the datacache right now.

-   * 
+   *

    * @param cls closure (internal context for the plugin)
    * @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);
 
    */
   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
 
 }
 #endif
 

-/* end of gnunet_datacache_plugin.h */

 #endif
 #endif

+
+/** @} */  /* end of group */