Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/output.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-2025 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_OUTPUT_H
24 #define MUPDF_FITZ_OUTPUT_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/context.h"
28 #include "mupdf/fitz/buffer.h"
29 #include "mupdf/fitz/string-util.h"
30 #include "mupdf/fitz/stream.h"
31
32 /**
33 Generic output streams - generalise between outputting to a
34 file, a buffer, etc.
35 */
36
37 /**
38 A function type for use when implementing
39 fz_outputs. The supplied function of this type is called
40 whenever data is written to the output.
41
42 state: The state for the output stream.
43
44 data: a pointer to a buffer of data to write.
45
46 n: The number of bytes of data to write.
47 */
48 typedef void (fz_output_write_fn)(fz_context *ctx, void *state, const void *data, size_t n);
49
50 /**
51 A function type for use when implementing
52 fz_outputs. The supplied function of this type is called when
53 fz_seek_output is requested.
54
55 state: The output stream state to seek within.
56
57 offset, whence: as defined for fz_seek().
58 */
59 typedef void (fz_output_seek_fn)(fz_context *ctx, void *state, int64_t offset, int whence);
60
61 /**
62 A function type for use when implementing
63 fz_outputs. The supplied function of this type is called when
64 fz_tell_output is requested.
65
66 state: The output stream state to report on.
67
68 Returns the offset within the output stream.
69 */
70 typedef int64_t (fz_output_tell_fn)(fz_context *ctx, void *state);
71
72 /**
73 A function type for use when implementing
74 fz_outputs. The supplied function of this type is called
75 when the output stream is closed, to flush any pending writes.
76 */
77 typedef void (fz_output_close_fn)(fz_context *ctx, void *state);
78
79 /**
80 A function type for use when implementing
81 fz_outputs. The supplied function of this type is called
82 when the output stream is reset, and resets the state
83 to that when it was first initialised.
84 */
85 typedef void (fz_output_reset_fn)(fz_context *ctx, void *state);
86
87 /**
88 A function type for use when implementing
89 fz_outputs. The supplied function of this type is called
90 when the output stream is dropped, to release the stream
91 specific state information.
92 */
93 typedef void (fz_output_drop_fn)(fz_context *ctx, void *state);
94
95 /**
96 A function type for use when implementing
97 fz_outputs. The supplied function of this type is called
98 when the fz_stream_from_output is called.
99 */
100 typedef fz_stream *(fz_stream_from_output_fn)(fz_context *ctx, void *state);
101
102 /**
103 A function type for use when implementing
104 fz_outputs. The supplied function of this type is called
105 when fz_truncate_output is called to truncate the file
106 at that point.
107 */
108 typedef void (fz_truncate_fn)(fz_context *ctx, void *state);
109
110 struct fz_output
111 {
112 void *state;
113 fz_output_write_fn *write;
114 fz_output_seek_fn *seek;
115 fz_output_tell_fn *tell;
116 fz_output_close_fn *close;
117 fz_output_drop_fn *drop;
118 fz_output_reset_fn *reset;
119 fz_stream_from_output_fn *as_stream;
120 fz_truncate_fn *truncate;
121 int closed;
122 char *bp, *wp, *ep;
123 /* If buffered is non-zero, then we have that many
124 * bits (1-7) waiting to be written in bits. */
125 int buffered;
126 int bits;
127 };
128
129 /**
130 Create a new output object with the given
131 internal state and function pointers.
132
133 state: Internal state (opaque to everything but implementation).
134
135 write: Function to output a given buffer.
136
137 close: Cleanup function to destroy state when output closed.
138 May permissibly be null.
139 */
140 fz_output *fz_new_output(fz_context *ctx, int bufsiz, void *state, fz_output_write_fn *write, fz_output_close_fn *close, fz_output_drop_fn *drop);
141
142 /**
143 Open an output stream that writes to a
144 given path.
145
146 filename: The filename to write to (specified in UTF-8).
147
148 append: non-zero if we should append to the file, rather than
149 overwriting it.
150 */
151 fz_output *fz_new_output_with_path(fz_context *, const char *filename, int append);
152
153 /**
154 Open an output stream that writes to a
155 given FILE *.
156
157 file: The file pointers to write to. NULL is interpreted as effectively
158 meaning /dev/null or similar.
159 */
160 fz_output *fz_new_output_with_file_ptr(fz_context *ctx, FILE *file);
161
162 /**
163 Open an output stream that appends
164 to a buffer.
165
166 buf: The buffer to append to.
167 */
168 fz_output *fz_new_output_with_buffer(fz_context *ctx, fz_buffer *buf);
169
170 /**
171 Retrieve an fz_output that directs to stdout.
172
173 Optionally may be fz_dropped when finished with.
174 */
175 fz_output *fz_stdout(fz_context *ctx);
176
177 /**
178 Retrieve an fz_output that directs to stdout.
179
180 Optionally may be fz_dropped when finished with.
181 */
182 fz_output *fz_stderr(fz_context *ctx);
183
184 #ifdef _WIN32
185 /**
186 Retrieve an fz_output that directs to OutputDebugString.
187
188 Optionally may be fz_dropped when finished with.
189 */
190 fz_output *fz_stdods(fz_context *ctx);
191 #endif
192
193 /**
194 Set the output stream to be used for fz_stddbg. Set to NULL to
195 reset to default (stderr).
196 */
197 void fz_set_stddbg(fz_context *ctx, fz_output *out);
198
199 /**
200 Retrieve an fz_output for the default debugging stream. On
201 Windows this will be OutputDebugString for non-console apps.
202 Otherwise, it is always fz_stderr.
203
204 Optionally may be fz_dropped when finished with.
205 */
206 fz_output *fz_stddbg(fz_context *ctx);
207
208 /**
209 Format and write data to an output stream.
210 See fz_format_string for formatting details.
211 */
212 void fz_write_printf(fz_context *ctx, fz_output *out, const char *fmt, ...);
213
214 /**
215 va_list version of fz_write_printf.
216 */
217 void fz_write_vprintf(fz_context *ctx, fz_output *out, const char *fmt, va_list ap);
218
219 /**
220 Seek to the specified file position.
221 See fseek for arguments.
222
223 Throw an error on unseekable outputs.
224 */
225 void fz_seek_output(fz_context *ctx, fz_output *out, int64_t off, int whence);
226
227 /**
228 Return the current file position.
229
230 Throw an error on untellable outputs.
231 */
232 int64_t fz_tell_output(fz_context *ctx, fz_output *out);
233
234 /**
235 Flush unwritten data.
236 */
237 void fz_flush_output(fz_context *ctx, fz_output *out);
238
239 /**
240 Flush pending output and close an output stream.
241 */
242 void fz_close_output(fz_context *, fz_output *);
243
244 /**
245 Reset a closed output stream. Returns state to
246 (broadly) that which it was in when opened. Not
247 all outputs can be reset, so this may throw an
248 exception.
249 */
250 void fz_reset_output(fz_context *, fz_output *);
251
252 /**
253 Free an output stream. Don't forget to close it first!
254 */
255 void fz_drop_output(fz_context *, fz_output *);
256
257 /**
258 Query whether a given fz_output supports fz_stream_from_output.
259 */
260 int fz_output_supports_stream(fz_context *ctx, fz_output *out);
261
262 /**
263 Obtain the fz_output in the form of a fz_stream.
264
265 This allows data to be read back from some forms of fz_output
266 object. When finished reading, the fz_stream should be released
267 by calling fz_drop_stream. Until the fz_stream is dropped, no
268 further operations should be performed on the fz_output object.
269 */
270 fz_stream *fz_stream_from_output(fz_context *, fz_output *);
271
272 /**
273 Truncate the output at the current position.
274
275 This allows output streams which have seeked back from the end
276 of their storage to be truncated at the current point.
277 */
278 void fz_truncate_output(fz_context *, fz_output *);
279
280 /**
281 Write data to output.
282
283 data: Pointer to data to write.
284 size: Size of data to write in bytes.
285 */
286 void fz_write_data(fz_context *ctx, fz_output *out, const void *data, size_t size);
287 void fz_write_buffer(fz_context *ctx, fz_output *out, fz_buffer *data);
288
289 /**
290 Write a string. Does not write zero terminator.
291 */
292 void fz_write_string(fz_context *ctx, fz_output *out, const char *s);
293
294 /**
295 Write different sized data to an output stream.
296 */
297 void fz_write_int32_be(fz_context *ctx, fz_output *out, int x);
298 void fz_write_int32_le(fz_context *ctx, fz_output *out, int x);
299 void fz_write_uint32_be(fz_context *ctx, fz_output *out, unsigned int x);
300 void fz_write_uint32_le(fz_context *ctx, fz_output *out, unsigned int x);
301 void fz_write_int16_be(fz_context *ctx, fz_output *out, int x);
302 void fz_write_int16_le(fz_context *ctx, fz_output *out, int x);
303 void fz_write_uint16_be(fz_context *ctx, fz_output *out, unsigned int x);
304 void fz_write_uint16_le(fz_context *ctx, fz_output *out, unsigned int x);
305 void fz_write_char(fz_context *ctx, fz_output *out, char x);
306 void fz_write_byte(fz_context *ctx, fz_output *out, unsigned char x);
307 void fz_write_float_be(fz_context *ctx, fz_output *out, float f);
308 void fz_write_float_le(fz_context *ctx, fz_output *out, float f);
309
310 /**
311 Write a UTF-8 encoded unicode character.
312 */
313 void fz_write_rune(fz_context *ctx, fz_output *out, int rune);
314
315 /**
316 Write a base64 encoded data block, optionally with periodic
317 newlines.
318 */
319 void fz_write_base64(fz_context *ctx, fz_output *out, const unsigned char *data, size_t size, int newline);
320
321 /**
322 Write a base64 encoded fz_buffer, optionally with periodic
323 newlines.
324 */
325 void fz_write_base64_buffer(fz_context *ctx, fz_output *out, fz_buffer *data, int newline);
326
327 /**
328 Write num_bits of data to the end of the output stream, assumed to be packed
329 most significant bits first.
330 */
331 void fz_write_bits(fz_context *ctx, fz_output *out, unsigned int data, int num_bits);
332
333 /**
334 Sync to byte boundary after writing bits.
335 */
336 void fz_write_bits_sync(fz_context *ctx, fz_output *out);
337
338 /**
339 Copy the stream contents to the output.
340 */
341 void fz_write_stream(fz_context *ctx, fz_output *out, fz_stream *in);
342
343 /**
344 Our customised 'printf'-like string formatter.
345 Takes %c, %d, %s, %u, %x, %X as usual.
346 The only modifiers supported are:
347 1) zero-padding ints (e.g. %02d, %03u, %04x, etc).
348 2) ' to indicate that ' should be inserted into
349 integers as thousands separators.
350 3) , to indicate that , should be inserted into
351 integers as thousands separators.
352 4) _ to indicate that , should be inserted into
353 integers as thousands separators.
354 Posix chooses the thousand separator in a locale
355 specific way - we do not. We always apply it every
356 3 characters for the positive part of integers, so
357 other styles, such as Indian (123,456,78) are not
358 supported.
359
360 %g output in "as short as possible hopefully lossless
361 non-exponent" form, see fz_ftoa for specifics.
362 %f and %e output as usual.
363 %C outputs a utf8 encoded int.
364 %M outputs a fz_matrix*.
365 %R outputs a fz_rect*.
366 %P outputs a fz_point*.
367 %n outputs a PDF name (with appropriate escaping).
368 %q and %( output escaped strings in C/PDF syntax.
369 %l{d,u,x,X} indicates that the values are int64_t.
370 %z{d,u,x,X} indicates that the value is a size_t.
371 %< outputs a quoted (utf8) string (for XML).
372 %> outputs a hex string for a zero terminated string of bytes.
373
374 user: An opaque pointer that is passed to the emit function.
375
376 emit: A function pointer called to emit output bytes as the
377 string is being formatted.
378 */
379 void fz_format_string(fz_context *ctx, void *user, void (*emit)(fz_context *ctx, void *user, int c), const char *fmt, va_list args);
380
381 /**
382 A vsnprintf work-alike, using our custom formatter.
383 */
384 size_t fz_vsnprintf(char *buffer, size_t space, const char *fmt, va_list args);
385
386 /**
387 The non va_list equivalent of fz_vsnprintf.
388 */
389 size_t fz_snprintf(char *buffer, size_t space, const char *fmt, ...);
390
391 /**
392 Allocated sprintf.
393
394 Returns a null terminated allocated block containing the
395 formatted version of the format string/args.
396 */
397 char *fz_asprintf(fz_context *ctx, const char *fmt, ...);
398
399 /**
400 Save the contents of a buffer to a file.
401 */
402 void fz_save_buffer(fz_context *ctx, fz_buffer *buf, const char *filename);
403
404 /**
405 Compression and other filtering outputs.
406
407 These outputs write encoded data to another output. Create a
408 filter output with the destination, write to the filter, then
409 close and drop it when you're done. These can also be chained
410 together, for example to write ASCII Hex encoded, Deflate
411 compressed, and RC4 encrypted data to a buffer output.
412
413 Output streams don't use reference counting, so make sure to
414 close all of the filters in the reverse order of creation so
415 that data is flushed properly.
416
417 Accordingly, ownership of 'chain' is never passed into the
418 following functions, but remains with the caller, whose
419 responsibility it is to ensure they exist at least until
420 the returned fz_output is dropped.
421 */
422
423 fz_output *fz_new_asciihex_output(fz_context *ctx, fz_output *chain);
424 fz_output *fz_new_ascii85_output(fz_context *ctx, fz_output *chain);
425 fz_output *fz_new_rle_output(fz_context *ctx, fz_output *chain);
426 fz_output *fz_new_arc4_output(fz_context *ctx, fz_output *chain, unsigned char *key, size_t keylen);
427 fz_output *fz_new_deflate_output(fz_context *ctx, fz_output *chain, int effort, int raw);
428
429 /*
430 Return whether a char is representable in an XML string.
431 */
432 int fz_is_valid_xml_char(int c);
433
434 /*
435 Return a char mapped into the ranges representable by XML.
436 Any unrepresentable char becomes the unicode replacement
437 char (0xFFFD).
438 */
439 int
440 fz_range_limit_xml_char(int c);
441
442 /*
443 Return true if all the utf-8 encoded characters in the
444 string are representable within XML.
445 */
446 int fz_is_valid_xml_string(const char *s);
447
448 #endif