output.h File Reference

#include "mupdf/fitz/system.h"
#include "mupdf/fitz/context.h"
#include "mupdf/fitz/buffer.h"
#include "mupdf/fitz/string-util.h"
#include "mupdf/fitz/stream.h"

Include dependency graph for output.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fz_output

Typedefs
typedef void	fz_output_write_fn(fz_context *ctx, void *state, const void *data, size_t n)
typedef void	fz_output_seek_fn(fz_context *ctx, void *state, int64_t offset, int whence)
typedef int64_t	fz_output_tell_fn(fz_context *ctx, void *state)
typedef void	fz_output_close_fn(fz_context *ctx, void *state)
typedef void	fz_output_reset_fn(fz_context *ctx, void *state)
typedef void	fz_output_drop_fn(fz_context *ctx, void *state)
typedef fz_stream *	fz_stream_from_output_fn(fz_context *ctx, void *state)
typedef void	fz_truncate_fn(fz_context *ctx, void *state)

Functions
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)
fz_output *	fz_new_output_with_path (fz_context *, const char *filename, int append)
fz_output *	fz_new_output_with_file_ptr (fz_context *ctx, FILE *file)
fz_output *	fz_new_output_with_buffer (fz_context *ctx, fz_buffer *buf)
fz_output *	fz_stdout (fz_context *ctx)
fz_output *	fz_stderr (fz_context *ctx)
void	fz_set_stddbg (fz_context *ctx, fz_output *out)
fz_output *	fz_stddbg (fz_context *ctx)
void	fz_write_printf (fz_context *ctx, fz_output *out, const char *fmt,...)
void	fz_write_vprintf (fz_context *ctx, fz_output *out, const char *fmt, va_list ap)
void	fz_seek_output (fz_context *ctx, fz_output *out, int64_t off, int whence)
int64_t	fz_tell_output (fz_context *ctx, fz_output *out)
void	fz_flush_output (fz_context *ctx, fz_output *out)
void	fz_close_output (fz_context *, fz_output *)
void	fz_reset_output (fz_context *, fz_output *)
void	fz_drop_output (fz_context *, fz_output *)
int	fz_output_supports_stream (fz_context *ctx, fz_output *out)
fz_stream *	fz_stream_from_output (fz_context *, fz_output *)
void	fz_truncate_output (fz_context *, fz_output *)
void	fz_write_data (fz_context *ctx, fz_output *out, const void *data, size_t size)
void	fz_write_buffer (fz_context *ctx, fz_output *out, fz_buffer *data)
void	fz_write_string (fz_context *ctx, fz_output *out, const char *s)
void	fz_write_int32_be (fz_context *ctx, fz_output *out, int x)
void	fz_write_int32_le (fz_context *ctx, fz_output *out, int x)
void	fz_write_uint32_be (fz_context *ctx, fz_output *out, unsigned int x)
void	fz_write_uint32_le (fz_context *ctx, fz_output *out, unsigned int x)
void	fz_write_int16_be (fz_context *ctx, fz_output *out, int x)
void	fz_write_int16_le (fz_context *ctx, fz_output *out, int x)
void	fz_write_uint16_be (fz_context *ctx, fz_output *out, unsigned int x)
void	fz_write_uint16_le (fz_context *ctx, fz_output *out, unsigned int x)
void	fz_write_char (fz_context *ctx, fz_output *out, char x)
void	fz_write_byte (fz_context *ctx, fz_output *out, unsigned char x)
void	fz_write_float_be (fz_context *ctx, fz_output *out, float f)
void	fz_write_float_le (fz_context *ctx, fz_output *out, float f)
void	fz_write_rune (fz_context *ctx, fz_output *out, int rune)
void	fz_write_base64 (fz_context *ctx, fz_output *out, const unsigned char *data, size_t size, int newline)
void	fz_write_base64_buffer (fz_context *ctx, fz_output *out, fz_buffer *data, int newline)
void	fz_write_bits (fz_context *ctx, fz_output *out, unsigned int data, int num_bits)
void	fz_write_bits_sync (fz_context *ctx, fz_output *out)
void	fz_write_stream (fz_context *ctx, fz_output *out, fz_stream *in)
void	fz_format_string (fz_context *ctx, void *user, void(*emit)(fz_context *ctx, void *user, int c), const char *fmt, va_list args)
size_t	fz_vsnprintf (char *buffer, size_t space, const char *fmt, va_list args)
size_t	fz_snprintf (char *buffer, size_t space, const char *fmt,...)
char *	fz_asprintf (fz_context *ctx, const char *fmt,...)
void	fz_save_buffer (fz_context *ctx, fz_buffer *buf, const char *filename)
fz_output *	fz_new_asciihex_output (fz_context *ctx, fz_output *chain)
fz_output *	fz_new_ascii85_output (fz_context *ctx, fz_output *chain)
fz_output *	fz_new_rle_output (fz_context *ctx, fz_output *chain)
fz_output *	fz_new_arc4_output (fz_context *ctx, fz_output *chain, unsigned char *key, size_t keylen)
fz_output *	fz_new_deflate_output (fz_context *ctx, fz_output *chain, int effort, int raw)
int	fz_is_valid_xml_char (int c)
int	fz_range_limit_xml_char (int c)
int	fz_is_valid_xml_string (const char *s)

Typedef Documentation

fz_output_close_fn

typedef void fz_output_close_fn(fz_context *ctx, void *state)

A function type for use when implementing fz_outputs. The supplied function of this type is called when the output stream is closed, to flush any pending writes.

fz_output_drop_fn

typedef void fz_output_drop_fn(fz_context *ctx, void *state)

A function type for use when implementing fz_outputs. The supplied function of this type is called when the output stream is dropped, to release the stream specific state information.

fz_output_reset_fn

typedef void fz_output_reset_fn(fz_context *ctx, void *state)

A function type for use when implementing fz_outputs. The supplied function of this type is called when the output stream is reset, and resets the state to that when it was first initialised.

fz_output_seek_fn

typedef void fz_output_seek_fn(fz_context *ctx, void *state, int64_t offset, int whence)

A function type for use when implementing fz_outputs. The supplied function of this type is called when fz_seek_output is requested.

state: The output stream state to seek within.

offset, whence: as defined for fz_seek().

fz_output_tell_fn

typedef int64_t fz_output_tell_fn(fz_context *ctx, void *state)

A function type for use when implementing fz_outputs. The supplied function of this type is called when fz_tell_output is requested.

state: The output stream state to report on.

Returns the offset within the output stream.

fz_output_write_fn

typedef void fz_output_write_fn(fz_context *ctx, void *state, const void *data, size_t n)

Generic output streams - generalise between outputting to a file, a buffer, etc. A function type for use when implementing fz_outputs. The supplied function of this type is called whenever data is written to the output.

state: The state for the output stream.

data: a pointer to a buffer of data to write.

n: The number of bytes of data to write.

fz_stream_from_output_fn

typedef fz_stream * fz_stream_from_output_fn(fz_context *ctx, void *state)

A function type for use when implementing fz_outputs. The supplied function of this type is called when the fz_stream_from_output is called.

fz_truncate_fn

typedef void fz_truncate_fn(fz_context *ctx, void *state)

A function type for use when implementing fz_outputs. The supplied function of this type is called when fz_truncate_output is called to truncate the file at that point.

Function Documentation

fz_asprintf()

char * fz_asprintf	(	fz_context *	ctx,
		const char *	fmt,
			... )

Allocated sprintf.

Returns a null terminated allocated block containing the formatted version of the format string/args.

fz_close_output()

void fz_close_output	(	fz_context *	,
		fz_output *	)

Flush pending output and close an output stream.

fz_drop_output()

void fz_drop_output	(	fz_context *	,
		fz_output *	)

Free an output stream. Don't forget to close it first!

fz_flush_output()

void fz_flush_output	(	fz_context *	ctx,
		fz_output *	out )

Flush unwritten data.

fz_format_string()

void fz_format_string	(	fz_context *	ctx,
		void *	user,
		void(*	emit )(fz_context *ctx, void *user, int c),
		const char *	fmt,
		va_list	args )

Our customised 'printf'-like string formatter. Takes c, d, s, u, x, X as usual. The only modifiers supported are: 1) zero-padding ints (e.g. %02d, %03u, %04x, etc). 2) ' to indicate that ' should be inserted into integers as thousands separators. 3) , to indicate that , should be inserted into integers as thousands separators. 4) _ to indicate that , should be inserted into integers as thousands separators. Posix chooses the thousand separator in a locale specific way - we do not. We always apply it every 3 characters for the positive part of integers, so other styles, such as Indian (123,456,78) are not supported.

g output in "as short as possible hopefully lossless non-exponent" form, see fz_ftoa for specifics. f and e output as usual. C outputs a utf8 encoded int. M outputs a fz_matrix*. R outputs a fz_rect*. P outputs a fz_point*. n outputs a PDF name (with appropriate escaping). q and %( output escaped strings in C/PDF syntax. l{d,u,x,X} indicates that the values are int64_t. z{d,u,x,X} indicates that the value is a size_t. %< outputs a quoted (utf8) string (for XML). %> outputs a hex string for a zero terminated string of bytes.

user: An opaque pointer that is passed to the emit function.

emit: A function pointer called to emit output bytes as the string is being formatted.

fz_is_valid_xml_char()

int fz_is_valid_xml_char

(

int

c

)

fz_is_valid_xml_string()

int fz_is_valid_xml_string

(

const char *

s

)

fz_new_arc4_output()

fz_output * fz_new_arc4_output	(	fz_context *	ctx,
		fz_output *	chain,
		unsigned char *	key,
		size_t	keylen )

fz_new_ascii85_output()

fz_output * fz_new_ascii85_output	(	fz_context *	ctx,
		fz_output *	chain )

fz_new_asciihex_output()

fz_output * fz_new_asciihex_output	(	fz_context *	ctx,
		fz_output *	chain )

Compression and other filtering outputs.

These outputs write encoded data to another output. Create a filter output with the destination, write to the filter, then close and drop it when you're done. These can also be chained together, for example to write ASCII Hex encoded, Deflate compressed, and RC4 encrypted data to a buffer output.

Output streams don't use reference counting, so make sure to close all of the filters in the reverse order of creation so that data is flushed properly.

Accordingly, ownership of 'chain' is never passed into the following functions, but remains with the caller, whose responsibility it is to ensure they exist at least until the returned fz_output is dropped.

fz_new_deflate_output()

fz_output * fz_new_deflate_output	(	fz_context *	ctx,
		fz_output *	chain,
		int	effort,
		int	raw )

fz_new_output()

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 )

Create a new output object with the given internal state and function pointers.

state: Internal state (opaque to everything but implementation).

write: Function to output a given buffer.

close: Cleanup function to destroy state when output closed. May permissibly be null.

fz_new_output_with_buffer()

fz_output * fz_new_output_with_buffer	(	fz_context *	ctx,
		fz_buffer *	buf )

Open an output stream that appends to a buffer.

buf: The buffer to append to.

fz_new_output_with_file_ptr()

fz_output * fz_new_output_with_file_ptr	(	fz_context *	ctx,
		FILE *	file )

Open an output stream that writes to a given FILE *.

file: The file pointers to write to. NULL is interpreted as effectively meaning /dev/null or similar.

fz_new_output_with_path()

fz_output * fz_new_output_with_path	(	fz_context *	,
		const char *	filename,
		int	append )

Open an output stream that writes to a given path. This stream will always be a binary stream.

On Windows, if this stream is stdout or stderr, these will be set to binary.

filename: The filename to write to (specified in UTF-8).

append: non-zero if we should append to the file, rather than overwriting it.

fz_new_rle_output()

fz_output * fz_new_rle_output	(	fz_context *	ctx,
		fz_output *	chain )

fz_output_supports_stream()

int fz_output_supports_stream	(	fz_context *	ctx,
		fz_output *	out )

Query whether a given fz_output supports fz_stream_from_output.

fz_range_limit_xml_char()

int fz_range_limit_xml_char

(

int

c

)

fz_reset_output()

void fz_reset_output	(	fz_context *	,
		fz_output *	)

Reset a closed output stream. Returns state to (broadly) that which it was in when opened. Not all outputs can be reset, so this may throw an exception.

fz_save_buffer()

void fz_save_buffer	(	fz_context *	ctx,
		fz_buffer *	buf,
		const char *	filename )

Save the contents of a buffer to a file.

fz_seek_output()

void fz_seek_output	(	fz_context *	ctx,
		fz_output *	out,
		int64_t	off,
		int	whence )

Seek to the specified file position. See fseek for arguments.

Throw an error on unseekable outputs.

fz_set_stddbg()

void fz_set_stddbg	(	fz_context *	ctx,
		fz_output *	out )

Set the output stream to be used for fz_stddbg. Set to NULL to reset to default (stderr).

fz_snprintf()

size_t fz_snprintf	(	char *	buffer,
		size_t	space,
		const char *	fmt,
			... )

The non va_list equivalent of fz_vsnprintf.

fz_stddbg()

fz_output * fz_stddbg

(

fz_context *

ctx

)

Retrieve an fz_output for the default debugging stream. On Windows this will be OutputDebugString for non-console apps. Otherwise, it is always fz_stderr.

Optionally may be fz_dropped when finished with.

fz_stderr()

fz_output * fz_stderr

(

fz_context *

ctx

)

Retrieve an fz_output that directs to stdout.

Optionally may be fz_dropped when finished with.

fz_stdout()

fz_output * fz_stdout

(

fz_context *

ctx

)

Retrieve an fz_output that directs to stdout.

Optionally may be fz_dropped when finished with.

fz_stream_from_output()

fz_stream * fz_stream_from_output	(	fz_context *	,
		fz_output *	)

Obtain the fz_output in the form of a fz_stream.

This allows data to be read back from some forms of fz_output object. When finished reading, the fz_stream should be released by calling fz_drop_stream. Until the fz_stream is dropped, no further operations should be performed on the fz_output object.

fz_tell_output()

int64_t fz_tell_output	(	fz_context *	ctx,
		fz_output *	out )

Return the current file position.

Throw an error on untellable outputs.

fz_truncate_output()

void fz_truncate_output	(	fz_context *	,
		fz_output *	)

Truncate the output at the current position.

This allows output streams which have seeked back from the end of their storage to be truncated at the current point.

fz_vsnprintf()

size_t fz_vsnprintf	(	char *	buffer,
		size_t	space,
		const char *	fmt,
		va_list	args )

A vsnprintf work-alike, using our custom formatter.

fz_write_base64()

void fz_write_base64	(	fz_context *	ctx,
		fz_output *	out,
		const unsigned char *	data,
		size_t	size,
		int	newline )

Write a base64 encoded data block, optionally with periodic newlines.

fz_write_base64_buffer()

void fz_write_base64_buffer	(	fz_context *	ctx,
		fz_output *	out,
		fz_buffer *	data,
		int	newline )

Write a base64 encoded fz_buffer, optionally with periodic newlines.

fz_write_bits()

void fz_write_bits	(	fz_context *	ctx,
		fz_output *	out,
		unsigned int	data,
		int	num_bits )

Write num_bits of data to the end of the output stream, assumed to be packed most significant bits first.

fz_write_bits_sync()

void fz_write_bits_sync	(	fz_context *	ctx,
		fz_output *	out )

Sync to byte boundary after writing bits.

fz_write_buffer()

void fz_write_buffer	(	fz_context *	ctx,
		fz_output *	out,
		fz_buffer *	data )

fz_write_byte()

void fz_write_byte	(	fz_context *	ctx,
		fz_output *	out,
		unsigned char	x )

fz_write_char()

void fz_write_char	(	fz_context *	ctx,
		fz_output *	out,
		char	x )

fz_write_data()

void fz_write_data	(	fz_context *	ctx,
		fz_output *	out,
		const void *	data,
		size_t	size )

Write data to output.

data: Pointer to data to write. size: Size of data to write in bytes.

fz_write_float_be()

void fz_write_float_be	(	fz_context *	ctx,
		fz_output *	out,
		float	f )

fz_write_float_le()

void fz_write_float_le	(	fz_context *	ctx,
		fz_output *	out,
		float	f )

fz_write_int16_be()

void fz_write_int16_be	(	fz_context *	ctx,
		fz_output *	out,
		int	x )

fz_write_int16_le()

void fz_write_int16_le	(	fz_context *	ctx,
		fz_output *	out,
		int	x )

fz_write_int32_be()

void fz_write_int32_be	(	fz_context *	ctx,
		fz_output *	out,
		int	x )

Write different sized data to an output stream.

fz_write_int32_le()

void fz_write_int32_le	(	fz_context *	ctx,
		fz_output *	out,
		int	x )

fz_write_printf()

void fz_write_printf	(	fz_context *	ctx,
		fz_output *	out,
		const char *	fmt,
			... )

Format and write data to an output stream. See fz_format_string for formatting details.

fz_write_rune()

void fz_write_rune	(	fz_context *	ctx,
		fz_output *	out,
		int	rune )

Write a UTF-8 encoded unicode character.

fz_write_stream()

void fz_write_stream	(	fz_context *	ctx,
		fz_output *	out,
		fz_stream *	in )

Copy the stream contents to the output.

fz_write_string()

void fz_write_string	(	fz_context *	ctx,
		fz_output *	out,
		const char *	s )

Write a string. Does not write zero terminator.

fz_write_uint16_be()

void fz_write_uint16_be	(	fz_context *	ctx,
		fz_output *	out,
		unsigned int	x )

fz_write_uint16_le()

void fz_write_uint16_le	(	fz_context *	ctx,
		fz_output *	out,
		unsigned int	x )

fz_write_uint32_be()

void fz_write_uint32_be	(	fz_context *	ctx,
		fz_output *	out,
		unsigned int	x )

fz_write_uint32_le()

void fz_write_uint32_le	(	fz_context *	ctx,
		fz_output *	out,
		unsigned int	x )

fz_write_vprintf()

void fz_write_vprintf	(	fz_context *	ctx,
		fz_output *	out,
		const char *	fmt,
		va_list	ap )

va_list version of fz_write_printf.