gmio/src/gmio_core/stream.h

136 lines
4.9 KiB
C
Raw Normal View History

2015-03-03 00:38:33 +08:00
/****************************************************************************
**
** GeomIO Library
** Copyright FougSys (2 Mar. 2015)
** contact@fougsys.fr
**
** This software is a reusable library whose purpose is to provide complete
** I/O support for various CAD file formats (eg. STL)
**
** This software is governed by the CeCILL-B license under French law and
** abiding by the rules of distribution of free software. You can use,
** modify and/ or redistribute the software under the terms of the CeCILL-B
** license as circulated by CEA, CNRS and INRIA at the following URL
** "http://www.cecill.info".
**
****************************************************************************/
#ifndef GMIO_STREAM_H
#define GMIO_STREAM_H
2013-01-16 00:56:24 +08:00
#include "global.h"
#include <stdio.h>
GMIO_C_LINKAGE_BEGIN
2014-11-21 18:39:23 +08:00
/*! \brief Stream that can get input from an arbitrary data source or can write
* output to an arbitrary data sink.
*
* It can be seen as generalization of the standard \c FILE*, and is pretty
* much the same as [custom streams]
* (http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams)
* in the GNU C Library
*
* It uses a cookie being basically an opaque pointer on a hidden data type.\n
* The custom stream is implemented by defining hook functions that know how
* to read/write the data.
2014-01-21 17:51:23 +08:00
*/
struct gmio_stream
{
2015-03-03 17:35:36 +08:00
/*! \brief Opaque pointer on the user stream, passed as first argument to
2014-11-21 18:39:23 +08:00
* hook functions */
2015-03-03 17:35:36 +08:00
void* cookie;
2014-01-21 17:51:23 +08:00
2015-03-03 17:35:36 +08:00
/*! \brief Pointer on a function that checks end-of-stream indicator
2014-11-21 18:39:23 +08:00
*
* Checks whether the end-of-stream indicator associated with stream
* pointed by \p cookie is set, returning GMIO_TRUE if is.
*
* The function should behaves like C standard [feof()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/feof.html)
*/
2015-03-03 17:35:36 +08:00
gmio_bool_t (*at_end_func)(void* cookie);
2015-03-03 17:35:36 +08:00
/*! \brief Pointer on a function that checks error indicator
2014-11-21 18:39:23 +08:00
*
* Checks if the error indicator associated with stream pointed by \p cookie
* is set, returning a value different from zero if it is.
*
* The function should behaves like C standard [ferror()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/ferror.html)
*/
2015-03-03 17:35:36 +08:00
int (*error_func)(void* cookie);
2014-11-21 18:39:23 +08:00
2015-03-03 17:35:36 +08:00
/*! \brief Pointer on a function that reads block of data from stream
2014-11-21 18:39:23 +08:00
*
* \details Reads an array of \p count elements, each one with a size of \p size
* bytes, from the stream pointed by \p cookie and stores them in the block
* of memory specified by \p ptr
*
* The function should behaves like C standard [fread()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/fread.html)
*
* \returns The total number of elements successfully read
*/
2015-03-03 17:35:36 +08:00
size_t (*read_func)(void* cookie, void* ptr, size_t size, size_t count);
2014-11-21 18:39:23 +08:00
2015-03-03 17:35:36 +08:00
/*! \brief Pointer on a function that writes block of data to stream
2014-11-21 18:39:23 +08:00
*
* \details Writes an array of \p count elements, each one with a size of \p size
* bytes, from the block of memory pointed by \p ptr to the current position
* in the stream pointed by \p cookie
*
* The function should behaves like C standard [fwrite()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/fwrite.html)
*
* \returns The total number of elements successfully written
*/
2015-03-03 17:35:36 +08:00
size_t (*write_func)(void* cookie, const void* ptr, size_t size, size_t count);
};
typedef struct gmio_stream gmio_stream_t;
2013-03-27 20:00:48 +08:00
/* Initialization */
2014-11-21 18:39:23 +08:00
/*! \brief Installs a null stream */
GMIO_LIB_EXPORT void gmio_stream_set_null(gmio_stream_t* stream);
2014-11-21 18:39:23 +08:00
/*! \brief Configures \p stream for standard FILE* (cookie will hold \p file) */
GMIO_LIB_EXPORT void gmio_stream_set_stdio(gmio_stream_t* stream, FILE* file);
/* Services */
2013-02-21 21:51:29 +08:00
2014-11-21 18:39:23 +08:00
/*! \brief Safe and convenient function for gmio_stream::at_end_func()
*
* Same as: \code stream->at_end_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT gmio_bool_t gmio_stream_at_end(gmio_stream_t* stream);
2013-02-21 21:51:29 +08:00
2014-11-21 18:39:23 +08:00
/*! \brief Safe and convenient function for gmio_stream::error_func()
*
* Same as: \code stream->error_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT int gmio_stream_error(gmio_stream_t* stream);
2013-02-21 21:51:29 +08:00
2014-11-21 18:39:23 +08:00
/*! \brief Safe and convenient function for gmio_stream::read_func()
*
* Same as: \code stream->read_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT size_t gmio_stream_read(gmio_stream_t* stream,
2013-02-21 21:51:29 +08:00
void* ptr,
size_t size,
size_t count);
2013-02-21 21:51:29 +08:00
2014-11-21 18:39:23 +08:00
/*! \brief Safe and convenient function for gmio_stream::write_func()
*
* Same as: \code stream->write_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT size_t gmio_stream_write(gmio_stream_t* stream,
2013-02-21 21:51:29 +08:00
const void* ptr,
size_t size,
size_t count);
2013-02-21 21:51:29 +08:00
GMIO_C_LINKAGE_END
#endif /* GMIO_STREAM_H */