Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/stream.h @ 3:2c135c81b16c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
MERGE: upstream PyMuPDF 1.26.4 with MuPDF 1.26.7
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:44:09 +0200
parents b50eed0cc0ef
children
comparison
equal deleted inserted replaced
0:6015a75abc2d 3:2c135c81b16c
1 // Copyright (C) 2004-2021 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_STREAM_H
24 #define MUPDF_FITZ_STREAM_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/context.h"
28 #include "mupdf/fitz/buffer.h"
29
30 /**
31 Return true if the named file exists and is readable.
32 */
33 int fz_file_exists(fz_context *ctx, const char *path);
34
35 /**
36 fz_stream is a buffered reader capable of seeking in both
37 directions.
38
39 Streams are reference counted, so references must be dropped
40 by a call to fz_drop_stream.
41
42 Only the data between rp and wp is valid.
43 */
44 typedef struct fz_stream fz_stream;
45
46 /**
47 Open the named file and wrap it in a stream.
48
49 filename: Path to a file. On non-Windows machines the filename
50 should be exactly as it would be passed to fopen(2). On Windows
51 machines, the path should be UTF-8 encoded so that non-ASCII
52 characters can be represented. Other platforms do the encoding
53 as standard anyway (and in most cases, particularly for MacOS
54 and Linux, the encoding they use is UTF-8 anyway).
55 */
56 fz_stream *fz_open_file(fz_context *ctx, const char *filename);
57
58 /**
59 Do the same as fz_open_file, but delete the file upon close.
60 */
61 fz_stream *fz_open_file_autodelete(fz_context *ctx, const char *filename);
62
63 /**
64 Open the named file and wrap it in a stream.
65
66 Does the same as fz_open_file, but in the event the file
67 does not open, it will return NULL rather than throw an
68 exception.
69 */
70 fz_stream *fz_try_open_file(fz_context *ctx, const char *name);
71
72 #ifdef _WIN32
73 /**
74 Open the named file and wrap it in a stream.
75
76 This function is only available when compiling for Win32.
77
78 filename: Wide character path to the file as it would be given
79 to _wfopen().
80 */
81 fz_stream *fz_open_file_w(fz_context *ctx, const wchar_t *filename);
82 #endif /* _WIN32 */
83
84 /**
85 Return the filename (UTF-8 encoded) from which a stream was opened.
86
87 Returns NULL if the filename is not available (or the stream was
88 opened from a source other than a file).
89 */
90 const char *fz_stream_filename(fz_context *ctx, fz_stream *stm);
91
92 /**
93 Open a block of memory as a stream.
94
95 data: Pointer to start of data block. Ownership of the data
96 block is NOT passed in.
97
98 len: Number of bytes in data block.
99
100 Returns pointer to newly created stream. May throw exceptions on
101 failure to allocate.
102 */
103 fz_stream *fz_open_memory(fz_context *ctx, const unsigned char *data, size_t len);
104
105 /**
106 Open a buffer as a stream.
107
108 buf: The buffer to open. Ownership of the buffer is NOT passed
109 in (this function takes its own reference).
110
111 Returns pointer to newly created stream. May throw exceptions on
112 failure to allocate.
113 */
114 fz_stream *fz_open_buffer(fz_context *ctx, fz_buffer *buf);
115
116 /**
117 Attach a filter to a stream that will store any
118 characters read from the stream into the supplied buffer.
119
120 chain: The underlying stream to leech from.
121
122 buf: The buffer into which the read data should be appended.
123 The buffer will be resized as required.
124
125 Returns pointer to newly created stream. May throw exceptions on
126 failure to allocate.
127 */
128 fz_stream *fz_open_leecher(fz_context *ctx, fz_stream *chain, fz_buffer *buf);
129
130 /**
131 Increments the reference count for a stream. Returns the same
132 pointer.
133
134 Never throws exceptions.
135 */
136 fz_stream *fz_keep_stream(fz_context *ctx, fz_stream *stm);
137
138 /**
139 Decrements the reference count for a stream.
140
141 When the reference count for the stream hits zero, frees the
142 storage used for the fz_stream itself, and (usually)
143 releases the underlying resources that the stream is based upon
144 (depends on the method used to open the stream initially).
145 */
146 void fz_drop_stream(fz_context *ctx, fz_stream *stm);
147
148 /**
149 return the current reading position within a stream
150 */
151 int64_t fz_tell(fz_context *ctx, fz_stream *stm);
152
153 /**
154 Seek within a stream.
155
156 stm: The stream to seek within.
157
158 offset: The offset to seek to.
159
160 whence: From where the offset is measured (see fseek).
161 SEEK_SET - start of stream.
162 SEEK_CUR - current position.
163 SEEK_END - end of stream.
164
165 */
166 void fz_seek(fz_context *ctx, fz_stream *stm, int64_t offset, int whence);
167
168 /**
169 Read from a stream into a given data block.
170
171 stm: The stream to read from.
172
173 data: The data block to read into.
174
175 len: The length of the data block (in bytes).
176
177 Returns the number of bytes read. May throw exceptions.
178 */
179 size_t fz_read(fz_context *ctx, fz_stream *stm, unsigned char *data, size_t len);
180
181 /**
182 Read from a stream discarding data.
183
184 stm: The stream to read from.
185
186 len: The number of bytes to read.
187
188 Returns the number of bytes read. May throw exceptions.
189 */
190 size_t fz_skip(fz_context *ctx, fz_stream *stm, size_t len);
191
192 /**
193 Read all of a stream into a buffer.
194
195 stm: The stream to read from
196
197 initial: Suggested initial size for the buffer.
198
199 Returns a buffer created from reading from the stream. May throw
200 exceptions on failure to allocate.
201 */
202 fz_buffer *fz_read_all(fz_context *ctx, fz_stream *stm, size_t initial);
203
204 /**
205 Read all the contents of a file into a buffer.
206 */
207 fz_buffer *fz_read_file(fz_context *ctx, const char *filename);
208
209 /**
210 Read all the contents of a file into a buffer.
211
212 Returns NULL if the file does not exist, otherwise
213 behaves exactly as fz_read_file.
214 */
215 fz_buffer *fz_try_read_file(fz_context *ctx, const char *filename);
216
217 /**
218 fz_read_[u]int(16|24|32|64)(_le)?
219
220 Read a 16/32/64 bit signed/unsigned integer from stream,
221 in big or little-endian byte orders.
222
223 Throws an exception if EOF is encountered.
224 */
225 uint16_t fz_read_uint16(fz_context *ctx, fz_stream *stm);
226 uint32_t fz_read_uint24(fz_context *ctx, fz_stream *stm);
227 uint32_t fz_read_uint32(fz_context *ctx, fz_stream *stm);
228 uint64_t fz_read_uint64(fz_context *ctx, fz_stream *stm);
229
230 uint16_t fz_read_uint16_le(fz_context *ctx, fz_stream *stm);
231 uint32_t fz_read_uint24_le(fz_context *ctx, fz_stream *stm);
232 uint32_t fz_read_uint32_le(fz_context *ctx, fz_stream *stm);
233 uint64_t fz_read_uint64_le(fz_context *ctx, fz_stream *stm);
234
235 int16_t fz_read_int16(fz_context *ctx, fz_stream *stm);
236 int32_t fz_read_int32(fz_context *ctx, fz_stream *stm);
237 int64_t fz_read_int64(fz_context *ctx, fz_stream *stm);
238
239 int16_t fz_read_int16_le(fz_context *ctx, fz_stream *stm);
240 int32_t fz_read_int32_le(fz_context *ctx, fz_stream *stm);
241 int64_t fz_read_int64_le(fz_context *ctx, fz_stream *stm);
242
243 float fz_read_float_le(fz_context *ctx, fz_stream *stm);
244 float fz_read_float(fz_context *ctx, fz_stream *stm);
245
246 /**
247 Read a null terminated string from the stream into
248 a buffer of a given length. The buffer will be null terminated.
249 Throws on failure (including the failure to fit the entire
250 string including the terminator into the buffer).
251 */
252 void fz_read_string(fz_context *ctx, fz_stream *stm, char *buffer, int len);
253
254 /**
255 Read a utf-8 rune from a stream.
256
257 In the event of encountering badly formatted utf-8 codes
258 (such as a leading code with an unexpected number of following
259 codes) no error/exception is given, but undefined values may be
260 returned.
261 */
262 int fz_read_rune(fz_context *ctx, fz_stream *in);
263
264 /**
265 Read a utf-16 rune from a stream. (little endian and
266 big endian respectively).
267
268 In the event of encountering badly formatted utf-16 codes
269 (mismatched surrogates) no error/exception is given, but
270 undefined values may be returned.
271 */
272 int fz_read_utf16_le(fz_context *ctx, fz_stream *stm);
273 int fz_read_utf16_be(fz_context *ctx, fz_stream *stm);
274
275 /**
276 A function type for use when implementing
277 fz_streams. The supplied function of this type is called
278 whenever data is required, and the current buffer is empty.
279
280 stm: The stream to operate on.
281
282 max: a hint as to the maximum number of bytes that the caller
283 needs to be ready immediately. Can safely be ignored.
284
285 Returns -1 if there is no more data in the stream. Otherwise,
286 the function should find its internal state using stm->state,
287 refill its buffer, update stm->rp and stm->wp to point to the
288 start and end of the new data respectively, and then
289 "return *stm->rp++".
290 */
291 typedef int (fz_stream_next_fn)(fz_context *ctx, fz_stream *stm, size_t max);
292
293 /**
294 A function type for use when implementing
295 fz_streams. The supplied function of this type is called
296 when the stream is dropped, to release the stream specific
297 state information.
298
299 state: The stream state to release.
300 */
301 typedef void (fz_stream_drop_fn)(fz_context *ctx, void *state);
302
303 /**
304 A function type for use when implementing
305 fz_streams. The supplied function of this type is called when
306 fz_seek is requested, and the arguments are as defined for
307 fz_seek.
308
309 The stream can find it's private state in stm->state.
310 */
311 typedef void (fz_stream_seek_fn)(fz_context *ctx, fz_stream *stm, int64_t offset, int whence);
312
313 struct fz_stream
314 {
315 int refs;
316 int error;
317 int eof;
318 int progressive;
319 int64_t pos;
320 int avail;
321 int bits;
322 unsigned char *rp, *wp;
323 void *state;
324 fz_stream_next_fn *next;
325 fz_stream_drop_fn *drop;
326 fz_stream_seek_fn *seek;
327 };
328
329 /**
330 Create a new stream object with the given
331 internal state and function pointers.
332
333 state: Internal state (opaque to everything but implementation).
334
335 next: Should provide the next set of bytes (up to max) of stream
336 data. Return the number of bytes read, or EOF when there is no
337 more data.
338
339 drop: Should clean up and free the internal state. May not
340 throw exceptions.
341 */
342 fz_stream *fz_new_stream(fz_context *ctx, void *state, fz_stream_next_fn *next, fz_stream_drop_fn *drop);
343
344 /**
345 Attempt to read a stream into a buffer. If truncated
346 is NULL behaves as fz_read_all, sets a truncated flag in case of
347 error.
348
349 stm: The stream to read from.
350
351 initial: Suggested initial size for the buffer.
352
353 truncated: Flag to store success/failure indication in.
354
355 worst_case: 0 for unknown, otherwise an upper bound for the
356 size of the stream.
357
358 Returns a buffer created from reading from the stream.
359 */
360 fz_buffer *fz_read_best(fz_context *ctx, fz_stream *stm, size_t initial, int *truncated, size_t worst_case);
361
362 /**
363 Read a line from stream into the buffer until either a
364 terminating newline or EOF, which it replaces with a null byte
365 ('\0').
366
367 Returns buf on success, and NULL when end of file occurs while
368 no characters have been read.
369 */
370 char *fz_read_line(fz_context *ctx, fz_stream *stm, char *buf, size_t max);
371
372 /**
373 Skip over a given string in a stream. Return 0 if successfully
374 skipped, non-zero otherwise. As many characters will be skipped
375 over as matched in the string.
376 */
377 int fz_skip_string(fz_context *ctx, fz_stream *stm, const char *str);
378
379 /**
380 Skip over whitespace (bytes <= 32) in a stream.
381 */
382 void fz_skip_space(fz_context *ctx, fz_stream *stm);
383
384 /**
385 Ask how many bytes are available immediately from
386 a given stream.
387
388 stm: The stream to read from.
389
390 max: A hint for the underlying stream; the maximum number of
391 bytes that we are sure we will want to read. If you do not know
392 this number, give 1.
393
394 Returns the number of bytes immediately available between the
395 read and write pointers. This number is guaranteed only to be 0
396 if we have hit EOF. The number of bytes returned here need have
397 no relation to max (could be larger, could be smaller).
398 */
399 static inline size_t fz_available(fz_context *ctx, fz_stream *stm, size_t max)
400 {
401 size_t len = stm->wp - stm->rp;
402 int c = EOF;
403
404 if (len)
405 return len;
406 if (stm->eof)
407 return 0;
408
409 fz_try(ctx)
410 c = stm->next(ctx, stm, max);
411 fz_catch(ctx)
412 {
413 fz_rethrow_if(ctx, FZ_ERROR_TRYLATER);
414 fz_report_error(ctx);
415 fz_warn(ctx, "read error; treating as end of file");
416 stm->error = 1;
417 c = EOF;
418 }
419 if (c == EOF)
420 {
421 stm->eof = 1;
422 return 0;
423 }
424 stm->rp--;
425 return stm->wp - stm->rp;
426 }
427
428 /**
429 Read the next byte from a stream.
430
431 stm: The stream t read from.
432
433 Returns -1 for end of stream, or the next byte. May
434 throw exceptions.
435 */
436 static inline int fz_read_byte(fz_context *ctx, fz_stream *stm)
437 {
438 int c = EOF;
439
440 if (stm->rp != stm->wp)
441 return *stm->rp++;
442 if (stm->eof)
443 return EOF;
444 fz_try(ctx)
445 c = stm->next(ctx, stm, 1);
446 fz_catch(ctx)
447 {
448 fz_rethrow_if(ctx, FZ_ERROR_TRYLATER);
449 fz_report_error(ctx);
450 fz_warn(ctx, "read error; treating as end of file");
451 stm->error = 1;
452 c = EOF;
453 }
454 if (c == EOF)
455 stm->eof = 1;
456 return c;
457 }
458
459 /**
460 Peek at the next byte in a stream.
461
462 stm: The stream to peek at.
463
464 Returns -1 for EOF, or the next byte that will be read.
465 */
466 static inline int fz_peek_byte(fz_context *ctx, fz_stream *stm)
467 {
468 int c = EOF;
469
470 if (stm->rp != stm->wp)
471 return *stm->rp;
472 if (stm->eof)
473 return EOF;
474
475 fz_try(ctx)
476 {
477 c = stm->next(ctx, stm, 1);
478 if (c != EOF)
479 stm->rp--;
480 }
481 fz_catch(ctx)
482 {
483 fz_rethrow_if(ctx, FZ_ERROR_TRYLATER);
484 fz_report_error(ctx);
485 fz_warn(ctx, "read error; treating as end of file");
486 stm->error = 1;
487 c = EOF;
488 }
489 if (c == EOF)
490 stm->eof = 1;
491 return c;
492 }
493
494 /**
495 Unread the single last byte successfully
496 read from a stream. Do not call this without having
497 successfully read a byte.
498
499 stm: The stream to operate upon.
500 */
501 static inline void fz_unread_byte(fz_context *ctx FZ_UNUSED, fz_stream *stm)
502 {
503 stm->rp--;
504 }
505
506 /**
507 Query if the stream has reached EOF (during normal bytewise
508 reading).
509
510 See fz_is_eof_bits for the equivalent function for bitwise
511 reading.
512 */
513 static inline int fz_is_eof(fz_context *ctx, fz_stream *stm)
514 {
515 if (stm->rp == stm->wp)
516 {
517 if (stm->eof)
518 return 1;
519 return fz_peek_byte(ctx, stm) == EOF;
520 }
521 return 0;
522 }
523
524 /**
525 Read the next n bits from a stream (assumed to
526 be packed most significant bit first).
527
528 stm: The stream to read from.
529
530 n: The number of bits to read, between 1 and 8*sizeof(int)
531 inclusive.
532
533 Returns -1 for EOF, or the required number of bits.
534 */
535 static inline unsigned int fz_read_bits(fz_context *ctx, fz_stream *stm, int n)
536 {
537 int x;
538
539 if (n <= stm->avail)
540 {
541 stm->avail -= n;
542 x = (stm->bits >> stm->avail) & ((1 << n) - 1);
543 }
544 else
545 {
546 x = stm->bits & ((1 << stm->avail) - 1);
547 n -= stm->avail;
548 stm->avail = 0;
549
550 while (n > 8)
551 {
552 x = (x << 8) | fz_read_byte(ctx, stm);
553 n -= 8;
554 }
555
556 if (n > 0)
557 {
558 stm->bits = fz_read_byte(ctx, stm);
559 stm->avail = 8 - n;
560 x = (x << n) | (stm->bits >> stm->avail);
561 }
562 }
563
564 return x;
565 }
566
567 /**
568 Read the next n bits from a stream (assumed to
569 be packed least significant bit first).
570
571 stm: The stream to read from.
572
573 n: The number of bits to read, between 1 and 8*sizeof(int)
574 inclusive.
575
576 Returns (unsigned int)-1 for EOF, or the required number of bits.
577 */
578 static inline unsigned int fz_read_rbits(fz_context *ctx, fz_stream *stm, int n)
579 {
580 int x;
581
582 if (n <= stm->avail)
583 {
584 x = stm->bits & ((1 << n) - 1);
585 stm->avail -= n;
586 stm->bits = stm->bits >> n;
587 }
588 else
589 {
590 unsigned int used = 0;
591
592 x = stm->bits & ((1 << stm->avail) - 1);
593 n -= stm->avail;
594 used = stm->avail;
595 stm->avail = 0;
596
597 while (n > 8)
598 {
599 x = (fz_read_byte(ctx, stm) << used) | x;
600 n -= 8;
601 used += 8;
602 }
603
604 if (n > 0)
605 {
606 stm->bits = fz_read_byte(ctx, stm);
607 x = ((stm->bits & ((1 << n) - 1)) << used) | x;
608 stm->avail = 8 - n;
609 stm->bits = stm->bits >> n;
610 }
611 }
612
613 return x;
614 }
615
616 /**
617 Called after reading bits to tell the stream
618 that we are about to return to reading bytewise. Resyncs
619 the stream to whole byte boundaries.
620 */
621 static inline void fz_sync_bits(fz_context *ctx FZ_UNUSED, fz_stream *stm)
622 {
623 stm->avail = 0;
624 }
625
626 /**
627 Query if the stream has reached EOF (during bitwise
628 reading).
629
630 See fz_is_eof for the equivalent function for bytewise
631 reading.
632 */
633 static inline int fz_is_eof_bits(fz_context *ctx, fz_stream *stm)
634 {
635 return fz_is_eof(ctx, stm) && (stm->avail == 0 || stm->bits == EOF);
636 }
637
638 /* Implementation details: subject to change. */
639
640 /**
641 Create a stream from a FILE * that will not be closed
642 when the stream is dropped.
643 */
644 fz_stream *fz_open_file_ptr_no_close(fz_context *ctx, FILE *file);
645
646 #endif