stream 3 LIBG3D Library stream I/O abstraction layer for plugins #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); 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. G3DStreamtypedef struct { } G3DStream; An abstraction of input handling. g3d_stream_open_fileG3DStream* 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_fileG3DStream* 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_streamG3DStream* 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_zipG3DStream* 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_streamG3DStream* 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_streamG3DStream* 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_bufferG3DStream* 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_streamG3DStream* 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_customG3DStream* 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_closegint g3d_stream_close (G3DStream *stream); Closes an open stream. stream : the stream Returns : 0 on success. g3d_stream_skipgint 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_seekgint 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_tellgoffset g3d_stream_tell (G3DStream *stream); Tells the current position in the stream. stream : stream to get position from Returns : current stream position g3d_stream_sizegoffset 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_eofgboolean 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_seekablegboolean 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_urigchar* 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_lineguint32 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_readgsize 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_linegchar* 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_int8gint32 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_begint32 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_legint32 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_begint32 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_legint32 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_beG3DFloat 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_leG3DFloat 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_beG3DDouble 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_leG3DDouble 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_cstrgint32 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 G3DStreamCloseFuncgint (*G3DStreamCloseFunc) (gpointer data); Callback function for g3d_stream_close(). data : opaque stream data Returns : 0 on success, -1 else. G3DStreamEofFuncgboolean (*G3DStreamEofFunc) (gpointer data); Callback function for g3d_stream_eof(). data : opaque stream data Returns : TRUE on stream end-of-file, FALSE else. G3DStreamReadFuncgsize (*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. G3DStreamReadLineFuncgchar* (*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. G3DStreamSeekFuncgint (*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. G3DStreamSizeFuncgoffset (*G3DStreamSizeFunc) (gpointer data); Callback function for g3d_stream_size(). data : opaque stream data Returns : size of stream. G3DStreamTellFuncgoffset (*G3DStreamTellFunc) (gpointer data); Callback function for g3d_stream_tell(). data : opaque stream data Returns : current stream position. G3DStream