## 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