1 #ifndef MUPDF_FITZ_OUTPUT_H 2 #define MUPDF_FITZ_OUTPUT_H 3 4 #include "mupdf/fitz/system.h" 5 #include "mupdf/fitz/context.h" 6 #include "mupdf/fitz/buffer.h" 7 #include "mupdf/fitz/string-util.h" 8 #include "mupdf/fitz/stream.h" 9 10 /** 11 Generic output streams - generalise between outputting to a 12 file, a buffer, etc. 13 */ 14 15 /** 16 A function type for use when implementing 17 fz_outputs. The supplied function of this type is called 18 whenever data is written to the output. 19 20 state: The state for the output stream. 21 22 data: a pointer to a buffer of data to write. 23 24 n: The number of bytes of data to write. 25 */ 26 typedef void (fz_output_write_fn)(fz_context *ctx, void *state, const void *data, size_t n); 27 28 /** 29 A function type for use when implementing 30 fz_outputs. The supplied function of this type is called when 31 fz_seek_output is requested. 32 33 state: The output stream state to seek within. 34 35 offset, whence: as defined for fs_seek_output. 36 */ 37 typedef void (fz_output_seek_fn)(fz_context *ctx, void *state, int64_t offset, int whence); 38 39 /** 40 A function type for use when implementing 41 fz_outputs. The supplied function of this type is called when 42 fz_tell_output is requested. 43 44 state: The output stream state to report on. 45 46 Returns the offset within the output stream. 47 */ 48 typedef int64_t (fz_output_tell_fn)(fz_context *ctx, void *state); 49 50 /** 51 A function type for use when implementing 52 fz_outputs. The supplied function of this type is called 53 when the output stream is closed, to flush any pending writes. 54 */ 55 typedef void (fz_output_close_fn)(fz_context *ctx, void *state); 56 57 /** 58 A function type for use when implementing 59 fz_outputs. The supplied function of this type is called 60 when the output stream is dropped, to release the stream 61 specific state information. 62 */ 63 typedef void (fz_output_drop_fn)(fz_context *ctx, void *state); 64 65 /** 66 A function type for use when implementing 67 fz_outputs. The supplied function of this type is called 68 when the fz_stream_from_output is called. 69 */ 70 typedef fz_stream *(fz_stream_from_output_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 fz_truncate_output is called to truncate the file 76 at that point. 77 */ 78 typedef void (fz_truncate_fn)(fz_context *ctx, void *state); 79 80 typedef struct 81 { 82 void *state; 83 fz_output_write_fn *write; 84 fz_output_seek_fn *seek; 85 fz_output_tell_fn *tell; 86 fz_output_close_fn *close; 87 fz_output_drop_fn *drop; 88 fz_stream_from_output_fn *as_stream; 89 fz_truncate_fn *truncate; 90 char *bp, *wp, *ep; 91 } fz_output; 92 93 /** 94 Create a new output object with the given 95 internal state and function pointers. 96 97 state: Internal state (opaque to everything but implementation). 98 99 write: Function to output a given buffer. 100 101 close: Cleanup function to destroy state when output closed. 102 May permissibly be null. 103 */ 104 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); 105 106 /** 107 Open an output stream that writes to a 108 given path. 109 110 filename: The filename to write to (specified in UTF-8). 111 112 append: non-zero if we should append to the file, rather than 113 overwriting it. 114 */ 115 fz_output *fz_new_output_with_path(fz_context *, const char *filename, int append); 116 117 /** 118 Open an output stream that appends 119 to a buffer. 120 121 buf: The buffer to append to. 122 */ 123 fz_output *fz_new_output_with_buffer(fz_context *ctx, fz_buffer *buf); 124 125 /** 126 Retrieve an fz_output that directs to stdout. 127 128 Should be fz_dropped when finished with. 129 */ 130 fz_output *fz_stdout(fz_context *ctx); 131 132 /** 133 Retrieve an fz_output that directs to stdout. 134 135 Should be fz_dropped when finished with. 136 */ 137 fz_output *fz_stderr(fz_context *ctx); 138 139 /** 140 Format and write data to an output stream. 141 See fz_format_string for formatting details. 142 */ 143 void fz_write_printf(fz_context *ctx, fz_output *out, const char *fmt, ...); 144 145 /** 146 va_list version of fz_write_printf. 147 */ 148 void fz_write_vprintf(fz_context *ctx, fz_output *out, const char *fmt, va_list ap); 149 150 /** 151 Seek to the specified file position. 152 See fseek for arguments. 153 154 Throw an error on unseekable outputs. 155 */ 156 void fz_seek_output(fz_context *ctx, fz_output *out, int64_t off, int whence); 157 158 /** 159 Return the current file position. 160 161 Throw an error on untellable outputs. 162 */ 163 int64_t fz_tell_output(fz_context *ctx, fz_output *out); 164 165 /** 166 Flush unwritten data. 167 */ 168 void fz_flush_output(fz_context *ctx, fz_output *out); 169 170 /** 171 Flush pending output and close an output stream. 172 */ 173 void fz_close_output(fz_context *, fz_output *); 174 175 /** 176 Free an output stream. Don't forget to close it first! 177 */ 178 void fz_drop_output(fz_context *, fz_output *); 179 180 /** 181 Query whether a given fz_output supports fz_stream_from_output. 182 */ 183 int fz_output_supports_stream(fz_context *ctx, fz_output *out); 184 185 /** 186 Obtain the fz_output in the form of a fz_stream. 187 188 This allows data to be read back from some forms of fz_output 189 object. When finished reading, the fz_stream should be released 190 by calling fz_drop_stream. Until the fz_stream is dropped, no 191 further operations should be performed on the fz_output object. 192 */ 193 fz_stream *fz_stream_from_output(fz_context *, fz_output *); 194 195 /** 196 Truncate the output at the current position. 197 198 This allows output streams which have seeked back from the end 199 of their storage to be truncated at the current point. 200 */ 201 void fz_truncate_output(fz_context *, fz_output *); 202 203 /** 204 Write data to output. 205 206 data: Pointer to data to write. 207 size: Size of data to write in bytes. 208 */ 209 void fz_write_data(fz_context *ctx, fz_output *out, const void *data, size_t size); 210 211 /** 212 Write a string. Does not write zero terminator. 213 */ 214 void fz_write_string(fz_context *ctx, fz_output *out, const char *s); 215 216 /** 217 Write different sized data to an output stream. 218 */ 219 void fz_write_int32_be(fz_context *ctx, fz_output *out, int x); 220 void fz_write_int32_le(fz_context *ctx, fz_output *out, int x); 221 void fz_write_uint32_be(fz_context *ctx, fz_output *out, unsigned int x); 222 void fz_write_uint32_le(fz_context *ctx, fz_output *out, unsigned int x); 223 void fz_write_int16_be(fz_context *ctx, fz_output *out, int x); 224 void fz_write_int16_le(fz_context *ctx, fz_output *out, int x); 225 void fz_write_uint16_be(fz_context *ctx, fz_output *out, unsigned int x); 226 void fz_write_uint16_le(fz_context *ctx, fz_output *out, unsigned int x); 227 void fz_write_char(fz_context *ctx, fz_output *out, char x); 228 void fz_write_byte(fz_context *ctx, fz_output *out, unsigned char x); 229 void fz_write_float_be(fz_context *ctx, fz_output *out, float f); 230 void fz_write_float_le(fz_context *ctx, fz_output *out, float f); 231 232 /** 233 Write a UTF-8 encoded unicode character. 234 */ 235 void fz_write_rune(fz_context *ctx, fz_output *out, int rune); 236 237 /** 238 Write a base64 encoded data block, optionally with periodic 239 newlines. 240 */ 241 void fz_write_base64(fz_context *ctx, fz_output *out, const unsigned char *data, size_t size, int newline); 242 243 /** 244 Write a base64 encoded fz_buffer, optionally with periodic 245 newlines. 246 */ 247 void fz_write_base64_buffer(fz_context *ctx, fz_output *out, fz_buffer *data, int newline); 248 249 /** 250 Our customised 'printf'-like string formatter. 251 Takes %c, %d, %s, %u, %x, as usual. 252 Modifiers are not supported except for zero-padding ints (e.g. 253 %02d, %03u, %04x, etc). 254 %g output in "as short as possible hopefully lossless 255 non-exponent" form, see fz_ftoa for specifics. 256 %f and %e output as usual. 257 %C outputs a utf8 encoded int. 258 %M outputs a fz_matrix*. 259 %R outputs a fz_rect*. 260 %P outputs a fz_point*. 261 %n outputs a PDF name (with appropriate escaping). 262 %q and %( output escaped strings in C/PDF syntax. 263 %l{d,u,x} indicates that the values are int64_t. 264 %z{d,u,x} indicates that the value is a size_t. 265 266 user: An opaque pointer that is passed to the emit function. 267 268 emit: A function pointer called to emit output bytes as the 269 string is being formatted. 270 */ 271 void fz_format_string(fz_context *ctx, void *user, void (*emit)(fz_context *ctx, void *user, int c), const char *fmt, va_list args); 272 273 /** 274 A vsnprintf work-alike, using our custom formatter. 275 */ 276 size_t fz_vsnprintf(char *buffer, size_t space, const char *fmt, va_list args); 277 278 /** 279 The non va_list equivalent of fz_vsnprintf. 280 */ 281 size_t fz_snprintf(char *buffer, size_t space, const char *fmt, ...); 282 283 /** 284 Allocated sprintf. 285 286 Returns a null terminated allocated block containing the 287 formatted version of the format string/args. 288 */ 289 char *fz_asprintf(fz_context *ctx, const char *fmt, ...); 290 291 /** 292 Save the contents of a buffer to a file. 293 */ 294 void fz_save_buffer(fz_context *ctx, fz_buffer *buf, const char *filename); 295 296 /** 297 Compression and other filtering outputs. 298 299 These outputs write encoded data to another output. Create a 300 filter output with the destination, write to the filter, then 301 close and drop it when you're done. These can also be chained 302 together, for example to write ASCII Hex encoded, Deflate 303 compressed, and RC4 encrypted data to a buffer output. 304 305 Output streams don't use reference counting, so make sure to 306 close all of the filters in the reverse order of creation so 307 that data is flushed properly. 308 309 Accordingly, ownership of 'chain' is never passed into the 310 following functions, but remains with the caller, whose 311 responsibility it is to ensure they exist at least until 312 the returned fz_output is dropped. 313 */ 314 315 fz_output *fz_new_asciihex_output(fz_context *ctx, fz_output *chain); 316 fz_output *fz_new_ascii85_output(fz_context *ctx, fz_output *chain); 317 fz_output *fz_new_rle_output(fz_context *ctx, fz_output *chain); 318 fz_output *fz_new_arc4_output(fz_context *ctx, fz_output *chain, unsigned char *key, size_t keylen); 319 fz_output *fz_new_deflate_output(fz_context *ctx, fz_output *chain, int effort, int raw); 320 321 #endif 322