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