2 This file is part of GNUnet.
3 (C) 2009 Christian Grothoff (and other contributing authors)
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.
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.
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.
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
29 * - decide if this API should be made public (gnunet_fs_service.h)
30 * or remain "internal" (but with exported symbols?)
32 #ifndef GNUNET_FS_TREE_H
33 #define GNUNET_FS_TREE_H
38 * Compute the depth of the CHK tree.
40 * @param flen file length for which to compute the depth
41 * @return depth of the tree
44 GNUNET_FS_compute_depth (uint64_t flen);
48 * Context for an ECRS-based file encoder that computes
49 * the Merkle-ish-CHK tree.
51 struct GNUNET_FS_TreeEncoder;
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".
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)
68 typedef void (*GNUNET_FS_TreeBlockProcessor)(void *cls,
69 const GNUNET_HashCode *query,
72 enum GNUNET_BLOCK_Type type,
78 * Function called with information about our
79 * progress in computing the tree encoding.
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
87 typedef void (*GNUNET_FS_TreeProgressCallback)(void *cls,
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.
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
112 struct GNUNET_FS_TreeEncoder *
113 GNUNET_FS_tree_encoder_create (struct GNUNET_FS_Handle *h,
116 GNUNET_FS_DataReader reader,
117 GNUNET_FS_TreeBlockProcessor proc,
118 GNUNET_FS_TreeProgressCallback progress,
119 GNUNET_SCHEDULER_Task cont);
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).
128 * @param te tree encoder to use
130 void GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder * te);
134 * Clean up a tree encoder and return information
135 * about the resulting URI or an error message.
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).
144 void GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder * te,
145 struct GNUNET_FS_Uri **uri,
150 * Compute the size of the current IBlock.
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
158 GNUNET_FS_tree_compute_iblock_size (unsigned int height,
163 * Compute how many bytes of data should be stored in
164 * the specified node.
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
173 GNUNET_FS_tree_calculate_block_size (uint64_t fsize,
174 unsigned int totaldepth,
180 /* the functions below will be needed for persistence
181 but are not yet implemented -- FIXME... */
183 * Get data that would be needed to resume
184 * the encoding later.
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
190 void GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder * te,
196 * Reset tree encoder to point previously
197 * obtained for resuming.
199 * @param te encoding to resume
200 * @param data the resume data
201 * @param size the size of the resume data
203 void GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder * te,
210 /* end of fs_tree.h */