git.gag.com Git - debian/amanda/blob - amar-src/amar.h

   1 /*
   2  * Copyright (c) 2008-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17  *
  18  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  19  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  20  */
  21
  22 #include <glib.h>
  23
  24 /* A note regarding error handling in this module.  Amar returns errors via the
  25  * Glib GError mechanism.  Most functions return a boolean, where TRUE
  26  * indicates success, and FALSE indicates an error which is indicated in the
  27  * 'error' parameter.
  28  *
  29  * Fatal programming errors are handled with assertions and error exits; any
  30  * fatal format or system errors are handled via GError.  Some format errors
  31  * (e.g., missing EOAs at the end of a file) are handled without any
  32  * acknowledgement.
  33  *
  34  * The domain for amar errors is that returned from amar_error_quark, and error
  35  * codes are system error codes (e.g., EINVAL, ENOSPC). */
  36
  37 GQuark amar_error_quark(void);
  38
  39 /* opaque types for archives, files, and attributes */
  40
  41 typedef struct amar_s amar_t;
  42 typedef struct amar_file_s amar_file_t;
  43 typedef struct amar_attr_s amar_attr_t;
  44
  45 /* Application attribute IDs should start at AMAR_ATTR_APP_START */
  46
  47 enum {
  48     /* internal-use only attributes */
  49     AMAR_ATTR_FILENAME = 0,
  50     AMAR_ATTR_EOF = 1,
  51
  52     /* anything above this value can be used by the application */
  53     AMAR_ATTR_APP_START = 16,
  54     AMAR_ATTR_GENERIC_DATA = AMAR_ATTR_APP_START,
  55 };
  56
  57 /* Create an object to read/write an amanda archive on the file descriptor fd.
  58  * @param fd: file descriptor of the file, it must already be opened
  59  * @mode: O_RDONLY for reading, O_WRONLY for writing
  60  * @returns: NULL on error
  61  */
  62 amar_t *amar_new(int fd, mode_t mode, GError **error);
  63
  64 /* Finish writing to this fd.  All buffers are flushed, but the file descriptor
  65  * is not closed -- the user must close it. */
  66 gboolean amar_close(amar_t *archive, GError **error);
  67
  68 /* create a new 'file' object on the archive.  The filename is treated as a
  69  * binary blob, but if filename_len is zero, then its length will be calculated
  70  * with strlen().  A zero-length filename_buf is not allowed.
  71  *
  72  * Note that a header record will only be written if header_offset is non-NULL,
  73  * as this represents a location to which a reader could seek.
  74  *
  75  * @param archive: the archive containing this file
  76  * @param filename_buf: filename to include in the file
  77  * @param filename_len: length of the filename_buf, or 0 to calculate
  78  * @param header_offset (output): offset of the header record preceding
  79  *      this file; pass NULL to ignore.
  80  * @returns: NULL on error, otherwise a file object
  81  */
  82 amar_file_t *amar_new_file(
  83             amar_t *archive,
  84             char *filename_buf,
  85             gsize filename_len,
  86             off_t *header_offset,
  87             GError **error);
  88
  89 /* Flush all buffer the 'file' object and write a record with ID=2 */
  90 gboolean amar_file_close(
  91             amar_file_t *file,
  92             GError **error);
  93
  94 /* create a new 'attribute' object with attrid attached to the file
  95  *
  96  * @returns: NULL on error, otherwise an attribute object
  97  */
  98 amar_attr_t *amar_new_attr(
  99             amar_file_t *file,
 100             uint16_t attrid,
 101             GError **error);
 102
 103 /* flush all buffers and mark the end of the attribute */
 104 gboolean amar_attr_close(
 105             amar_attr_t *attribute,
 106             GError **error);
 107
 108 /* Add 'size' byte of data from 'data' to the attribute.  If this is the
 109  * last data in this attribute, set eoa to TRUE.  This will save space by
 110  * writing and end-of-attribute indication in this record, instead of adding
 111  * an empty EOA record.
 112  */
 113 gboolean amar_attr_add_data_buffer(
 114             amar_attr_t *attribute,
 115             gpointer data,
 116             gsize size,
 117             gboolean eoa,
 118             GError **error);
 119
 120 /* This function reads from the file descriptor 'fd' until EOF and adds
 121  * the resulting data to the attribute.  The end of the attribute is
 122  * flagged appropriately if EOA is true.
 123  *
 124  * @param attribute: the attribute for the data
 125  * @param fd: the file descriptor from which to read
 126  * @param eoa: add an EOA bit to the end?
 127  * @returns: number of bytes read from fd, or -1 on error
 128  */
 129 off_t amar_attr_add_data_fd(
 130             amar_attr_t *attribute,
 131             int fd,
 132             gboolean eoa,
 133             GError **error);
 134
 135 /* When reading files, the handling of each attribute can be configured
 136  * separately.  Some attributes may always be short enough to fit in memory,
 137  * and in this case the archive interface will take care of assembling any
 138  * fragments for you.  Some attributes should be ignored, while others
 139  * will call a function for each fragment.
 140  *
 141  * There are a a number of xx_data options available here, that deserve some
 142  * disambiguation.
 143  *  - user_data is global to the entire read operation (it is a parameter to
 144  *    amar_read)
 145  *  - file_data is specific to the current file; it is set by the start_file
 146  *    callback and freed by the finish_file callback.
 147  *  - attrid_data is specific this the current attribute ID, across all files;
 148  *    it comes from the amar_attr_handling_t struct.
 149  *  - attr_data is specific to the current instance of the particular
 150  *    attribute.  It points to a NULL pointer on the first call to the fragment
 151  *    callback, and can be set at that time.  It should be freed when the EOA
 152  *    argument is TRUE.
 153  *
 154  * @param user_data: the pointer passed to amar_read
 155  * @param filenum: the file number for this record
 156  * @param file_data: the file_data pointer returned from the start_file callback
 157  * @param attrid: the attribute id for this record
 158  * @param attrid_data: the data from the handling array
 159  * @param attr_data (in/out): data for this attribute; this will be the same
 160  *        pointer for every callback for a particular instance of an attribute.
 161  *        Any resources should be freed when eoa is true.
 162  * @param data: the data for this fragment
 163  * @param size: the size of data
 164  * @param eoa: TRUE iff this is the last fragment for this attribute
 165  * @param truncated: TRUE if this attribute is likely to be incomplete (e.g.,
 166  *        in an error situation)
 167  * @returns: FALSE if the amar_read call should be aborted
 168  */
 169 typedef gboolean (*amar_fragment_callback_t)(
 170         gpointer user_data,
 171         uint16_t filenum,
 172         gpointer file_data,
 173         uint16_t attrid,
 174         gpointer attrid_data,
 175         gpointer *attr_data,
 176         gpointer data,
 177         gsize size,
 178         gboolean eoa,
 179         gboolean truncated);
 180
 181 /* amar_read takes an array of this struct, terminated by an entry
 182  * with attrid 0.  This final entry is used as the "catchall" for attributes
 183  * not matching any other array entries. */
 184 typedef struct amar_attr_handling_s {
 185     uint16_t attrid;
 186
 187     /* if nonzero, this is the minimum size fragment that will be passed to the
 188      * callback.  Use SIZE_MAX for no limit, although this may result in
 189      * excessive memory use while parsing a malicious or corrupt archive. */
 190     gsize min_size;
 191
 192     /* if non-NULL, this function will be called for each fragment
 193      * with this attribute ID */
 194     amar_fragment_callback_t callback;
 195
 196     /* this value is passed as the attr_data parameter to the callback */
 197     gpointer attrid_data;
 198 } amar_attr_handling_t;
 199
 200 /* This function is called for each new file, and can decide whether to ignore
 201  * the file, or set up file-specific data.
 202  *
 203  * @param user_data: the pointer passed to amar_read
 204  * @param filenum: the file number for this record
 205  * @param filename_buf: the filename of this file
 206  * @param filename_len: the length of the filename
 207  * @param ignore (output): if set to TRUE, ignore all attributes for this file.
 208  * @param file_data (output): space to store file-specific data
 209  * @returns: FALSE if the amar_read call should be aborted
 210  */
 211 typedef gboolean (*amar_file_start_callback_t)(
 212         gpointer user_data,
 213         uint16_t filenum,
 214         gpointer filename_buf,
 215         gsize filename_len,
 216         gboolean *ignore,
 217         gpointer *file_data);
 218
 219 /* This function is called for each new file, and can decide whether to ignore
 220  * the file, or set up file-specific data.
 221  *
 222  * @param user_data: the pointer passed to amar_read
 223  * @param filenum: the file number for this record
 224  * @param file_data (output): space to store file-specific data
 225  * @param truncated: TRUE if this file is likely to be incomplete (e.g.,
 226  *        in an error situation, or at an early EOF)
 227  * @returns: FALSE if the amar_read call should be aborted
 228  */
 229 typedef gboolean (*amar_file_finish_callback_t)(
 230         gpointer user_data,
 231         uint16_t filenum,
 232         gpointer *file_data,
 233         gboolean truncated);
 234
 235 /* This function actually performs the read operation, calling all of the
 236  * above callbacks.  If any of the callbacks return FALSE, this function
 237  * returns FALSE but does not set its error parameter.
 238  *
 239  * @param user_data: passed to all callbacks
 240  * @param handling_array: array giving handling information
 241  * @param file_start_cb: callback for file starts
 242  * @param file_finish_cb: callback for file finishs
 243  * @param error (output): the error result
 244  * @returns: FALSE on error or an early exit, otherwise TRUE
 245  */
 246 gboolean amar_read(
 247         amar_t *archive,
 248         gpointer user_data,
 249         amar_attr_handling_t *handling_array,
 250         amar_file_start_callback_t file_start_cb,
 251         amar_file_finish_callback_t file_finish_cb,
 252         GError **error);