Open-ILS/xul/staff_client/external/libmar/src/mar.h

   1 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /*
   4  * This file is part of Evergreen.
   5  *
   6  * Evergreen is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published
   8  * by the Free Software Foundation, either version 2 of the License,
   9  * or (at your option) any later version.
  10  *
  11  * Evergreen is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with Evergreen.  If not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * This Source Code Form is derived from code that was originally
  20  * subject to the terms of the Mozilla Public License, v. 2.0 and
  21  * included in Evergreen.  You may, therefore, use this Source Code
  22  * Form under the terms of the Mozilla Public License 2.0.  This
  23  * licensing option does not affect the larger Evergreen project, only
  24  * the Source Code Forms bearing this exception are affected.  If a
  25  * copy of the MPL was not distributed with this file, You can obtain
  26  * one at http://mozilla.org/MPL/2.0/.
  27  */
  28
  29 #ifndef MAR_H__
  30 #define MAR_H__
  31
  32 #include <stdint.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /* We have a MAX_SIGNATURES limit so that an invalid MAR will never
  39  * waste too much of either updater's or signmar's time.
  40  * It is also used at various places internally and will affect memory usage.
  41  * If you want to increase this value above 9 then you need to adjust parsing
  42  * code in tool/mar.c.
  43 */
  44 #define MAX_SIGNATURES 8
  45
  46 struct ProductInformationBlock {
  47   const char *MARChannelID;
  48   const char *productVersion;
  49 };
  50
  51 /**
  52  * The MAR item data structure.
  53  */
  54 typedef struct MarItem_ {
  55   struct MarItem_ *next;  /* private field */
  56   uint32_t offset;        /* offset into archive */
  57   uint32_t length;        /* length of data in bytes */
  58   uint32_t flags;         /* contains file mode bits */
  59   char name[1];           /* file path */
  60 } MarItem;
  61
  62 #define TABLESIZE 256
  63
  64 struct MarFile_ {
  65   FILE *fp;
  66   MarItem *item_table[TABLESIZE];
  67 };
  68
  69 typedef struct MarFile_ MarFile;
  70
  71 /**
  72  * Signature of callback function passed to mar_enum_items.
  73  * @param mar       The MAR file being visited.
  74  * @param item      The MAR item being visited.
  75  * @param data      The data parameter passed by the caller of mar_enum_items.
  76  * @return          A non-zero value to stop enumerating.
  77  */
  78 typedef int (* MarItemCallback)(MarFile *mar, const MarItem *item, void *data);
  79
  80 /**
  81  * Open a MAR file for reading.
  82  * @param path      Specifies the path to the MAR file to open.  This path must
  83  *                  be compatible with fopen.
  84  * @return          NULL if an error occurs.
  85  */
  86 MarFile *mar_open(const char *path);
  87
  88 #ifdef XP_WIN
  89 MarFile *mar_wopen(const PRUnichar *path);
  90 #endif
  91
  92 /**
  93  * Close a MAR file that was opened using mar_open.
  94  * @param mar       The MarFile object to close.
  95  */
  96 void mar_close(MarFile *mar);
  97
  98 /**
  99  * Find an item in the MAR file by name.
 100  * @param mar       The MarFile object to query.
 101  * @param item      The name of the item to query.
 102  * @return          A const reference to a MAR item or NULL if not found.
 103  */
 104 const MarItem *mar_find_item(MarFile *mar, const char *item);
 105
 106 /**
 107  * Enumerate all MAR items via callback function.
 108  * @param mar       The MAR file to enumerate.
 109  * @param callback  The function to call for each MAR item.
 110  * @param data      A caller specified value that is passed along to the
 111  *                  callback function.
 112  * @return          0 if the enumeration ran to completion.  Otherwise, any
 113  *                  non-zero return value from the callback is returned.
 114  */
 115 int mar_enum_items(MarFile *mar, MarItemCallback callback, void *data);
 116
 117 /**
 118  * Read from MAR item at given offset up to bufsize bytes.
 119  * @param mar       The MAR file to read.
 120  * @param item      The MAR item to read.
 121  * @param offset    The byte offset relative to the start of the item.
 122  * @param buf       A pointer to a buffer to copy the data into.
 123  * @param bufsize   The length of the buffer to copy the data into.
 124  * @return          The number of bytes written or a negative value if an
 125  *                  error occurs.
 126  */
 127 int mar_read(MarFile *mar, const MarItem *item, int offset, char *buf,
 128              int bufsize);
 129
 130 /**
 131  * Create a MAR file from a set of files.
 132  * @param dest      The path to the file to create.  This path must be
 133  *                  compatible with fopen.
 134  * @param numfiles  The number of files to store in the archive.
 135  * @param files     The list of null-terminated file paths.  Each file
 136  *                  path must be compatible with fopen.
 137  * @param infoBlock The information to store in the product information block.
 138  * @return          A non-zero value if an error occurs.
 139  */
 140 int mar_create(const char *dest,
 141                int numfiles,
 142                char **files,
 143                struct ProductInformationBlock *infoBlock);
 144
 145 /**
 146  * Extract a MAR file to the current working directory.
 147  * @param path      The path to the MAR file to extract.  This path must be
 148  *                  compatible with fopen.
 149  * @return          A non-zero value if an error occurs.
 150  */
 151 int mar_extract(const char *path);
 152
 153 /**
 154  * Reads the product info block from the MAR file's additional block section.
 155  * The caller is responsible for freeing the fields in infoBlock
 156  * if the return is successful.
 157  *
 158  * @param infoBlock Out parameter for where to store the result to
 159  * @return 0 on success, -1 on failure
 160 */
 161 int
 162 mar_read_product_info_block(MarFile *mar,
 163                             struct ProductInformationBlock *infoBlock);
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif
 168
 169 #endif  /* MAR_H__ */