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

## See Also

G3DStream