2 This file is part of GNUnet.
3 Copyright (C) 2009 GNUnet e.V.
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.
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.
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/>.
21 * @brief Merkle-tree-ish-CHK file encoding for GNUnet
22 * @see https://gnunet.org/encoding
23 * @author Krista Bennett
24 * @author Christian Grothoff
27 * - decide if this API should be made public (gnunet_fs_service.h)
28 * or remain "internal" (but with exported symbols?)
30 #ifndef GNUNET_FS_TREE_H
31 #define GNUNET_FS_TREE_H
36 * Compute the depth of the CHK tree.
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.
42 GNUNET_FS_compute_depth (uint64_t flen);
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).
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
55 GNUNET_FS_tree_compute_tree_size (unsigned int depth);
59 * Compute how many bytes of data should be stored in
60 * the specified block.
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;
66 * @param depth depth of the node in the tree, 0 for DBLOCK
67 * @return number of bytes stored in this node
70 GNUNET_FS_tree_calculate_block_size (uint64_t fsize, uint64_t offset,
75 * Context for an ECRS-based file encoder that computes
76 * the Merkle-ish-CHK tree.
78 struct GNUNET_FS_TreeEncoder;
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".
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)
95 typedef void (*GNUNET_FS_TreeBlockProcessor) (void *cls,
96 const struct ContentHashKey * chk,
99 enum GNUNET_BLOCK_Type type,
101 uint16_t block_size);
105 * Function called with information about our
106 * progress in computing the tree encoding.
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
114 typedef void (*GNUNET_FS_TreeProgressCallback) (void *cls, uint64_t offset,
115 const void *pt_block,
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.
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
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);
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).
152 * @param te tree encoder to use
155 GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder *te);
159 * Get the resulting URI from the encoding.
161 * @param te the tree encoder to clean up
162 * @return uri set to the resulting URI (if encoding finished), NULL otherwise
164 struct GNUNET_FS_Uri *
165 GNUNET_FS_tree_encoder_get_uri (struct GNUNET_FS_TreeEncoder *te);
169 * Clean up a tree encoder and return information
170 * about possible errors.
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).
179 GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder *te,
184 /* the functions below will be needed for persistence
185 but are not yet implemented -- FIXME... */
187 * Get data that would be needed to resume
188 * the encoding later.
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
195 GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder *te,
196 void **data, size_t * size);
200 * Reset tree encoder to point previously
201 * obtained for resuming.
203 * @param te encoding to resume
204 * @param data the resume data
205 * @param size the size of the resume data
208 GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder *te,
209 const void *data, size_t size);
215 /* end of fs_tree.h */