src/fs/fs_tree.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file fs/fs_tree.h
  23  * @brief Merkle-tree-ish-CHK file encoding for GNUnet
  24  * @see https://gnunet.org/encoding
  25  * @author Krista Bennett
  26  * @author Christian Grothoff
  27  *
  28  * TODO:
  29  * - decide if this API should be made public (gnunet_fs_service.h)
  30  *   or remain "internal" (but with exported symbols?)
  31  */
  32 #ifndef GNUNET_FS_TREE_H
  33 #define GNUNET_FS_TREE_H
  34
  35 #include "fs.h"
  36
  37 /**
  38  * Compute the depth of the CHK tree.
  39  *
  40  * @param flen file length for which to compute the depth
  41  * @return depth of the tree, always > 0.  A depth of 1 means only a DBLOCK.
  42  */
  43 unsigned int GNUNET_FS_compute_depth (uint64_t flen);
  44
  45
  46 /**
  47  * Calculate how many bytes of payload a block tree of the given
  48  * depth MAY correspond to at most (this function ignores the fact that
  49  * some blocks will only be present partially due to the total file
  50  * size cutting some blocks off at the end).
  51  *
  52  * @param depth depth of the block.  depth==0 is a DBLOCK.
  53  * @return number of bytes of payload a subtree of this depth may correspond to
  54  */
  55 uint64_t GNUNET_FS_tree_compute_tree_size (unsigned int depth);
  56
  57
  58 /**
  59  * Compute how many bytes of data should be stored in
  60  * the specified block.
  61  *
  62  * @param fsize overall file size, must be > 0.
  63  * @param offset offset in the original data corresponding
  64  *         to the beginning of the tree induced by the block;
  65  *         must be < fsize
  66  * @param depth depth of the node in the tree, 0 for DBLOCK
  67  * @return number of bytes stored in this node
  68  */
  69 size_t GNUNET_FS_tree_calculate_block_size (uint64_t fsize, uint64_t offset,
  70                                             unsigned int depth);
  71
  72
  73 /**
  74  * Context for an ECRS-based file encoder that computes
  75  * the Merkle-ish-CHK tree.
  76  */
  77 struct GNUNET_FS_TreeEncoder;
  78
  79
  80 /**
  81  * Function called asking for the current (encoded)
  82  * block to be processed.  After processing the
  83  * client should either call "GNUNET_FS_tree_encode_next"
  84  * or (on error) "GNUNET_FS_tree_encode_finish".
  85  *
  86  * @param cls closure
  87  * @param chk content hash key for the block
  88  * @param offset offset of the block
  89  * @param depth depth of the block, 0 for DBLOCKs
  90  * @param type type of the block (IBLOCK or DBLOCK)
  91  * @param block the (encrypted) block
  92  * @param block_size size of block (in bytes)
  93  */
  94 typedef void (*GNUNET_FS_TreeBlockProcessor) (void *cls,
  95                                               const struct ContentHashKey * chk,
  96                                               uint64_t offset,
  97                                               unsigned int depth,
  98                                               enum GNUNET_BLOCK_Type type,
  99                                               const void *block,
 100                                               uint16_t block_size);
 101
 102
 103 /**
 104  * Function called with information about our
 105  * progress in computing the tree encoding.
 106  *
 107  * @param cls closure
 108  * @param offset where are we in the file
 109  * @param pt_block plaintext of the currently processed block
 110  * @param pt_size size of pt_block
 111  * @param depth depth of the block in the tree, 0 for DBLOCKS
 112  */
 113 typedef void (*GNUNET_FS_TreeProgressCallback) (void *cls, uint64_t offset,
 114                                                 const void *pt_block,
 115                                                 size_t pt_size,
 116                                                 unsigned int depth);
 117
 118
 119 /**
 120  * Initialize a tree encoder.  This function will call "proc" and
 121  * "progress" on each block in the tree.  Once all blocks have been
 122  * processed, "cont" will be scheduled.  The "reader" will be called
 123  * to obtain the (plaintext) blocks for the file.  Note that this
 124  * function will actually never call "proc"; the "proc" function must
 125  * be triggered by calling "GNUNET_FS_tree_encoder_next" to trigger
 126  * encryption (and calling of "proc") for each block.
 127  *
 128  * @param h the global FS context
 129  * @param size overall size of the file to encode
 130  * @param cls closure for reader, proc, progress and cont
 131  * @param reader function to call to read plaintext data
 132  * @param proc function to call on each encrypted block
 133  * @param progress function to call with progress information
 134  * @param cont function to call when done
 135  * @return tree encoder context
 136  */
 137 struct GNUNET_FS_TreeEncoder *GNUNET_FS_tree_encoder_create (struct
 138                                                              GNUNET_FS_Handle
 139                                                              *h, uint64_t size,
 140                                                              void *cls,
 141                                                              GNUNET_FS_DataReader
 142                                                              reader,
 143                                                              GNUNET_FS_TreeBlockProcessor
 144                                                              proc,
 145                                                              GNUNET_FS_TreeProgressCallback
 146                                                              progress,
 147                                                              GNUNET_SCHEDULER_Task
 148                                                              cont);
 149
 150
 151 /**
 152  * Encrypt the next block of the file (and
 153  * call proc and progress accordingly; or
 154  * of course "cont" if we have already completed
 155  * encoding of the entire file).
 156  *
 157  * @param te tree encoder to use
 158  */
 159 void GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder *te);
 160
 161
 162 /**
 163  * Clean up a tree encoder and return information
 164  * about the resulting URI or an error message.
 165  *
 166  * @param te the tree encoder to clean up
 167  * @param uri set to the resulting URI (if encoding finished)
 168  * @param emsg set to an error message (if an error occured
 169  *        within the tree encoder; if this function is called
 170  *        prior to completion and prior to an internal error,
 171  *        both "*uri" and "*emsg" will be set to NULL).
 172  */
 173 void GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder *te,
 174                                     struct GNUNET_FS_Uri **uri, char **emsg);
 175
 176
 177 #if 0
 178 /* the functions below will be needed for persistence
 179    but are not yet implemented -- FIXME... */
 180 /**
 181  * Get data that would be needed to resume
 182  * the encoding later.
 183  *
 184  * @param te encoding to resume
 185  * @param data set to the resume data
 186  * @param size set to the size of the resume data
 187  */
 188 void GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder
 189                                              *te, void **data, size_t * size);
 190
 191
 192 /**
 193  * Reset tree encoder to point previously
 194  * obtained for resuming.
 195  *
 196  * @param te encoding to resume
 197  * @param data the resume data
 198  * @param size the size of the resume data
 199  */
 200 void GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder *te,
 201                                     const void *data, size_t size);
 202 #endif
 203
 204 #endif
 205
 206 /* end of fs_tree.h */