bfbd7019b492699b66e35ce7a1f33e025da17226
[oweals/gnunet.git] / 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 2, 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 type type of the block (IBLOCK or DBLOCK)
64  * @param block the (encrypted) block
65  * @param block_size size of block (in bytes)
66  */
67 typedef void (*GNUNET_FS_TreeBlockProcessor)(void *cls,
68                                              const GNUNET_HashCode *query,
69                                              uint64_t offset,
70                                              uint32_t type,
71                                              const void *block,
72                                              uint16_t block_size);
73                                              
74
75 /**
76  * Function called with information about our
77  * progress in computing the tree encoding.
78  *
79  * @param cls closure
80  * @param offset where are we in the file
81  * @param pt_block plaintext of the currently processed block
82  * @param pt_size size of pt_block
83  * @param depth depth of the block in the tree
84  */
85 typedef void (*GNUNET_FS_TreeProgressCallback)(void *cls,
86                                                uint64_t offset,
87                                                const void *pt_block,
88                                                size_t pt_size,
89                                                unsigned int depth);
90                                                
91
92 /**
93  * Initialize a tree encoder.  This function will call "proc" and
94  * "progress" on each block in the tree.  Once all blocks have been
95  * processed, "cont" will be scheduled.  The "reader" will be called
96  * to obtain the (plaintext) blocks for the file.  Note that this
97  * function will actually never call "proc"; the "proc" function must
98  * be triggered by calling "GNUNET_FS_tree_encoder_next" to trigger
99  * encryption (and calling of "proc") for each block.
100  *
101  * @param h the global FS context
102  * @param size overall size of the file to encode
103  * @param cls closure for reader, proc, progress and cont
104  * @param reader function to call to read plaintext data
105  * @param proc function to call on each encrypted block
106  * @param progress function to call with progress information 
107  * @param cont function to call when done
108  * @return tree encoder context
109  */
110 struct GNUNET_FS_TreeEncoder *
111 GNUNET_FS_tree_encoder_create (struct GNUNET_FS_Handle *h,
112                                uint64_t size,
113                                void *cls,
114                                GNUNET_FS_DataReader reader,
115                                GNUNET_FS_TreeBlockProcessor proc,
116                                GNUNET_FS_TreeProgressCallback progress,
117                                GNUNET_SCHEDULER_Task cont);
118
119
120 /**
121  * Encrypt the next block of the file (and 
122  * call proc and progress accordingly; or 
123  * of course "cont" if we have already completed
124  * encoding of the entire file).
125  *
126  * @param te tree encoder to use
127  */
128 void GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder * te);
129
130
131 /**
132  * Clean up a tree encoder and return information
133  * about the resulting URI or an error message.
134  * 
135  * @param te the tree encoder to clean up
136  * @param uri set to the resulting URI (if encoding finished)
137  * @param emsg set to an error message (if an error occured
138  *        within the tree encoder; if this function is called
139  *        prior to completion and prior to an internal error,
140  *        both "*uri" and "*emsg" will be set to NULL).
141  */
142 void GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder * te,
143                                     struct GNUNET_FS_Uri **uri,
144                                     char **emsg);
145
146
147 #if 0
148 /* the functions below will be needed for persistence
149    but are not yet implemented -- FIXME... */
150 /**
151  * Get data that would be needed to resume
152  * the encoding later.
153  * 
154  * @param te encoding to resume
155  * @param data set to the resume data
156  * @param size set to the size of the resume data
157  */
158 void GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder * te,
159                                              void **data,
160                                              size_t *size);
161
162
163 /**
164  * Reset tree encoder to point previously
165  * obtained for resuming.
166  * 
167  * @param te encoding to resume
168  * @param data the resume data
169  * @param size the size of the resume data
170  */
171 void GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder * te,
172                                     const void *data,
173                                     size_t size);
174 #endif
175
176 #endif
177
178 /* end of fs_tree.h */