MuPDF X.Y.Z

fitz/stream.h

Index

typedef

struct

function

Stream

function fz_file_exists

int
fz_file_exists (
        fz_context *ctx,
        const char *path
)

Return true if the named file exists and is readable.

typedef fz_stream

typedef struct fz_stream fz_stream

fz_stream is a buffered reader capable of seeking in both directions.

Streams are reference counted, so references must be dropped by a call to fz_drop_stream.

Only the data between rp and wp is valid.

function fz_open_file

fz_stream *
fz_open_file (
        fz_context *ctx,
        const char *filename
)

Open the named file and wrap it in a stream.

filename:
Path to a file. On non-Windows machines the filename should be exactly as it would be passed to fopen(2). On Windows machines, the path should be UTF-8 encoded so that non-ASCII characters can be represented. Other platforms do the encoding as standard anyway (and in most cases, particularly for MacOS and Linux, the encoding they use is UTF-8 anyway).

function fz_open_file_autodelete

fz_stream *
fz_open_file_autodelete (
        fz_context *ctx,
        const char *filename
)

Do the same as fz_open_file, but delete the file upon close.

function fz_try_open_file

fz_stream *
fz_try_open_file (
        fz_context *ctx,
        const char *name
)

Open the named file and wrap it in a stream.

Does the same as fz_open_file, but in the event the file does not open, it will return NULL rather than throw an exception.

function fz_open_file_w

fz_stream *
fz_open_file_w (
        fz_context *ctx,
        const wchar_t *filename
)

Open the named file and wrap it in a stream.

This function is only available when compiling for Win32.

filename:
Wide character path to the file as it would be given to _wfopen().

function fz_stream_filename

const char *
fz_stream_filename (
        fz_context *ctx,
        fz_stream *stm
)

Return the filename (UTF-8 encoded) from which a stream was opened.

Returns NULL if the filename is not available (or the stream was opened from a source other than a file).

function fz_open_memory

fz_stream *
fz_open_memory (
        fz_context *ctx,
        const unsigned char *data,
        size_t len
)

Open a block of memory as a stream.

data:
Pointer to start of data block. Ownership of the data block is NOT passed in.
len:
Number of bytes in data block.

Returns pointer to newly created stream. May throw exceptions on failure to allocate.

function fz_open_buffer

fz_stream *
fz_open_buffer (
        fz_context *ctx,
        fz_buffer *buf
)

Open a buffer as a stream.

buf:
The buffer to open. Ownership of the buffer is NOT passed in (this function takes its own reference).

Returns pointer to newly created stream. May throw exceptions on failure to allocate.

function fz_open_leecher

fz_stream *
fz_open_leecher (
        fz_context *ctx,
        fz_stream *chain,
        fz_buffer *buf
)

Attach a filter to a stream that will store any characters read from the stream into the supplied buffer.

chain:
The underlying stream to leech from.
buf:
The buffer into which the read data should be appended. The buffer will be resized as required.

Returns pointer to newly created stream. May throw exceptions on failure to allocate.

function fz_keep_stream

fz_stream *
fz_keep_stream (
        fz_context *ctx,
        fz_stream *stm
)

Increments the reference count for a stream. Returns the same pointer.

Never throws exceptions.

function fz_drop_stream

void
fz_drop_stream (
        fz_context *ctx,
        fz_stream *stm
)

Decrements the reference count for a stream.

When the reference count for the stream hits zero, frees the storage used for the fz_stream itself, and (usually) releases the underlying resources that the stream is based upon (depends on the method used to open the stream initially).

function fz_tell

int64_t
fz_tell (
        fz_context *ctx,
        fz_stream *stm
)

return the current reading position within a stream

function fz_seek

void
fz_seek (
        fz_context *ctx,
        fz_stream *stm,
        int64_t offset,
        int whence
)

Seek within a stream.

stm:
The stream to seek within.
offset:
The offset to seek to.
whence:
From where the offset is measured (see fseek). SEEK_SET - start of stream. SEEK_CUR - current position. SEEK_END - end of stream.

function fz_read

size_t
fz_read (
        fz_context *ctx,
        fz_stream *stm,
        unsigned char *data,
        size_t len
)

Read from a stream into a given data block.

stm:
The stream to read from.
data:
The data block to read into.
len:
The length of the data block (in bytes).

Returns the number of bytes read. May throw exceptions.

function fz_skip

size_t
fz_skip (
        fz_context *ctx,
        fz_stream *stm,
        size_t len
)

Read from a stream discarding data.

stm:
The stream to read from.
len:
The number of bytes to read.

Returns the number of bytes read. May throw exceptions.

function fz_read_all

fz_buffer *
fz_read_all (
        fz_context *ctx,
        fz_stream *stm,
        size_t initial
)

Read all of a stream into a buffer.

stm:
The stream to read from
initial:
Suggested initial size for the buffer.

Returns a buffer created from reading from the stream. May throw exceptions on failure to allocate.

function fz_read_file

fz_buffer *
fz_read_file (
        fz_context *ctx,
        const char *filename
)

Read all the contents of a file into a buffer.

function fz_try_read_file

fz_buffer *
fz_try_read_file (
        fz_context *ctx,
        const char *filename
)

Read all the contents of a file into a buffer.

Returns NULL if the file does not exist, otherwise behaves exactly as fz_read_file.

function fz_read_text_file

char *
fz_read_text_file (
        fz_context *ctx,
        const char *filename
)

Read all the contents of a file into a string. File should be UTF-8 encoded plain text.

function fz_read_uint16

uint16_t
fz_read_uint16 (
        fz_context *ctx,
        fz_stream *stm
)

fz_read_[u]int(16|24|32|64)(_le)?

Read a 16/32/64 bit signed/unsigned integer from stream, in big or little-endian byte orders.

Throws an exception if EOF is encountered.

function fz_read_uint24

uint32_t
fz_read_uint24 (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_uint32

uint32_t
fz_read_uint32 (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_uint64

uint64_t
fz_read_uint64 (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_uint16_le

uint16_t
fz_read_uint16_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_uint24_le

uint32_t
fz_read_uint24_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_uint32_le

uint32_t
fz_read_uint32_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_uint64_le

uint64_t
fz_read_uint64_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_int16

int16_t
fz_read_int16 (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_int32

int32_t
fz_read_int32 (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_int64

int64_t
fz_read_int64 (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_int16_le

int16_t
fz_read_int16_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_int32_le

int32_t
fz_read_int32_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_int64_le

int64_t
fz_read_int64_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_float_le

float
fz_read_float_le (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_float

float
fz_read_float (
        fz_context *ctx,
        fz_stream *stm
)

function fz_read_string

void
fz_read_string (
        fz_context *ctx,
        fz_stream *stm,
        char *buffer,
        int len
)

Read a null terminated string from the stream into a buffer of a given length. The buffer will be null terminated. Throws on failure (including the failure to fit the entire string including the terminator into the buffer).

function fz_read_rune

int
fz_read_rune (
        fz_context *ctx,
        fz_stream *in
)

Read a utf-8 rune from a stream.

In the event of encountering badly formatted utf-8 codes (such as a leading code with an unexpected number of following codes) no error/exception is given, but undefined values may be returned.

function fz_read_utf16_le

int
fz_read_utf16_le (
        fz_context *ctx,
        fz_stream *stm
)

Read a utf-16 rune from a stream. (little endian and big endian respectively).

In the event of encountering badly formatted utf-16 codes (mismatched surrogates) no error/exception is given, but undefined values may be returned.

function fz_read_utf16_be

int
fz_read_utf16_be (
        fz_context *ctx,
        fz_stream *stm
)

typedef fz_stream_next_fn

typedef int (fz_stream_next_fn)(fz_context *ctx, fz_stream *stm, size_t max)

A function type for use when implementing fz_streams. The supplied function of this type is called whenever data is required, and the current buffer is empty.

stm:
The stream to operate on.
max:
a hint as to the maximum number of bytes that the caller needs to be ready immediately. Can safely be ignored.

Returns -1 if there is no more data in the stream. Otherwise, the function should find its internal state using stm->state, refill its buffer, update stm->rp and stm->wp to point to the start and end of the new data respectively, and then “return *stm->rp++“.

typedef fz_stream_drop_fn

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

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

state:
The stream state to release.

typedef fz_stream_seek_fn

typedef void (fz_stream_seek_fn)(fz_context *ctx, fz_stream *stm, int64_t offset, int whence)

A function type for use when implementing fz_streams. The supplied function of this type is called when fz_seek is requested, and the arguments are as defined for fz_seek.

The stream can find it’s private state in stm->state.

struct fz_stream

struct fz_stream
{
        int refs;
        int error;
        int eof;
        int progressive;
        int64_t pos;
        int avail;
        int bits;
        unsigned char *rp, *wp;
        void *state;
        fz_stream_next_fn *next;
        fz_stream_drop_fn *drop;
        fz_stream_seek_fn *seek;
}

function fz_new_stream

fz_stream *
fz_new_stream (
        fz_context *ctx,
        void *state,
        fz_stream_next_fn *next,
        fz_stream_drop_fn *drop
)

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

state:
Internal state (opaque to everything but implementation).
next:
Should provide the next set of bytes (up to max) of stream data. Return the number of bytes read, or EOF when there is no more data.
drop:
Should clean up and free the internal state. May not throw exceptions.

function fz_read_best

fz_buffer *
fz_read_best (
        fz_context *ctx,
        fz_stream *stm,
        size_t initial,
        int *truncated,
        size_t worst_case
)

Attempt to read a stream into a buffer. If truncated is NULL behaves as fz_read_all, sets a truncated flag in case of error.

stm:
The stream to read from.
initial:
Suggested initial size for the buffer.
truncated:
Flag to store success/failure indication in.
worst_case:
0 for unknown, otherwise an upper bound for the size of the stream.

Returns a buffer created from reading from the stream.

function fz_read_line

char *
fz_read_line (
        fz_context *ctx,
        fz_stream *stm,
        char *buf,
        size_t max
)

Read a line from stream into the buffer until either a terminating newline or EOF, which it replaces with a null byte (‘\0’).

Returns buf on success, and NULL when end of file occurs while no characters have been read.

function fz_skip_string

int
fz_skip_string (
        fz_context *ctx,
        fz_stream *stm,
        const char *str
)

Skip over a given string in a stream. Return 0 if successfully skipped, non-zero otherwise. As many characters will be skipped over as matched in the string.

function fz_skip_space

void
fz_skip_space (
        fz_context *ctx,
        fz_stream *stm
)

Skip over whitespace (bytes <= 32) in a stream.

function fz_available

size_t
fz_available (
        fz_context *ctx,
        fz_stream *stm,
        size_t max
)

Ask how many bytes are available immediately from a given stream.

stm:
The stream to read from.
max:
A hint for the underlying stream; the maximum number of bytes that we are sure we will want to read. If you do not know this number, give 1.

Returns the number of bytes immediately available between the read and write pointers. This number is guaranteed only to be 0 if we have hit EOF. The number of bytes returned here need have no relation to max (could be larger, could be smaller).

function fz_read_byte

int
fz_read_byte (
        fz_context *ctx,
        fz_stream *stm
)

Read the next byte from a stream.

stm:
The stream t read from.

Returns -1 for end of stream, or the next byte. May throw exceptions.

function fz_peek_byte

int
fz_peek_byte (
        fz_context *ctx,
        fz_stream *stm
)

Peek at the next byte in a stream.

stm:
The stream to peek at.

Returns -1 for EOF, or the next byte that will be read.

function fz_unread_byte

void
fz_unread_byte (
        fz_context *ctx FZ_UNUSED,
        fz_stream *stm
)

Unread the single last byte successfully read from a stream. Do not call this without having successfully read a byte.

stm:
The stream to operate upon.

function fz_is_eof

int
fz_is_eof (
        fz_context *ctx,
        fz_stream *stm
)

Query if the stream has reached EOF (during normal bytewise reading).

See fz_is_eof_bits for the equivalent function for bitwise reading.

function fz_read_bits

unsigned int
fz_read_bits (
        fz_context *ctx,
        fz_stream *stm,
        int n
)

Read the next n bits from a stream (assumed to be packed most significant bit first).

stm:
The stream to read from.
n:
The number of bits to read, between 1 and 8*sizeof(int) inclusive.

Returns -1 for EOF, or the required number of bits.

function fz_read_rbits

unsigned int
fz_read_rbits (
        fz_context *ctx,
        fz_stream *stm,
        int n
)

Read the next n bits from a stream (assumed to be packed least significant bit first).

stm:
The stream to read from.
n:
The number of bits to read, between 1 and 8*sizeof(int) inclusive.

Returns (unsigned int)-1 for EOF, or the required number of bits.

function fz_sync_bits

void
fz_sync_bits (
        fz_context *ctx FZ_UNUSED,
        fz_stream *stm
)

Called after reading bits to tell the stream that we are about to return to reading bytewise. Resyncs the stream to whole byte boundaries.

function fz_is_eof_bits

int
fz_is_eof_bits (
        fz_context *ctx,
        fz_stream *stm
)

Query if the stream has reached EOF (during bitwise reading).

See fz_is_eof for the equivalent function for bytewise reading.

Implementation details: subject to change.

function fz_open_file_ptr_no_close

fz_stream *
fz_open_file_ptr_no_close (
        fz_context *ctx,
        FILE *file
)

Create a stream from a FILE * that will not be closed when the stream is dropped.