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