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