src/fs/fs_tree.h

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