Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/archive.h @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 // Copyright (C) 2004-2024 Artifex Software, Inc.
2 //
3 // This file is part of MuPDF.
4 //
5 // MuPDF is free software: you can redistribute it and/or modify it under the
6 // terms of the GNU Affero General Public License as published by the Free
7 // Software Foundation, either version 3 of the License, or (at your option)
8 // any later version.
9 //
10 // MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 // FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
13 // details.
14 //
15 // You should have received a copy of the GNU Affero General Public License
16 // along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
17 //
18 // Alternative licensing terms are available from the licensor.
19 // For commercial licensing, see <https://www.artifex.com/> or contact
20 // Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
21 // CA 94129, USA, for further information.
22
23 #ifndef MUPDF_FITZ_ARCHIVE_H
24 #define MUPDF_FITZ_ARCHIVE_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/context.h"
28 #include "mupdf/fitz/buffer.h"
29 #include "mupdf/fitz/stream.h"
30 #include "mupdf/fitz/tree.h"
31
32 /* PUBLIC API */
33
34 /**
35 fz_archive:
36
37 fz_archive provides methods for accessing "archive" files.
38 An archive file is a conceptual entity that contains multiple
39 files, which can be counted, enumerated, and read.
40
41 Implementations of fz_archive based upon directories, zip
42 and tar files are included.
43 */
44
45 typedef struct fz_archive fz_archive;
46
47 /**
48 Open a zip or tar archive
49
50 Open a file and identify its archive type based on the archive
51 signature contained inside.
52
53 filename: a path to a file as it would be given to open(2).
54 */
55 fz_archive *fz_open_archive(fz_context *ctx, const char *filename);
56
57 /**
58 Open zip or tar archive stream.
59
60 Open an archive using a seekable stream object rather than
61 opening a file or directory on disk.
62 */
63 fz_archive *fz_open_archive_with_stream(fz_context *ctx, fz_stream *file);
64
65 /**
66 Open zip or tar archive stream.
67
68 Does the same as fz_open_archive_with_stream, but will not throw
69 an error in the event of failing to recognise the format. Will
70 still throw errors in other cases though!
71 */
72 fz_archive *fz_try_open_archive_with_stream(fz_context *ctx, fz_stream *file);
73
74 /**
75 Open a directory as if it was an archive.
76
77 A special case where a directory is opened as if it was an
78 archive.
79
80 Note that for directories it is not possible to retrieve the
81 number of entries or list the entries. It is however possible
82 to check if the archive has a particular entry.
83
84 path: a path to a directory as it would be given to opendir(3).
85 */
86 fz_archive *fz_open_directory(fz_context *ctx, const char *path);
87
88
89 /**
90 Determine if a given path is a directory.
91
92 In the case of the path not existing, or having no access
93 we will return 0.
94 */
95 int fz_is_directory(fz_context *ctx, const char *path);
96
97 /**
98 Drop a reference to an archive.
99
100 When the last reference is dropped, this closes and releases
101 any memory or filehandles associated with the archive.
102 */
103 void fz_drop_archive(fz_context *ctx, fz_archive *arch);
104
105 /**
106 Keep a reference to an archive.
107 */
108 fz_archive *
109 fz_keep_archive(fz_context *ctx, fz_archive *arch);
110
111 /**
112 Return a pointer to a string describing the format of the
113 archive.
114
115 The lifetime of the string is unspecified (in current
116 implementations the string will persist until the archive
117 is closed, but this is not guaranteed).
118 */
119 const char *fz_archive_format(fz_context *ctx, fz_archive *arch);
120
121 /**
122 Number of entries in archive.
123
124 Will always return a value >= 0.
125
126 May throw an exception if this type of archive cannot count the
127 entries (such as a directory).
128 */
129 int fz_count_archive_entries(fz_context *ctx, fz_archive *arch);
130
131 /**
132 Get listed name of entry position idx.
133
134 idx: Must be a value >= 0 < return value from
135 fz_count_archive_entries. If not in range NULL will be
136 returned.
137
138 May throw an exception if this type of archive cannot list the
139 entries (such as a directory).
140 */
141 const char *fz_list_archive_entry(fz_context *ctx, fz_archive *arch, int idx);
142
143 /**
144 Check if entry by given name exists.
145
146 If named entry does not exist 0 will be returned, if it does
147 exist 1 is returned.
148
149 name: Entry name to look for, this must be an exact match to
150 the entry name in the archive.
151 */
152 int fz_has_archive_entry(fz_context *ctx, fz_archive *arch, const char *name);
153
154 /**
155 Opens an archive entry as a stream.
156
157 name: Entry name to look for, this must be an exact match to
158 the entry name in the archive.
159
160 Throws an exception if a matching entry cannot be found.
161 */
162 fz_stream *fz_open_archive_entry(fz_context *ctx, fz_archive *arch, const char *name);
163
164 /**
165 Opens an archive entry as a stream.
166
167 Returns NULL if a matching entry cannot be found, otherwise
168 behaves exactly as fz_open_archive_entry.
169 */
170 fz_stream *fz_try_open_archive_entry(fz_context *ctx, fz_archive *arch, const char *name);
171
172 /**
173 Reads all bytes in an archive entry
174 into a buffer.
175
176 name: Entry name to look for, this must be an exact match to
177 the entry name in the archive.
178
179 Throws an exception if a matching entry cannot be found.
180 */
181 fz_buffer *fz_read_archive_entry(fz_context *ctx, fz_archive *arch, const char *name);
182
183 /**
184 Reads all bytes in an archive entry
185 into a buffer.
186
187 name: Entry name to look for, this must be an exact match to
188 the entry name in the archive.
189
190 Returns NULL if a matching entry cannot be found. Otherwise behaves
191 the same as fz_read_archive_entry. Exceptions may be thrown.
192 */
193 fz_buffer *fz_try_read_archive_entry(fz_context *ctx, fz_archive *arch, const char *name);
194
195 /**
196 fz_archive: tar implementation
197 */
198
199 /**
200 Detect if stream object is a tar archive.
201
202 Assumes that the stream object is seekable.
203 */
204 int fz_is_tar_archive(fz_context *ctx, fz_stream *file);
205
206 /**
207 Detect if stream object is an archive supported by libarchive.
208
209 Assumes that the stream object is seekable.
210 */
211 int fz_is_libarchive_archive(fz_context *ctx, fz_stream *file);
212
213 /**
214 Detect if stream object is a cfb archive.
215
216 Assumes that the stream object is seekable.
217 */
218 int fz_is_cfb_archive(fz_context *ctx, fz_stream *file);
219
220 /**
221 Open a tar archive file.
222
223 An exception is thrown if the file is not a tar archive as
224 indicated by the presence of a tar signature.
225
226 filename: a path to a tar archive file as it would be given to
227 open(2).
228 */
229 fz_archive *fz_open_tar_archive(fz_context *ctx, const char *filename);
230
231 /**
232 Open a tar archive stream.
233
234 Open an archive using a seekable stream object rather than
235 opening a file or directory on disk.
236
237 An exception is thrown if the stream is not a tar archive as
238 indicated by the presence of a tar signature.
239
240 */
241 fz_archive *fz_open_tar_archive_with_stream(fz_context *ctx, fz_stream *file);
242
243 /**
244 Open an archive using libarchive.
245
246 An exception is thrown if the file is not supported by libarchive.
247
248 filename: a path to an archive file as it would be given to
249 open(2).
250 */
251 fz_archive *fz_open_libarchive_archive(fz_context *ctx, const char *filename);
252
253 /**
254 Open an archive using libarchive.
255
256 Open an archive using a seekable stream object rather than
257 opening a file or directory on disk.
258
259 An exception is thrown if the stream is not supported by libarchive.
260 */
261 fz_archive *fz_open_libarchive_archive_with_stream(fz_context *ctx, fz_stream *file);
262
263 /**
264 Open a cfb file as an archive.
265
266 An exception is thrown if the file is not recognised as a cfb.
267
268 filename: a path to an archive file as it would be given to
269 open(2).
270 */
271 fz_archive *fz_open_cfb_archive(fz_context *ctx, const char *filename);
272
273 /**
274 Open a cfb file as an archive.
275
276 Open an archive using a seekable stream object rather than
277 opening a file or directory on disk.
278
279 An exception is thrown if the file is not recognised as a chm.
280 */
281 fz_archive *fz_open_cfb_archive_with_stream(fz_context *ctx, fz_stream *file);
282
283 /**
284 fz_archive: zip implementation
285 */
286
287 /**
288 Detect if stream object is a zip archive.
289
290 Assumes that the stream object is seekable.
291 */
292 int fz_is_zip_archive(fz_context *ctx, fz_stream *file);
293
294 /**
295 Open a zip archive file.
296
297 An exception is thrown if the file is not a zip archive as
298 indicated by the presence of a zip signature.
299
300 filename: a path to a zip archive file as it would be given to
301 open(2).
302 */
303 fz_archive *fz_open_zip_archive(fz_context *ctx, const char *path);
304
305 /**
306 Open a zip archive stream.
307
308 Open an archive using a seekable stream object rather than
309 opening a file or directory on disk.
310
311 An exception is thrown if the stream is not a zip archive as
312 indicated by the presence of a zip signature.
313
314 */
315 fz_archive *fz_open_zip_archive_with_stream(fz_context *ctx, fz_stream *file);
316
317 /**
318 fz_zip_writer offers methods for creating and writing zip files.
319 It can be seen as the reverse of the fz_archive zip
320 implementation.
321 */
322
323 typedef struct fz_zip_writer fz_zip_writer;
324
325 /**
326 Create a new zip writer that writes to a given file.
327
328 Open an archive using a seekable stream object rather than
329 opening a file or directory on disk.
330 */
331 fz_zip_writer *fz_new_zip_writer(fz_context *ctx, const char *filename);
332
333 /**
334 Create a new zip writer that writes to a given output stream.
335
336 Ownership of out passes in immediately upon calling this function.
337 The caller should never drop the fz_output, even if this function throws
338 an exception.
339 */
340 fz_zip_writer *fz_new_zip_writer_with_output(fz_context *ctx, fz_output *out);
341
342
343 /**
344 Given a buffer of data, (optionally) compress it, and add it to
345 the zip file with the given name.
346 */
347 void fz_write_zip_entry(fz_context *ctx, fz_zip_writer *zip, const char *name, fz_buffer *buf, int compress);
348
349 /**
350 Close the zip file for writing.
351
352 This flushes any pending data to the file. This can throw
353 exceptions.
354 */
355 void fz_close_zip_writer(fz_context *ctx, fz_zip_writer *zip);
356
357 /**
358 Drop the reference to the zipfile.
359
360 In common with other 'drop' methods, this will never throw an
361 exception.
362 */
363 void fz_drop_zip_writer(fz_context *ctx, fz_zip_writer *zip);
364
365 /**
366 Create an archive that holds named buffers.
367
368 tree can either be a preformed tree with fz_buffers as values,
369 or it can be NULL for an empty tree.
370 */
371 fz_archive *fz_new_tree_archive(fz_context *ctx, fz_tree *tree);
372
373 /**
374 Add a named buffer to an existing tree archive.
375
376 The tree will take a new reference to the buffer. Ownership
377 is not transferred.
378 */
379 void fz_tree_archive_add_buffer(fz_context *ctx, fz_archive *arch_, const char *name, fz_buffer *buf);
380
381 /**
382 Add a named block of data to an existing tree archive.
383
384 The data will be copied into a buffer, and so the caller
385 may free it as soon as this returns.
386 */
387 void fz_tree_archive_add_data(fz_context *ctx, fz_archive *arch_, const char *name, const void *data, size_t size);
388
389 /**
390 Create a new multi archive (initially empty).
391 */
392 fz_archive *fz_new_multi_archive(fz_context *ctx);
393
394 /**
395 Add an archive to the set of archives handled by a multi
396 archive.
397
398 If path is NULL, then the archive contents will appear at the
399 top level, otherwise, the archives contents will appear prefixed
400 by path.
401 */
402 void fz_mount_multi_archive(fz_context *ctx, fz_archive *arch_, fz_archive *sub, const char *path);
403
404 typedef int (fz_recognize_archive_fn)(fz_context *, fz_stream *);
405 typedef fz_archive *(fz_open_archive_fn)(fz_context *, fz_stream *);
406
407 typedef struct
408 {
409 fz_recognize_archive_fn *recognize;
410 fz_open_archive_fn *open;
411 }
412 fz_archive_handler;
413
414 FZ_DATA extern const fz_archive_handler fz_libarchive_archive_handler;
415
416 void fz_register_archive_handler(fz_context *ctx, const fz_archive_handler *handler);
417
418 /**
419 Implementation details: Subject to change.
420 */
421
422 struct fz_archive
423 {
424 int refs;
425 fz_stream *file;
426
427 const char *format;
428
429 void (*drop_archive)(fz_context *ctx, fz_archive *arch);
430 int (*count_entries)(fz_context *ctx, fz_archive *arch);
431 const char *(*list_entry)(fz_context *ctx, fz_archive *arch, int idx);
432 int (*has_entry)(fz_context *ctx, fz_archive *arch, const char *name);
433 fz_buffer *(*read_entry)(fz_context *ctx, fz_archive *arch, const char *name);
434 fz_stream *(*open_entry)(fz_context *ctx, fz_archive *arch, const char *name);
435 };
436
437 fz_archive *fz_new_archive_of_size(fz_context *ctx, fz_stream *file, int size);
438
439 #define fz_new_derived_archive(C,F,M) \
440 ((M*)Memento_label(fz_new_archive_of_size(C, F, sizeof(M)), #M))
441
442
443
444 #endif