adding man page for gnunet-auto-share, updating man page for gnunet-publish

[oweals/gnunet.git] / src / fs / fs_tree.h

diff --git a/src/fs/fs_tree.h b/src/fs/fs_tree.h
index 4186a4e21ef2fb1ba1167a05fafb25931b9816e5..5b1c2024f41515f73ab1da5da4890fa10504efbe 100644 (file)
--- a/src/fs/fs_tree.h
+++ b/src/fs/fs_tree.h
@@ -4,7 +4,7 @@
 
      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


@@ -21,7 +21,7 @@
 /**
  * @file fs/fs_tree.h
  * @brief Merkle-tree-ish-CHK file encoding for GNUnet
 /**
  * @file fs/fs_tree.h
  * @brief Merkle-tree-ish-CHK file encoding for GNUnet

- * @see http://gnunet.org/encoding.php3
+ * @see https://gnunet.org/encoding

  * @author Krista Bennett
  * @author Christian Grothoff
  *
  * @author Krista Bennett
  * @author Christian Grothoff
  *


@@ -32,18 +32,47 @@
 #ifndef GNUNET_FS_TREE_H
 #define GNUNET_FS_TREE_H
 
 #ifndef GNUNET_FS_TREE_H
 #define GNUNET_FS_TREE_H
 

-#include "fs.h"
+#include "fs_api.h"

 
 /**
  * Compute the depth of the CHK tree.
  *
  * @param flen file length for which to compute the depth
 
 /**
  * Compute the depth of the CHK tree.
  *
  * @param flen file length for which to compute the depth

- * @return depth of the tree
+ * @return depth of the tree, always > 0.  A depth of 1 means only a DBLOCK.

  */
 unsigned int
 GNUNET_FS_compute_depth (uint64_t flen);
 
 
  */
 unsigned int
 GNUNET_FS_compute_depth (uint64_t flen);
 
 

+/**
+ * Calculate how many bytes of payload a block tree of the given
+ * depth MAY correspond to at most (this function ignores the fact that
+ * some blocks will only be present partially due to the total file
+ * size cutting some blocks off at the end).
+ *
+ * @param depth depth of the block.  depth==0 is a DBLOCK.
+ * @return number of bytes of payload a subtree of this depth may correspond to
+ */
+uint64_t
+GNUNET_FS_tree_compute_tree_size (unsigned int depth);
+
+
+/**
+ * Compute how many bytes of data should be stored in
+ * the specified block.
+ *
+ * @param fsize overall file size, must be > 0.
+ * @param offset offset in the original data corresponding
+ *         to the beginning of the tree induced by the block;
+ *         must be < fsize
+ * @param depth depth of the node in the tree, 0 for DBLOCK
+ * @return number of bytes stored in this node
+ */
+size_t
+GNUNET_FS_tree_calculate_block_size (uint64_t fsize, uint64_t offset,
+                                     unsigned int depth);
+
+

 /**
  * Context for an ECRS-based file encoder that computes
  * the Merkle-ish-CHK tree.
 /**
  * Context for an ECRS-based file encoder that computes
  * the Merkle-ish-CHK tree.


@@ -58,19 +87,21 @@ struct GNUNET_FS_TreeEncoder;
  * or (on error) "GNUNET_FS_tree_encode_finish".
  *
  * @param cls closure
  * or (on error) "GNUNET_FS_tree_encode_finish".
  *
  * @param cls closure

- * @param query the query for the block (key for lookup in the datastore)
+ * @param chk content hash key for the block

  * @param offset offset of the block
  * @param offset offset of the block

+ * @param depth depth of the block, 0 for DBLOCKs

  * @param type type of the block (IBLOCK or DBLOCK)
  * @param block the (encrypted) block
  * @param block_size size of block (in bytes)
  */
  * @param type type of the block (IBLOCK or DBLOCK)
  * @param block the (encrypted) block
  * @param block_size size of block (in bytes)
  */

-typedef void (*GNUNET_FS_TreeBlockProcessor)(void *cls,
-                                            const GNUNET_HashCode *query,
-                                            uint64_t offset,
-                                            unsigned int type,
-                                            const void *block,
-                                            uint16_t block_size);
-                                            
+typedef void (*GNUNET_FS_TreeBlockProcessor) (void *cls,
+                                              const struct ContentHashKey * chk,
+                                              uint64_t offset,
+                                              unsigned int depth,
+                                              enum GNUNET_BLOCK_Type type,
+                                              const void *block,
+                                              uint16_t block_size);
+

 
 /**
  * Function called with information about our
 
 /**
  * Function called with information about our


@@ -80,14 +111,13 @@ typedef void (*GNUNET_FS_TreeBlockProcessor)(void *cls,
  * @param offset where are we in the file
  * @param pt_block plaintext of the currently processed block
  * @param pt_size size of pt_block
  * @param offset where are we in the file
  * @param pt_block plaintext of the currently processed block
  * @param pt_size size of pt_block

- * @param depth depth of the block in the tree
+ * @param depth depth of the block in the tree, 0 for DBLOCKS

  */
  */

-typedef void (*GNUNET_FS_TreeProgressCallback)(void *cls,
-                                              uint64_t offset,
-                                              const void *pt_block,
-                                              size_t pt_size,
-                                              unsigned int depth);
-                                              
+typedef void (*GNUNET_FS_TreeProgressCallback) (void *cls, uint64_t offset,
+                                                const void *pt_block,
+                                                size_t pt_size,
+                                                unsigned int depth);
+

 
 /**
  * Initialize a tree encoder.  This function will call "proc" and
 
 /**
  * Initialize a tree encoder.  This function will call "proc" and


@@ -103,35 +133,34 @@ typedef void (*GNUNET_FS_TreeProgressCallback)(void *cls,
  * @param cls closure for reader, proc, progress and cont
  * @param reader function to call to read plaintext data
  * @param proc function to call on each encrypted block
  * @param cls closure for reader, proc, progress and cont
  * @param reader function to call to read plaintext data
  * @param proc function to call on each encrypted block

- * @param progress function to call with progress information 
+ * @param progress function to call with progress information

  * @param cont function to call when done
  * @return tree encoder context
  */
 struct GNUNET_FS_TreeEncoder *
  * @param cont function to call when done
  * @return tree encoder context
  */
 struct GNUNET_FS_TreeEncoder *

-GNUNET_FS_tree_encoder_create (struct GNUNET_FS_Handle *h,
-                              uint64_t size,
-                              void *cls,
-                              GNUNET_FS_DataReader reader,
-                              GNUNET_FS_TreeBlockProcessor proc,
-                              GNUNET_FS_TreeProgressCallback progress,
-                              GNUNET_SCHEDULER_Task cont);
+GNUNET_FS_tree_encoder_create (struct GNUNET_FS_Handle *h, uint64_t size,
+                               void *cls, GNUNET_FS_DataReader reader,
+                               GNUNET_FS_TreeBlockProcessor proc,
+                               GNUNET_FS_TreeProgressCallback progress,
+                               GNUNET_SCHEDULER_Task cont);

 
 
 /**
 
 
 /**

- * Encrypt the next block of the file (and 
- * call proc and progress accordingly; or 
+ * Encrypt the next block of the file (and
+ * call proc and progress accordingly; or

  * of course "cont" if we have already completed
  * encoding of the entire file).
  *
  * @param te tree encoder to use
  */
  * of course "cont" if we have already completed
  * encoding of the entire file).
  *
  * @param te tree encoder to use
  */

-void GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder * te);
+void
+GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder *te);

 
 
 /**
  * Clean up a tree encoder and return information
  * about the resulting URI or an error message.
 
 
 /**
  * Clean up a tree encoder and return information
  * about the resulting URI or an error message.

- * 
+ *

  * @param te the tree encoder to clean up
  * @param uri set to the resulting URI (if encoding finished)
  * @param emsg set to an error message (if an error occured
  * @param te the tree encoder to clean up
  * @param uri set to the resulting URI (if encoding finished)
  * @param emsg set to an error message (if an error occured


@@ -139,9 +168,9 @@ void GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder * te);
  *        prior to completion and prior to an internal error,
  *        both "*uri" and "*emsg" will be set to NULL).
  */
  *        prior to completion and prior to an internal error,
  *        both "*uri" and "*emsg" will be set to NULL).
  */

-void GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder * te,
-                                   struct GNUNET_FS_Uri **uri,
-                                   char **emsg);
+void
+GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder *te,
+                               struct GNUNET_FS_Uri **uri, char **emsg);

 
 
 #if 0
 
 
 #if 0


@@ -150,27 +179,27 @@ void GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder * te,
 /**
  * Get data that would be needed to resume
  * the encoding later.
 /**
  * Get data that would be needed to resume
  * the encoding later.

- * 
+ *

  * @param te encoding to resume
  * @param data set to the resume data
  * @param size set to the size of the resume data
  */
  * @param te encoding to resume
  * @param data set to the resume data
  * @param size set to the size of the resume data
  */

-void GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder * te,
-                                            void **data,
-                                            size_t *size);
+void
+GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder *te,
+                                        void **data, size_t * size);

 
 
 /**
  * Reset tree encoder to point previously
  * obtained for resuming.
 
 
 /**
  * Reset tree encoder to point previously
  * obtained for resuming.

- * 
+ *

  * @param te encoding to resume
  * @param data the resume data
  * @param size the size of the resume data
  */
  * @param te encoding to resume
  * @param data the resume data
  * @param size the size of the resume data
  */

-void GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder * te,
-                                   const void *data,
-                                   size_t size);
+void
+GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder *te,
+                               const void *data, size_t size);

 #endif
 
 #endif
 #endif
 
 #endif