init commit

include/mupdf/fitz/stream.h

@@ -1,3 +1,25 @@
+// Copyright (C) 2004-2021 Artifex Software, Inc.
+//
+// This file is part of MuPDF.
+//
+// MuPDF is free software: you can redistribute it and/or modify it under the
+// terms of the GNU Affero General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option)
+// any later version.
+//
+// MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+// FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+// details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
+//
+// Alternative licensing terms are available from the licensor.
+// For commercial licensing, see <https://www.artifex.com/> or contact
+// Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
+// CA 94129, USA, for further information.
+
 #ifndef MUPDF_FITZ_STREAM_H
 #define MUPDF_FITZ_STREAM_H
 
@@ -5,12 +27,12 @@
 #include "mupdf/fitz/context.h"
 #include "mupdf/fitz/buffer.h"
 
-/*
-	fz_file_exists: Return true if the named file exists and is readable.
+/**
+	Return true if the named file exists and is readable.
 */
 int fz_file_exists(fz_context *ctx, const char *path);
 
-/*
+/**
 	fz_stream is a buffered reader capable of seeking in both
 	directions.
 
@@ -19,24 +41,37 @@ int fz_file_exists(fz_context *ctx, const char *path);
 
 	Only the data between rp and wp is valid.
 */
-typedef struct fz_stream_s fz_stream;
+typedef struct fz_stream fz_stream;
 
-/*
-	fz_open_file: Open the named file and wrap it in a stream.
+/**
+	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).
+	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).
 */
 fz_stream *fz_open_file(fz_context *ctx, const char *filename);
 
-fz_stream *fz_open_file_progressive(fz_context *ctx, const char *filename, int bps);
+/**
+	Do the same as fz_open_file, but delete the file upon close.
+*/
+fz_stream *fz_open_file_autodelete(fz_context *ctx, const char *filename);
 
-/*
-	fz_open_file_w: Open the named file and wrap it in a stream.
+/**
+	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.
+*/
+fz_stream *fz_try_open_file(fz_context *ctx, const char *name);
+
+#ifdef _WIN32
+/**
+	Open the named file and wrap it in a stream.
 
 	This function is only available when compiling for Win32.
 
@@ -44,12 +79,21 @@ fz_stream *fz_open_file_progressive(fz_context *ctx, const char *filename, int b
 	to _wfopen().
 */
 fz_stream *fz_open_file_w(fz_context *ctx, const wchar_t *filename);
+#endif /* _WIN32 */
 
-/*
-	fz_open_memory: Open a block of memory as a stream.
+/**
+	Return the filename (UTF-8 encoded) from which a stream was opened.
 
-	data: Pointer to start of data block. Ownership of the data block is
-	NOT passed in.
+	Returns NULL if the filename is not available (or the stream was
+	opened from a source other than a file).
+*/
+const char *fz_stream_filename(fz_context *ctx, fz_stream *stm);
+
+/**
+	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.
 
@@ -58,19 +102,19 @@ fz_stream *fz_open_file_w(fz_context *ctx, const wchar_t *filename);
 */
 fz_stream *fz_open_memory(fz_context *ctx, const unsigned char *data, size_t len);
 
-/*
-	fz_open_buffer: Open a buffer as a stream.
+/**
+	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).
+	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.
 */
 fz_stream *fz_open_buffer(fz_context *ctx, fz_buffer *buf);
 
-/*
-	fz_open_leecher: Attach a filter to a stream that will store any
+/**
+	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.
@@ -83,33 +127,46 @@ fz_stream *fz_open_buffer(fz_context *ctx, fz_buffer *buf);
 */
 fz_stream *fz_open_leecher(fz_context *ctx, fz_stream *chain, fz_buffer *buf);
 
-/*
-	fz_drop_stream: Close an open stream.
+/**
+	Increments the reference count for a stream. Returns the same
+	pointer.
 
-	Drops a reference for the stream. Once no references remain
-	the stream will be closed, as will any file descriptor the
-	stream is using.
+	Never throws exceptions.
+*/
+fz_stream *fz_keep_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).
 */
 void fz_drop_stream(fz_context *ctx, fz_stream *stm);
 
-/*
-	fz_tell: return the current reading position within a stream
+/**
+	return the current reading position within a stream
 */
 int64_t fz_tell(fz_context *ctx, fz_stream *stm);
 
-/*
-	fz_seek: Seek within a stream.
+/**
+	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.
+
 */
 void fz_seek(fz_context *ctx, fz_stream *stm, int64_t offset, int whence);
 
-/*
-	fz_read: Read from a stream into a given data block.
+/**
+	Read from a stream into a given data block.
 
 	stm: The stream to read from.
 
@@ -121,8 +178,8 @@ void fz_seek(fz_context *ctx, fz_stream *stm, int64_t offset, int whence);
 */
 size_t fz_read(fz_context *ctx, fz_stream *stm, unsigned char *data, size_t len);
 
-/*
-	fz_skip: Read from a stream discarding data.
+/**
+	Read from a stream discarding data.
 
 	stm: The stream to read from.
 
@@ -132,8 +189,8 @@ size_t fz_read(fz_context *ctx, fz_stream *stm, unsigned char *data, size_t len)
 */
 size_t fz_skip(fz_context *ctx, fz_stream *stm, size_t len);
 
-/*
-	fz_read_all: Read all of a stream into a buffer.
+/**
+	Read all of a stream into a buffer.
 
 	stm: The stream to read from
 
@@ -144,12 +201,20 @@ size_t fz_skip(fz_context *ctx, fz_stream *stm, size_t len);
 */
 fz_buffer *fz_read_all(fz_context *ctx, fz_stream *stm, size_t initial);
 
-/*
-	fz_read_file: Read all the contents of a file into a buffer.
+/**
+	Read all the contents of a file into a buffer.
 */
 fz_buffer *fz_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.
+*/
+fz_buffer *fz_try_read_file(fz_context *ctx, const char *filename);
+
+/**
 	fz_read_[u]int(16|24|32|64)(_le)?
 
 	Read a 16/32/64 bit signed/unsigned integer from stream,
@@ -175,41 +240,40 @@ int16_t fz_read_int16_le(fz_context *ctx, fz_stream *stm);
 int32_t fz_read_int32_le(fz_context *ctx, fz_stream *stm);
 int64_t fz_read_int64_le(fz_context *ctx, fz_stream *stm);
 
-/*
-	fz_read_string: Read a null terminated string from the stream into
+float fz_read_float_le(fz_context *ctx, fz_stream *stm);
+float fz_read_float(fz_context *ctx, fz_stream *stm);
+
+/**
+	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).
+	Throws on failure (including the failure to fit the entire
+	string including the terminator into the buffer).
 */
 void fz_read_string(fz_context *ctx, fz_stream *stm, char *buffer, int len);
 
-enum
-{
-	FZ_STREAM_META_PROGRESSIVE = 1,
-	FZ_STREAM_META_LENGTH = 2
-};
+/**
+	Read a utf-8 rune from a stream.
 
-/*
-	fz_stream_meta: Perform a meta call on a stream (typically to
-	request meta information about a stream).
-
-	stm: The stream to query.
-
-	key: The meta request identifier.
-
-	size: Meta request specific parameter - typically the size of
-	the data block pointed to by ptr.
-
-	ptr: Meta request specific parameter - typically a pointer to
-	a block of data to be filled in.
-
-	Returns -1 if this stream does not support this meta operation,
-	or a meta operation specific return value.
+	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.
 */
-int fz_stream_meta(fz_context *ctx, fz_stream *stm, int key, int size, void *ptr);
+int fz_read_rune(fz_context *ctx, fz_stream *in);
 
-/*
-	fz_stream_next_fn: A function type for use when implementing
+/**
+	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.
+*/
+int fz_read_utf16_le(fz_context *ctx, fz_stream *stm);
+int fz_read_utf16_be(fz_context *ctx, fz_stream *stm);
+
+/**
+	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.
 
@@ -226,8 +290,8 @@ int fz_stream_meta(fz_context *ctx, fz_stream *stm, int key, int size, void *ptr
 */
 typedef int (fz_stream_next_fn)(fz_context *ctx, fz_stream *stm, size_t max);
 
-/*
-	fz_stream_drop_fn: A function type for use when implementing
+/**
+	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.
@@ -236,8 +300,8 @@ typedef int (fz_stream_next_fn)(fz_context *ctx, fz_stream *stm, size_t max);
 */
 typedef void (fz_stream_drop_fn)(fz_context *ctx, void *state);
 
-/*
-	fz_stream_seek_fn: A function type for use when implementing
+/**
+	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.
@@ -246,21 +310,12 @@ typedef void (fz_stream_drop_fn)(fz_context *ctx, void *state);
 */
 typedef void (fz_stream_seek_fn)(fz_context *ctx, fz_stream *stm, int64_t offset, int whence);
 
-/*
-	fz_stream_meta_fn: A function type for use when implementing
-	fz_streams. The supplied function of this type is called when
-	fz_meta is requested, and the arguments are as defined for
-	fz_meta.
-
-	The stream can find it's private state in stm->state.
-*/
-typedef int (fz_stream_meta_fn)(fz_context *ctx, fz_stream *stm, int key, int size, void *ptr);
-
-struct fz_stream_s
+struct fz_stream
 {
 	int refs;
 	int error;
 	int eof;
+	int progressive;
 	int64_t pos;
 	int avail;
 	int bits;
@@ -269,11 +324,10 @@ struct fz_stream_s
 	fz_stream_next_fn *next;
 	fz_stream_drop_fn *drop;
 	fz_stream_seek_fn *seek;
-	fz_stream_meta_fn *meta;
 };
 
-/*
-	fz_new_stream: Create a new stream object with the given
+/**
+	Create a new stream object with the given
 	internal state and function pointers.
 
 	state: Internal state (opaque to everything but implementation).
@@ -287,10 +341,8 @@ struct fz_stream_s
 */
 fz_stream *fz_new_stream(fz_context *ctx, void *state, fz_stream_next_fn *next, fz_stream_drop_fn *drop);
 
-fz_stream *fz_keep_stream(fz_context *ctx, fz_stream *stm);
-
-/*
-	fz_read_best: Attempt to read a stream into a buffer. If truncated
+/**
+	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.
 
@@ -300,21 +352,37 @@ fz_stream *fz_keep_stream(fz_context *ctx, fz_stream *stm);
 
 	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.
 */
-fz_buffer *fz_read_best(fz_context *ctx, fz_stream *stm, size_t initial, int *truncated);
+fz_buffer *fz_read_best(fz_context *ctx, fz_stream *stm, size_t initial, int *truncated, size_t worst_case);
 
-/*
-	fz_read_line: Read a line from stream into the buffer until either a
-	terminating newline or EOF, which it replaces with a null byte ('\0').
+/**
+	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.
+	Returns buf on success, and NULL when end of file occurs while
+	no characters have been read.
 */
 char *fz_read_line(fz_context *ctx, fz_stream *stm, char *buf, size_t max);
 
-/*
-	fz_available: Ask how many bytes are available immediately from
+/**
+	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.
+*/
+int fz_skip_string(fz_context *ctx, fz_stream *stm, const char *str);
+
+/**
+	Skip over whitespace (bytes <= 32) in a stream.
+*/
+void fz_skip_space(fz_context *ctx, fz_stream *stm);
+
+/**
+	Ask how many bytes are available immediately from
 	a given stream.
 
 	stm: The stream to read from.
@@ -343,6 +411,7 @@ static inline size_t fz_available(fz_context *ctx, fz_stream *stm, size_t max)
 	fz_catch(ctx)
 	{
 		fz_rethrow_if(ctx, FZ_ERROR_TRYLATER);
+		fz_report_error(ctx);
 		fz_warn(ctx, "read error; treating as end of file");
 		stm->error = 1;
 		c = EOF;
@@ -356,8 +425,8 @@ static inline size_t fz_available(fz_context *ctx, fz_stream *stm, size_t max)
 	return stm->wp - stm->rp;
 }
 
-/*
-	fz_read_byte: Read the next byte from a stream.
+/**
+	Read the next byte from a stream.
 
 	stm: The stream t read from.
 
@@ -377,6 +446,7 @@ static inline int fz_read_byte(fz_context *ctx, fz_stream *stm)
 	fz_catch(ctx)
 	{
 		fz_rethrow_if(ctx, FZ_ERROR_TRYLATER);
+		fz_report_error(ctx);
 		fz_warn(ctx, "read error; treating as end of file");
 		stm->error = 1;
 		c = EOF;
@@ -386,8 +456,8 @@ static inline int fz_read_byte(fz_context *ctx, fz_stream *stm)
 	return c;
 }
 
-/*
-	fz_peek_byte: Peek at the next byte in a stream.
+/**
+	Peek at the next byte in a stream.
 
 	stm: The stream to peek at.
 
@@ -411,6 +481,7 @@ static inline int fz_peek_byte(fz_context *ctx, fz_stream *stm)
 	fz_catch(ctx)
 	{
 		fz_rethrow_if(ctx, FZ_ERROR_TRYLATER);
+		fz_report_error(ctx);
 		fz_warn(ctx, "read error; treating as end of file");
 		stm->error = 1;
 		c = EOF;
@@ -420,8 +491,8 @@ static inline int fz_peek_byte(fz_context *ctx, fz_stream *stm)
 	return c;
 }
 
-/*
-	fz_unread_byte: Unread the single last byte successfully
+/**
+	Unread the single last byte successfully
 	read from a stream. Do not call this without having
 	successfully read a byte.
 
@@ -432,6 +503,13 @@ static inline void fz_unread_byte(fz_context *ctx FZ_UNUSED, fz_stream *stm)
 	stm->rp--;
 }
 
+/**
+	Query if the stream has reached EOF (during normal bytewise
+	reading).
+
+	See fz_is_eof_bits for the equivalent function for bitwise
+	reading.
+*/
 static inline int fz_is_eof(fz_context *ctx, fz_stream *stm)
 {
 	if (stm->rp == stm->wp)
@@ -443,8 +521,8 @@ static inline int fz_is_eof(fz_context *ctx, fz_stream *stm)
 	return 0;
 }
 
-/*
-	fz_read_bits: Read the next n bits from a stream (assumed to
+/**
+	Read the next n bits from a stream (assumed to
 	be packed most significant bit first).
 
 	stm: The stream to read from.
@@ -486,8 +564,8 @@ static inline unsigned int fz_read_bits(fz_context *ctx, fz_stream *stm, int n)
 	return x;
 }
 
-/*
-	fz_read_rbits: Read the next n bits from a stream (assumed to
+/**
+	Read the next n bits from a stream (assumed to
 	be packed least significant bit first).
 
 	stm: The stream to read from.
@@ -535,8 +613,8 @@ static inline unsigned int fz_read_rbits(fz_context *ctx, fz_stream *stm, int n)
 	return x;
 }
 
-/*
-	fz_sync_bits: Called after reading bits to tell the stream
+/**
+	Called after reading bits to tell the stream
 	that we are about to return to reading bytewise. Resyncs
 	the stream to whole byte boundaries.
 */
@@ -545,9 +623,24 @@ static inline void fz_sync_bits(fz_context *ctx FZ_UNUSED, fz_stream *stm)
 	stm->avail = 0;
 }
 
+/**
+	Query if the stream has reached EOF (during bitwise
+	reading).
+
+	See fz_is_eof for the equivalent function for bytewise
+	reading.
+*/
 static inline int fz_is_eof_bits(fz_context *ctx, fz_stream *stm)
 {
 	return fz_is_eof(ctx, stm) && (stm->avail == 0 || stm->bits == EOF);
 }
 
+/* Implementation details: subject to change. */
+
+/**
+	Create a stream from a FILE * that will not be closed
+	when the stream is dropped.
+*/
+fz_stream *fz_open_file_ptr_no_close(fz_context *ctx, FILE *file);
+
 #endif