ObjFW  Diff

#import "OFString.h"

@class OFDataArray;

/**
 * \brief A base class for different types of streams.
 *
 * \warning Even though the OFCopying protocol is implemented, it does
 *	    <i>not</i> return an independant copy of the stream but instead
 *	    retains it.  This is so that the stream can be used as a key for a
 *	    dictionary so context can be associated with a stream. Using a
 *	    stream in more than one thread at the same time is not thread-safe,
 *	    even if copy was called!
 *
 * \warning If you want to subclass this, override _readNBytes:intoBuffer:,
 *	    _writeNBytes:fromBuffer: and _isAtEndOfStream, but nothing else.
 *	    Those are not defined in the headers, but do the actual work.
 *	    OFStream uses those and does all the caching and other stuff. If
 *	    you override these methods without the _ prefix, you *WILL* break
 *	    caching and get broken results!
 */
@interface OFStream: OFObject <OFCopying>
{
	char   *cache;
	char   *writeBuffer;
	size_t cacheLength, writeBufferLength;
	BOOL   buffersWrites;

 * \brief Reads exactly the specified length bytes from the stream into a
 *	  buffer.
 *
 * Unlike readNBytes:intoBuffer:, this method does not return when less than the
 * specified length has been read - instead, it waits until it got exactly the
 * specified length.
 *
 * \warning Only call this when you know that specified amount of data is
 *	    available! Otherwise you will get an exception!
 *
 * \param buffer The buffer into which the data is read
 * \param length The length of the data that should be read.
 *	       The buffer MUST be EXACTLY this big!
 */
- (void)readExactlyNBytes: (size_t)length
	       intoBuffer: (void*)buffer;

/**
 * \brief Reads a uint8_t from the stream.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A uint8_t from the stream
 */
- (uint8_t)readInt8;

/**
 * \brief Reads a uint16_t from the stream which is encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A uint16_t from the stream in native endianess
 */
- (uint16_t)readBigEndianInt16;

/**
 * \brief Reads a uint32_t from the stream which is encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A uint32_t from the stream in the native endianess
 */
- (uint32_t)readBigEndianInt32;

/**
 * \brief Reads a uint64_t from the stream which is encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A uint64_t from the stream in the native endianess
 */
- (uint64_t)readBigEndianInt64;

/**
 * \brief Reads a float from the stream which is encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A float from the stream in the native endianess
 */
- (float)readBigEndianFloat;

/**
 * \brief Reads a double from the stream which is encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A double from the stream in the native endianess
 */
- (double)readBigEndianDouble;

/**
 * \brief Reads the specified number of uint16_ts from the stream which are
 *	  encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nInt16s The number of uint16_ts to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 uint16_ts
 * \return The number of bytes read
 */
- (size_t)readNBigEndianInt16s: (size_t)nInt16s
		    intoBuffer: (uint16_t*)buffer;

/**
 * \brief Reads the specified number of uint32_ts from the stream which are
 *	  encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nInt32s The number of uint32_ts to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 uint32_ts
 * \return The number of bytes read
 */
- (size_t)readNBigEndianInt32s: (size_t)nInt32s
		    intoBuffer: (uint32_t*)buffer;

/**
 * \brief Reads the specified number of uint64_ts from the stream which are
 *	  encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nInt64s The number of uint64_ts to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 uint64_ts
 * \return The number of bytes read
 */
- (size_t)readNBigEndianInt64s: (size_t)nInt64s
		    intoBuffer: (uint64_t*)buffer;

/**
 * \brief Reads the specified number of floats from the stream which are encoded
 *	  in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nFloatss The number of floats to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 floats
 * \return The number of bytes read
 */
- (size_t)readNBigEndianFloats: (size_t)nFloats
		    intoBuffer: (float*)buffer;

/**
 * \brief Reads the specified number of doubles from the stream which are
 *	  encoded in big endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nDoubles The number of doubles to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 doubles
 * \return The number of bytes read
 */
- (size_t)readNBigEndianDoubles: (size_t)nDoubles
		     intoBuffer: (double*)buffer;

/**
 * \brief Reads a uint16_t from the stream which is encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A uint16_t from the stream in native endianess
 */
- (uint16_t)readLittleEndianInt16;

/**
 * \brief Reads a uint32_t from the stream which is encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A uint32_t from the stream in the native endianess
 */
- (uint32_t)readLittleEndianInt32;

/**
 * \brief Reads a uint64_t from the stream which is encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A uint64_t from the stream in the native endianess
 */
- (uint64_t)readLittleEndianInt64;

/**
 * \brief Reads a float from the stream which is encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A float from the stream in the native endianess
 */
- (float)readLittleEndianFloat;

/**
 * \brief Reads a double from the stream which is encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \return A double from the stream in the native endianess
 */
- (double)readLittleEndianDouble;

/**
 * \brief Reads the specified number of uint16_ts from the stream which are
 *	  encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nInt16s The number of uint16_ts to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 uint16_ts
 * \return The number of bytes read
 */
- (size_t)readNLittleEndianInt16s: (size_t)nInt16s
		       intoBuffer: (uint16_t*)buffer;

/**
 * \brief Reads the specified number of uint32_ts from the stream which are
 *	  encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nInt32s The number of uint32_ts to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 uint32_ts
 * \return The number of bytes read
 */
- (size_t)readNLittleEndianInt32s: (size_t)nInt32s
		       intoBuffer: (uint32_t*)buffer;

/**
 * \brief Reads the specified number of uint64_ts from the stream which are
 *	  encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nInt64s The number of uint64_ts to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 uint64_ts
 * \return The number of bytes read
 */
- (size_t)readNLittleEndianInt64s: (size_t)nInt64s
		       intoBuffer: (uint64_t*)buffer;

/**
 * \brief Reads the specified number of floats from the stream which are
 *	  encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nFloats The number of floats to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 floats
 * \return The number of bytes read
 */
- (size_t)readNLittleEndianFloats: (size_t)nFloats
		       intoBuffer: (float*)buffer;

/**
 * \brief Reads the specified number of doubles from the stream which are
 *	  encoded in little endian.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nDoubles The number of doubles to read
 * \param buffer A buffer of sufficient size to store the specified number of
 *		 doubles
 * \return The number of bytes read
 */
- (size_t)readNLittleEndianDoubles: (size_t)nDoubles
			intoBuffer: (double*)buffer;

/**
 * \brief Reads the specified number of items with an item size of 1 from the
 *	  stream and returns them in an OFDataArray.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param nItems The number of items to read
 * \return An OFDataArray with at nItems items.
 */
- (OFDataArray*)readDataArrayWithNItems: (size_t)nItems;

/**
 * \brief Reads the specified number of items with the specified item size from
 *	  the stream and returns them in an OFDataArray.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param itemSize The size of each item
 * \param nItems The number of items to read
 * \return An OFDataArray with at nItems items.
 */
- (OFDataArray*)readDataArrayWithItemSize: (size_t)itemSize

 * \brief Reads a string with the specified length from the stream.
 *
 * If a \\0 appears in the stream, the string will be truncated at the \\0 and
 * the rest of the bytes of the string will be lost. This way, reading from the
 * stream will not break because of a \\0 because the specified number of bytes
 * is still being read and only the string gets truncated.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param length The length (in bytes) of the string to read from the stream
 * \return A string with the specified length
 */
- (OFString*)readStringWithLength: (size_t)length;

/**
 * \brief Reads a string with the specified encoding and length from the stream.
 *
 * If a \\0 appears in the stream, the string will be truncated at the \\0 and
 * the rest of the bytes of the string will be lost. This way, reading from the
 * stream will not break because of a \\0 because the specified number of bytes
 * is still being read and only the string gets truncated.
 *
 * \warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * \param encoding The encoding of the string to read from the stream
 * \param length The length (in bytes) of the string to read from the stream
 * \return A string with the specified length
 */
- (OFString*)readStringWithEncoding: (of_string_encoding_t)encoding