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 http://gnunet.org/encoding.php3
  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
  42  */
  43 unsigned int
  44 GNUNET_FS_compute_depth (uint64_t flen);
  45
  46
  47 /**
  48  * Context for an ECRS-based file encoder that computes
  49  * the Merkle-ish-CHK tree.
  50  */
  51 struct GNUNET_FS_TreeEncoder;
  52
  53
  54 /**
  55  * Function called asking for the current (encoded)
  56  * block to be processed.  After processing the
  57  * client should either call "GNUNET_FS_tree_encode_next"
  58  * or (on error) "GNUNET_FS_tree_encode_finish".
  59  *
  60  * @param cls closure
  61  * @param query the query for the block (key for lookup in the datastore)
  62  * @param offset offset of the block
  63  * @param depth depth of the block
  64  * @param type type of the block (IBLOCK or DBLOCK)
  65  * @param block the (encrypted) block
  66  * @param block_size size of block (in bytes)
  67  */
  68 typedef void (*GNUNET_FS_TreeBlockProcessor)(void *cls,
  69                                              const GNUNET_HashCode *query,
  70                                              uint64_t offset,
  71                                              unsigned int depth,
  72                                              enum GNUNET_BLOCK_Type type,
  73                                              const void *block,
  74                                              uint16_t block_size);
  75
  76
  77 /**
  78  * Function called with information about our
  79  * progress in computing the tree encoding.
  80  *
  81  * @param cls closure
  82  * @param offset where are we in the file
  83  * @param pt_block plaintext of the currently processed block
  84  * @param pt_size size of pt_block
  85  * @param depth depth of the block in the tree
  86  */
  87 typedef void (*GNUNET_FS_TreeProgressCallback)(void *cls,
  88                                                uint64_t offset,
  89                                                const void *pt_block,
  90                                                size_t pt_size,
  91                                                unsigned int depth);
  92
  93
  94 /**
  95  * Initialize a tree encoder.  This function will call "proc" and
  96  * "progress" on each block in the tree.  Once all blocks have been
  97  * processed, "cont" will be scheduled.  The "reader" will be called
  98  * to obtain the (plaintext) blocks for the file.  Note that this
  99  * function will actually never call "proc"; the "proc" function must
 100  * be triggered by calling "GNUNET_FS_tree_encoder_next" to trigger
 101  * encryption (and calling of "proc") for each block.
 102  *
 103  * @param h the global FS context
 104  * @param size overall size of the file to encode
 105  * @param cls closure for reader, proc, progress and cont
 106  * @param reader function to call to read plaintext data
 107  * @param proc function to call on each encrypted block
 108  * @param progress function to call with progress information
 109  * @param cont function to call when done
 110  * @return tree encoder context
 111  */
 112 struct GNUNET_FS_TreeEncoder *
 113 GNUNET_FS_tree_encoder_create (struct GNUNET_FS_Handle *h,
 114                                uint64_t size,
 115                                void *cls,
 116                                GNUNET_FS_DataReader reader,
 117                                GNUNET_FS_TreeBlockProcessor proc,
 118                                GNUNET_FS_TreeProgressCallback progress,
 119                                GNUNET_SCHEDULER_Task cont);
 120
 121
 122 /**
 123  * Encrypt the next block of the file (and
 124  * call proc and progress accordingly; or
 125  * of course "cont" if we have already completed
 126  * encoding of the entire file).
 127  *
 128  * @param te tree encoder to use
 129  */
 130 void GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder * te);
 131
 132
 133 /**
 134  * Clean up a tree encoder and return information
 135  * about the resulting URI or an error message.
 136  *
 137  * @param te the tree encoder to clean up
 138  * @param uri set to the resulting URI (if encoding finished)
 139  * @param emsg set to an error message (if an error occured
 140  *        within the tree encoder; if this function is called
 141  *        prior to completion and prior to an internal error,
 142  *        both "*uri" and "*emsg" will be set to NULL).
 143  */
 144 void GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder * te,
 145                                     struct GNUNET_FS_Uri **uri,
 146                                     char **emsg);
 147
 148
 149 /**
 150  * Compute the size of the current IBlock.
 151  *
 152  * @param height height of the IBlock in the tree (aka overall
 153  *               number of tree levels minus depth); 0 == DBlock
 154  * @param offset current offset in the overall file
 155  * @return size of the corresponding IBlock
 156  */
 157 uint16_t
 158 GNUNET_FS_tree_compute_iblock_size (unsigned int height,
 159                                     uint64_t offset);
 160
 161
 162 /**
 163  * Compute how many bytes of data should be stored in
 164  * the specified node.
 165  *
 166  * @param fsize overall file size
 167  * @param totaldepth depth of the entire tree
 168  * @param offset offset of the node
 169  * @param depth depth of the node
 170  * @return number of bytes stored in this node
 171  */
 172 size_t
 173 GNUNET_FS_tree_calculate_block_size (uint64_t fsize,
 174                                      unsigned int totaldepth,
 175                                      uint64_t offset,
 176                                      unsigned int depth);
 177
 178
 179 #if 0
 180 /* the functions below will be needed for persistence
 181    but are not yet implemented -- FIXME... */
 182 /**
 183  * Get data that would be needed to resume
 184  * the encoding later.
 185  *
 186  * @param te encoding to resume
 187  * @param data set to the resume data
 188  * @param size set to the size of the resume data
 189  */
 190 void GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder * te,
 191                                              void **data,
 192                                              size_t *size);
 193
 194
 195 /**
 196  * Reset tree encoder to point previously
 197  * obtained for resuming.
 198  *
 199  * @param te encoding to resume
 200  * @param data the resume data
 201  * @param size the size of the resume data
 202  */
 203 void GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder * te,
 204                                     const void *data,
 205                                     size_t size);
 206 #endif
 207
 208 #endif
 209
 210 /* end of fs_tree.h */