Add libmar to build update tools to the repo.
[working/Evergreen.git] / 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__ */