stream

stream — I/O abstraction layer for plugins

Synopsis


#include <g3d/stream.h>

                    G3DStream;
G3DStream*          g3d_stream_open_file                (const gchar *filename,
                                                         const gchar *mode);
G3DStream*          g3d_stream_open_structured_file     (const gchar *filename,
                                                         const gchar *subfile);
G3DStream*          g3d_stream_open_structured_file_from_stream
                                                        (G3DStream *stream,
                                                         const gchar *subfile);
G3DStream*          g3d_stream_open_zip                 (const gchar *filename,
                                                         const gchar *subfile);
G3DStream*          g3d_stream_open_zip_from_stream     (G3DStream *stream,
                                                         const gchar *subfile);
G3DStream*          g3d_stream_open_gzip_from_stream    (G3DStream *stream);
G3DStream*          g3d_stream_from_buffer              (guint8 *buffer,
                                                         gsize size,
                                                         const gchar *title,
                                                         gboolean free_buffer);
G3DStream*          g3d_stream_zlib_inflate_stream      (G3DStream *stream,
                                                         gsize cmp_size);
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);
gint                g3d_stream_close                    (G3DStream *stream);
gint                g3d_stream_skip                     (G3DStream *stream,
                                                         goffset offset);
gint                g3d_stream_seek                     (G3DStream *stream,
                                                         goffset offset,
                                                         GSeekType whence);
goffset             g3d_stream_tell                     (G3DStream *stream);
goffset             g3d_stream_size                     (G3DStream *stream);
gboolean            g3d_stream_eof                      (G3DStream *stream);
gboolean            g3d_stream_is_seekable              (G3DStream *stream);
gchar*              g3d_stream_get_uri                  (G3DStream *stream);
guint32             g3d_stream_line                     (G3DStream *stream);
gsize               g3d_stream_read                     (G3DStream *stream,
                                                         gpointer ptr,
                                                         gsize size);
gchar*              g3d_stream_read_line                (G3DStream *stream,
                                                         gchar *buf,
                                                         gsize size);
gint32              g3d_stream_read_int8                (G3DStream *stream);
gint32              g3d_stream_read_int16_be            (G3DStream *stream);
gint32              g3d_stream_read_int16_le            (G3DStream *stream);
gint32              g3d_stream_read_int32_be            (G3DStream *stream);
gint32              g3d_stream_read_int32_le            (G3DStream *stream);
G3DFloat            g3d_stream_read_float_be            (G3DStream *stream);
G3DFloat            g3d_stream_read_float_le            (G3DStream *stream);
G3DDouble           g3d_stream_read_double_be           (G3DStream *stream);
G3DDouble           g3d_stream_read_double_le           (G3DStream *stream);
gint32              g3d_stream_read_cstr                (G3DStream *stream,
                                                         gchar *buffer,
                                                         gint32 max_len);
gint                (*G3DStreamCloseFunc)               (gpointer data);
gboolean            (*G3DStreamEofFunc)                 (gpointer data);
gsize               (*G3DStreamReadFunc)                (gpointer ptr,
                                                         gsize size,
                                                         gpointer data);
gchar*              (*G3DStreamReadLineFunc)            (gchar *buf,
                                                         gsize size,
                                                         gpointer data);
gint                (*G3DStreamSeekFunc)                (gpointer data,
                                                         goffset offset,
                                                         GSeekType whence);
goffset             (*G3DStreamSizeFunc)                (gpointer data);
goffset             (*G3DStreamTellFunc)                (gpointer data);

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.

Details

G3DStream

typedef struct {
} G3DStream;

An abstraction of input handling.

g3d_stream_open_file ()

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

Opens a file with the C stdio routines.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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().

data :

 opaque stream data

Returns :

 0 on success, -1 else.

G3DStreamEofFunc ()

gboolean            (*G3DStreamEofFunc)                 (gpointer data);

Callback function for g3d_stream_eof().

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().

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().

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().

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().

data :

 opaque stream data

Returns :

 size of stream.

G3DStreamTellFunc ()

goffset             (*G3DStreamTellFunc)                (gpointer data);

Callback function for g3d_stream_tell().

data :

 opaque stream data

Returns :

 current stream position.

See Also

G3DStream
Generated by GTK-Doc V1.10