stream: libg3d Reference Manual

stream

stream — I/O abstraction layer for plugins

Functions

G3DStream *	g3d_stream_open_file ()
G3DStream *	g3d_stream_open_structured_file ()
G3DStream *	g3d_stream_open_structured_file_from_stream ()
G3DStream *	g3d_stream_open_zip ()
G3DStream *	g3d_stream_open_zip_from_stream ()
G3DStream *	g3d_stream_open_gzip_from_stream ()
G3DStream *	g3d_stream_from_buffer ()
G3DStream *	g3d_stream_zlib_inflate_stream ()
G3DStream *	g3d_stream_new_custom ()
gint	g3d_stream_close ()
gint	g3d_stream_skip ()
gint	g3d_stream_seek ()
goffset	g3d_stream_tell ()
goffset	g3d_stream_size ()
gboolean	g3d_stream_eof ()
gboolean	g3d_stream_is_seekable ()
gchar *	g3d_stream_get_uri ()
guint32	g3d_stream_line ()
gsize	g3d_stream_read ()
gchar *	g3d_stream_read_line ()
gint32	g3d_stream_read_int8 ()
gint32	g3d_stream_read_int16_be ()
gint32	g3d_stream_read_int16_le ()
gint32	g3d_stream_read_int32_be ()
gint32	g3d_stream_read_int32_le ()
G3DFloat	g3d_stream_read_float_be ()
G3DFloat	g3d_stream_read_float_le ()
G3DDouble	g3d_stream_read_double_be ()
G3DDouble	g3d_stream_read_double_le ()
gint32	g3d_stream_read_cstr ()
gint	(*G3DStreamCloseFunc) ()
gboolean	(*G3DStreamEofFunc) ()
gsize	(*G3DStreamReadFunc) ()
gchar *	(*G3DStreamReadLineFunc) ()
gint	(*G3DStreamSeekFunc) ()
goffset	(*G3DStreamSizeFunc) ()
goffset	(*G3DStreamTellFunc) ()

Types and Values

G3DStream

Includes

#include <g3d/stream.h>

Description

A stream is an abstraction for data input. It enables plugins to read data from a file, a memory buffer, a container file or some other medium.

Functions

g3d_stream_open_file ()

G3DStream *
g3d_stream_open_file (const gchar *filename,
                      const gchar *mode);

Opens a file with the C stdio routines.

Parameters

filename	the name of the file to open
mode	the mode to open the file, as given to `fopen()`

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_open_structured_file ()

G3DStream *
g3d_stream_open_structured_file (const gchar *filename,
                                 const gchar *subfile);

Open a file within a Structured File as G3DStream.

Parameters

filename	name of container file
subfile	name of (contained) sub-file

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_open_structured_file_from_stream ()

G3DStream *
g3d_stream_open_structured_file_from_stream
                               (G3DStream *stream,
                                const gchar *subfile);

Open a file within a Structured File which is opened as a stream. At the moment this only works for streams opened by g3d_stream_open_file() as the file is directly opened again.

Parameters

stream	stream of container file
subfile	name of (contained) sub-file

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_open_zip ()

G3DStream *
g3d_stream_open_zip (const gchar *filename,
                     const gchar *subfile);

Open a file within a Zip archive.

Parameters

filename	name of container file
subfile	name of (contained) sub-file

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_open_zip_from_stream ()

G3DStream *
g3d_stream_open_zip_from_stream (G3DStream *stream,
                                 const gchar *subfile);

Open a file within a Zip archive which is opened as a stream. At the moment this only works for streams opened by g3d_stream_open_file() as the file is directly opened again.

Parameters

stream	stream of container file
subfile	name of (contained) sub-file

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_open_gzip_from_stream ()

G3DStream *
g3d_stream_open_gzip_from_stream (G3DStream *stream);

Reads data from a gzip-compressed stream.

Parameters

stream

stream to read from

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_from_buffer ()

G3DStream *
g3d_stream_from_buffer (guint8 *buffer,
                        gsize size,
                        const gchar *title,
                        gboolean free_buffer);

Use a buffer in memory as G3DStream.

Parameters

buffer	memory buffer to use
size	size of buffer
title	optional title of stream, may be NULL
free_buffer	whether to free the memory with `g_free()` on `g3d_stream_close()`

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_zlib_inflate_stream ()

G3DStream *
g3d_stream_zlib_inflate_stream (G3DStream *stream,
                                gsize cmp_size);

Opens a new stream to decompress zlib-deflated parts of a stream.

Parameters

stream	a parent stream
cmp_size	the compressed size of the deflated part

Returns

a newly allocated G3DStream or NULL in case of an error

g3d_stream_new_custom ()

G3DStream *
g3d_stream_new_custom (guint32 flags,
                       const gchar *uri,
                       G3DStreamReadFunc readfunc,
                       G3DStreamReadLineFunc readlinefunc,
                       G3DStreamSeekFunc seekfunc,
                       G3DStreamTellFunc tellfunc,
                       G3DStreamSizeFunc sizefunc,
                       G3DStreamEofFunc eoffunc,
                       G3DStreamCloseFunc closefunc,
                       gpointer data);

Creates a new G3DStream with custom callback functions.

Parameters

flags	stream capability flags
uri	URI of new stream, must not be NULL
readfunc	read callback function
readlinefunc	read line callback function, may be NULL in which case line reading is emulated with `g3d_stream_read()`
seekfunc	seek callback function
tellfunc	tell callback function
sizefunc	size callback function
eoffunc	end-of-file callback function
closefunc	close callback function
data	opaque data for all callback functions

Returns

a newly allocated G3DStream or NULL in case of an error.

g3d_stream_close ()

gint
g3d_stream_close (G3DStream *stream);

Closes an open stream.

Parameters

stream

the stream

Returns

0 on success.

g3d_stream_skip ()

gint
g3d_stream_skip (G3DStream *stream,
                 goffset offset);

Skip a number of bytes (>= 0) in stream even if it does not support seeking.

Parameters

stream	stream to skip bytes from
offset	number of bytes to skip

Returns

0 on success, -1 else

g3d_stream_seek ()

gint
g3d_stream_seek (G3DStream *stream,
                 goffset offset,
                 GSeekType whence);

Moves around the current position in the stream.

Parameters

stream	stream to seek in
offset	number of bytes to seek
whence	seek type

Returns

0 on success, -1 else

g3d_stream_tell ()

goffset
g3d_stream_tell (G3DStream *stream);

Tells the current position in the stream.

Parameters

stream

stream to get position from

Returns

current stream position

g3d_stream_size ()

goffset
g3d_stream_size (G3DStream *stream);

Get the size in bytes of a stream.

Parameters

stream

stream to get size from

Returns

size of stream in bytes

g3d_stream_eof ()

gboolean
g3d_stream_eof (G3DStream *stream);

Checks whether the stream has reached its end.

Parameters

stream

the stream

Returns

TRUE if no more data can be read, FALSE else.

g3d_stream_is_seekable ()

gboolean
g3d_stream_is_seekable (G3DStream *stream);

Get information whether it is possible to seek in a stream.

Parameters

stream

the stream

Returns

TRUE if seekable, FALSE else

g3d_stream_get_uri ()

gchar *
g3d_stream_get_uri (G3DStream *stream);

Get the URI of a stream

Parameters

stream

the stream

Returns

a non-NULL, zero-terminated string containing the URI of the string. This return value should not be freed.

g3d_stream_line ()

guint32
g3d_stream_line (G3DStream *stream);

Get the current line number from stream. This only works if line are consequently read with g3d_stream_read_line(), so it's only applicable for text streams.

Parameters

stream

stream to get line from

Returns

current line number, may be 0

g3d_stream_read ()

gsize
g3d_stream_read (G3DStream *stream,
                 gpointer ptr,
                 gsize size);

Reads a number of bytes from the stream.

Parameters

stream	the stream to read from
ptr	pointer to memory storage
size	number of bytes to read

Returns

number of bytes successfully read.

g3d_stream_read_line ()

gchar *
g3d_stream_read_line (G3DStream *stream,
                      gchar *buf,
                      gsize size);

Read a line (terminated by a newline character or end of file) from a stream.

Parameters

stream	stream to read a line from
buf	an allocated buffer to be filled
size	maximum length of line including terminating zero

Returns

the read line or NULL in case of an error.

g3d_stream_read_int8 ()

gint32
g3d_stream_read_int8 (G3DStream *stream);

Read a 1 byte signed integer from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_int16_be ()

gint32
g3d_stream_read_int16_be (G3DStream *stream);

Read a 2 byte big-endian signed integer from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_int16_le ()

gint32
g3d_stream_read_int16_le (G3DStream *stream);

Read a 2 byte little-endian signed integer from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_int32_be ()

gint32
g3d_stream_read_int32_be (G3DStream *stream);

Read a 4 byte big-endian signed integer from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_int32_le ()

gint32
g3d_stream_read_int32_le (G3DStream *stream);

Read a 4 byte little-endian signed integer from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_float_be ()

G3DFloat
g3d_stream_read_float_be (G3DStream *stream);

Read a 4 byte big-endian floating point number from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_float_le ()

G3DFloat
g3d_stream_read_float_le (G3DStream *stream);

Read a 4 byte little-endian floating point number from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_double_be ()

G3DDouble
g3d_stream_read_double_be (G3DStream *stream);

Read a 8 byte big-endian double-precision floating point number from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_double_le ()

G3DDouble
g3d_stream_read_double_le (G3DStream *stream);

Read a 8 byte little-endian double-precision floating point number from file.

Parameters

stream

the stream to read from

Returns

The read value, 0 in case of error

g3d_stream_read_cstr ()

gint32
g3d_stream_read_cstr (G3DStream *stream,
                      gchar *buffer,
                      gint32 max_len);

Read a string (terminated by '\0') from stream

Parameters

stream	the stream to read from
buffer	the buffer to fill
max_len	maximum number to read from stream

Returns

number of bytes read from stream

G3DStreamCloseFunc ()

gint
(*G3DStreamCloseFunc) (gpointer data);

Callback function for g3d_stream_close().

Parameters

data

opaque stream data

Returns

0 on success, -1 else.

G3DStreamEofFunc ()

gboolean
(*G3DStreamEofFunc) (gpointer data);

Callback function for g3d_stream_eof().

Parameters

data

opaque stream data

Returns

TRUE on stream end-of-file, FALSE else.

G3DStreamReadFunc ()

gsize
(*G3DStreamReadFunc) (gpointer ptr,
                      gsize size,
                      gpointer data);

Callback function for g3d_stream_read().

Parameters

ptr	buffer to read bytes into
size	number of bytes to read
data	opaque stream data

Returns

number of bytes actually read.

G3DStreamReadLineFunc ()

gchar *
(*G3DStreamReadLineFunc) (gchar *buf,
                          gsize size,
                          gpointer data);

Callback function for g3d_stream_read_line().

Parameters

buf	buffer to read bytes into
size	maximum size of buffer
data	opaque stream data

Returns

The line buffer or NULL in case of an error.

G3DStreamSeekFunc ()

gint
(*G3DStreamSeekFunc) (gpointer data,
                      goffset offset,
                      GSeekType whence);

Callback function for g3d_stream_seek().

Parameters

data	opaque stream data
offset	seek offset
whence	seek type

Returns

0 on success, -1 else.

G3DStreamSizeFunc ()

goffset
(*G3DStreamSizeFunc) (gpointer data);

Callback function for g3d_stream_size().

Parameters

data

opaque stream data

Returns

size of stream.

G3DStreamTellFunc ()

goffset
(*G3DStreamTellFunc) (gpointer data);

Callback function for g3d_stream_tell().

Parameters

data

opaque stream data

Returns

current stream position.

Types and Values

G3DStream

typedef struct {
} G3DStream;

An abstraction of input handling.