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  */
  99 struct GNUNET_FS_TreeEncoder *
 100 GNUNET_FS_tree_encoder_create (struct GNUNET_FS_Handle *h,
 101                                uint64_t size,
 102                                void *cls,
 103                                GNUNET_FS_DataReader reader,
 104                                GNUNET_FS_TreeBlockProcessor proc,
 105                                GNUNET_FS_TreeProgressCallback progress,
 106                                GNUNET_SCHEDULER_Task cont);
 107
 108
 109 /**
 110  * Encrypt the next block of the file (and
 111  * call proc and progress accordingly; or
 112  * of course "cont" if we have already completed
 113  * encoding of the entire file).
 114  *
 115  * @param te tree encoder to use
 116  */
 117 void GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder * te);
 118
 119
 120 /**
 121  * Clean up a tree encoder and return information
 122  * about the resulting URI or an error message.
 123  *
 124  * @param te the tree encoder to clean up
 125  * @param uri set to the resulting URI (if encoding finished)
 126  * @param emsg set to an error message (if an error occured
 127  *        within the tree encoder; if this function is called
 128  *        prior to completion and prior to an internal error,
 129  *        both "*uri" and "*emsg" will be set to NULL).
 130  */
 131 void GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder * te,
 132                                     struct GNUNET_FS_Uri **uri,
 133                                     char **emsg);
 134
 135
 136 #if 0
 137 /* the functions below will be needed for persistence
 138    but are not yet implemented -- FIXME... */
 139 /**
 140  * Get data that would be needed to resume
 141  * the encoding later.
 142  *
 143  * @param te encoding to resume
 144  * @param data set to the resume data
 145  * @param size set to the size of the resume data
 146  */
 147 void GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder * te,
 148                                              void **data,
 149                                              size_t *size);
 150
 151
 152 /**
 153  * Reset tree encoder to point previously
 154  * obtained for resuming.
 155  *
 156  * @param te encoding to resume
 157  * @param data the resume data
 158  * @param size the size of the resume data
 159  */
 160 void GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder * te,
 161                                     const void *data,
 162                                     size_t size);
 163 #endif
 164
 165 #endif
 166
 167 /* end of fs_tree.h */