diff options
Diffstat (limited to 'src/lib/string_stream.h')
| -rwxr-xr-x | src/lib/string_stream.h | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/src/lib/string_stream.h b/src/lib/string_stream.h new file mode 100755 index 0000000..939489c --- /dev/null +++ b/src/lib/string_stream.h @@ -0,0 +1,253 @@ +#ifndef __STRING_STREAM_H__ +#define __STRING_STREAM_H__ + +// $Id: string_stream.h,v 1.2 2014/02/03 01:30:25 daviddu Exp $ +// $Source: /afs/awd/projects/eclipz/KnowledgeBase/.cvsroot/eclipz/chips/p8/working/procedures/lib/string_stream.h,v $ +//----------------------------------------------------------------------------- +// *! (C) Copyright International Business Machines Corp. 2013 +// *! All Rights Reserved -- Property of IBM +// *! *** IBM Confidential *** +//----------------------------------------------------------------------------- + +/// \file string_stream.h +/// \brief Implementations of string streams. + +#include "ssx_io.h" + +/// A string stream +/// +/// This structure is used for the public CircularStream and WrappingStream +/// types, as well as for the library-internal types used to implement +/// sprintf() and snprintf(). + +typedef struct { + + /// The base class + FILE stream; + + /// Data storage - provided by the creator + uint8_t *data; + + /// The size of the data storage + size_t size; + + /// The index of the next byte to write + size_t next_write; + + /// The index of the next byte to read + size_t next_read; + + /// Stream flags, see \ref string_stream_flags + int flags; + +} StringStream; + + +/// A StringStream with circular buffer semantics +/// +/// The swrite() method copies the input data to the stream buffer, which is +/// treated as a circular buffer. If the swrite() would overflow the buffer, +/// then as much data as possible is written and swrite returns -EAGAIN. In +/// all cases swrite() returns the number of bytes actually written to the +/// buffer. +/// +/// The sread() method copies data from the StringStream circular buffer to +/// the caller's buffer until either the caller's request is satisfied or all +/// of the immediately available data has been read from the buffer. If the +/// caller's request can not be immediately granted then as much data as +/// possible is copied and sread() returns -EAGAIN. In all cases sread() +/// returns the number of bytes actually read from the buffer. +/// +/// The fflush() method marks the buffer as empty, effectively losing any data +/// currently stored in the buffer. + +typedef StringStream CircularStream; + + +/// A StringStream with wrapping circular buffer semantics +/// +/// The swrite() method copies the input data to the stream buffer, which is +/// treated as a circular buffer. If the swrite() would overflow the buffer, +/// then unread data is overwritten with new data. If the size of the +/// swrite() exceeds the buffer length then the effect is simply to fill the +/// buffer with the final bytes of the caller's data. swrite() always returns +/// the number of bytes requested to be written. +/// +/// The sread() method copies data from the StringStream circular buffer to +/// the caller's buffer until either the caller's request is satisfied or all +/// of the immediately available data has been read from the buffer. If the +/// caller's request can not be immediately granted then as much data as +/// possible is copied and sread() returns -EAGAIN. In all cases sread() +/// returns the number of bytes actually read from the buffer. +/// +/// The fflush() method marks the buffer as empty, effectively losing any data +/// currently stored in the buffer. + +typedef StringStream WrappingStream; + + +/// Create a StringStream +/// +/// \param stream The StringStream to initialize +/// +/// \param buf The stream data buffer +/// +/// \param size The size of the data buffer in bytes +/// +/// \param flags Flags for FILE_create() +/// +/// \param swrite The function to be installed as the swrite() function for +/// the underlying FILE object. The sread() and fflush() functions are fixed. +/// +/// This API initializes a StringStream structure for use in I/O operations. +/// This API will typically only be used by the creation functions of specific +/// StringStream types. +/// +/// \retval 0 Success +/// +/// \retval -STRING_STREAM_INVALID_ARGUMENT Either \a stream is NULL (0) +/// or \a buf is NULL(0) and \a size is non-0. + +int +_string_stream_create(StringStream* stream, + void* buf, size_t size, int flags, + int (*swrite)(FILE* stream, + const void* buf, + size_t size, + size_t* written)); + +/// Create a CircularStream +/// +/// \param stream The CircularStream to initialize +/// +/// \param buf The stream data buffer +/// +/// \param size The size of the data buffer in bytes +/// +/// \param flags Flags for FILE_create() +/// +/// This API initializes a CircularStream structure for use in I/O +/// operations. Once created, the pointer to the CircularStream stream can be +/// cast to a FILE* and used for sread(), swrite(), fflush() and fprintf() +/// operations. +/// +/// \retval 0 Success +/// +/// \retval -STRING_STREAM_INVALID_ARGUMENT Either \a stream is NULL (0) +/// or \a buf is NULL(0) and \a size is non-0. + +int +circular_stream_create(CircularStream* stream, + void* buf, size_t size, int flags); + + +/// Create a WrappingStream +/// +/// \param stream The WrappingStream to initialize +/// +/// \param buf The stream data buffer +/// +/// \param size The size of the data buffer in bytes +/// +/// \param flags Flags for FILE_create() +/// +/// This API initializes a WrappingStream structure for use in I/O +/// operations. Once created, the pointer to the WrappingStream stream can be +/// cast to a FILE* and used for sread(), swrite(), fflush() and fprintf() +/// operations. +/// +/// \retval 0 Success +/// +/// \retval -STRING_STREAM_INVALID_ARGUMENT Either \a stream is NULL (0) +/// or \a buf is NULL(0) and \a size is non-0. + +int +wrapping_stream_create(CircularStream* stream, + void* buf, size_t size, int flags); + + +/// Create a LinearStream +/// +/// \param stream The LinearStream to initialize +/// +/// \param buf The stream data buffer +/// +/// \param size The size of the data buffer in bytes +/// +/// \param flags Flags for FILE_create() +/// +/// This API initializes a LinearStream structure for use in I/O +/// operations. Once created, the pointer to the WrappingStream stream can be +/// cast to a FILE* and used for sread(), swrite(), fflush() and fprintf() +/// operations. +/// +/// \retval 0 Success +/// +/// \retval -STRING_STREAM_INVALID_ARGUMENT Either \a stream is NULL (0) +/// or \a buf is NULL(0) and \a size is non-0. + + +int +linear_stream_create(CircularStream* stream, + void* buf, size_t size, int flags); + + +/// A StringStream used as a read-only input stream +/// +/// This is a CircualarStream created with a full buffer and without a write +/// method. It uses a special read method that returns EOF once the buffer is +/// empty rather than -EAGAIN. + +typedef StringStream InputStream; + + +/// Create an InputStream +/// +/// \param stream The InputStream to initialize +/// +/// \param buf The stream data buffer. +/// +/// \param size The size of the readable portion of the data buffer in bytes +/// +/// \param flags Flags for FILE_create() +/// +/// This API initializes an InputStream structure for use in input operations. +/// The stream data buffer contains \a size bytes of data which can be read. +/// Once created, the pointer to the InputStream stream can be cast to a FILE* +/// and used for sread(), fgetc() and ungetc() operations. Neither fflush() +/// nor swrite() are supported on this class of stream. The read operations +/// will succeed until \a size bytes have been returned from the stream, at +/// which point the stream will return EOF on any subsequent reads. +/// +/// \retval 0 Success +/// +/// \retval -STRING_STREAM_INVALID_ARGUMENT Either \a stream is NULL (0) +/// or \a buf is NULL(0) and \a size is non-0. + +int +input_stream_create(InputStream* stream, + void* buf, size_t size, int flags); + + +/// \defgroup string_stream_flags StringStream Flags +/// +/// @{ + +/// The StringStream is full +#define STRING_STREAM_FULL 0x1 + +/// @} + + +/// \defgroup string_stream_codes StringStream Error/Panic Codes +/// +/// @{ + +/// A bug was detected in a StringStream function +#define STRING_STREAM_BUG 0x00787701 +#define STRING_STREAM_INVALID_ARGUMENT 0x00787702 + +/// @} + + +#endif // __STRING_STREAM_H__ |
