/*
* Copyright (c) 2008, 2009, 2010, 2011
* Jonathan Schleifer <js@webkeks.org>
*
* All rights reserved.
*
* This file is part of ObjFW. It may be distributed under the terms of the
* Q Public License 1.0, which can be found in the file LICENSE.QPL included in
* the packaging of this file.
*
* Alternatively, it may be distributed under the terms of the GNU General
* Public License, either version 2 or 3, which can be found in the file
* LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this
* file.
*/
#include <stdarg.h>
#import "OFObject.h"
#import "OFString.h"
@class OFDataArray;
/**
* \brief A base class for different types of streams.
*
* IMPORTANT: 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
{
char *cache;
char *wBuffer;
size_t cacheLen, wBufferLen;
BOOL buffersWrites;
BOOL isBlocking;
}
#ifdef OF_HAVE_PROPERTIES
@property (assign, setter=setBlocking:) BOOL isBlocking;
#endif
/**
* Returns a boolean whether the end of the stream has been reached.
*
* \return A boolean whether the end of the stream has been reached
*/
- (BOOL)isAtEndOfStream;
/**
* Reads at most size bytes from the stream into a buffer.
*
* \param buf The buffer into which the data is read
* \param size The size of the data that should be read at most.
* The buffer MUST be at least size big!
* \return The number of bytes read
*/
- (size_t)readNBytes: (size_t)size
intoBuffer: (char*)buf;
/**
* Reads exactly size bytes from the stream into a buffer. Unlike
* readNBytes:intoBuffer:, this method does not return when less than the
* specified size has been read - instead, it waits until it got exactly size
* bytes.
*
* WARNING: Only call this when you know that specified amount of data is
* available! Otherwise you will get an exception!
*
* \param buf The buffer into which the data is read
* \param size The size of the data that should be read.
* The buffer MUST be EXACTLY this big!
*/
- (void)readExactlyNBytes: (size_t)size
intoBuffer: (char*)buf;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* Reads nitems 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 iteams to read
* \return An OFDataArray with at nitems items.
*/
- (OFDataArray*)readDataArrayWithItemSize: (size_t)itemsize
andNItems: (size_t)nitems;
/**
* \return An OFDataArray with an item size of 1 with all the data of the
* stream until the end of the stream is reached.
*/
- (OFDataArray*)readDataArrayTillEndOfStream;
/**
* Read until a newline, \\0 or end of stream occurs.
*
* \return The line that was read, autoreleased, or nil if the end of the
* stream has been reached.
*/
- (OFString*)readLine;
/**
* Read with the specified encoding until a newline, \\0 or end of stream
* occurs.
*
* \param encoding The encoding used by the stream
* \return The line that was read, autoreleased, or nil if the end of the
* stream has been reached.
*/
- (OFString*)readLineWithEncoding: (of_string_encoding_t)encoding;
/**
* Read until the specified string or \\0 is found or the end of stream occurs.
*
* \param delimiter The delimiter
* \return The line that was read, autoreleased, or nil if the end of the
* stream has been reached.
*/
- (OFString*)readTillDelimiter: (OFString*)delimiter;
/**
* Read until the specified string or \\0 is found or the end of stream occurs.
*
* \param delimiter The delimiter
* \param encoding The encoding used by the stream
* \return The line that was read, autoreleased, or nil if the end of the
* stream has been reached.
*/
- (OFString*)readTillDelimiter: (OFString*)delimiter
withEncoding: (of_string_encoding_t)encoding;
/**
* \return A boolean whether writes are buffered
*/
- (BOOL)buffersWrites;
/**
* Enables or disables the write buffer.
*
* \param enable Whether the write buffer should be enabled or disabled
*/
- (void)setBuffersWrites: (BOOL)enable;
/**
* Writes everythig in the write buffer to the stream.
*/
- (void)flushWriteBuffer;
/**
* Writes from a buffer into the stream.
*
* \param buf The buffer from which the data is written to the stream
* \param size The size of the data that should be written
* \return The number of bytes written
*/
- (size_t)writeNBytes: (size_t)size
fromBuffer: (const char*)buf;
/**
* Writes a uint8_t into the stream.
*
* \param int8 A uint8_t
*/
- (void)writeInt8: (uint8_t)int8;
/**
* Writes a uint16_t into the stream, encoded in big endian.
*
* \param int16 A uint16_t
*/
- (void)writeBigEndianInt16: (uint16_t)int16;
/**
* Writes a uint32_t into the stream, encoded in big endian.
*
* \param int32 A uint32_t
*/
- (void)writeBigEndianInt32: (uint32_t)int32;
/**
* Writes a uint64_t into the stream, encoded in big endian.
*
* \param int64 A uint64_t
*/
- (void)writeBigEndianInt64: (uint64_t)int64;
/**
* Writes a uint16_t into the stream, encoded in little endian.
*
* \param int16 A uint16_t
*/
- (void)writeLittleEndianInt16: (uint16_t)int16;
/**
* Writes a uint32_t into the stream, encoded in little endian.
*
* \param int32 A uint32_t
*/
- (void)writeLittleEndianInt32: (uint32_t)int32;
/**
* Writes a uint64_t into the stream, encoded in little endian.
*
* \param int64 A uint64_t
*/
- (void)writeLittleEndianInt64: (uint64_t)int64;
/**
* Writes from an OFDataArray into the stream.
*
* \param dataarray The OFDataArray to write into the stream
* \return The number of bytes written
*/
- (size_t)writeDataArray: (OFDataArray*)dataarray;
/**
* Writes a string into the stream, without the trailing zero.
*
* \param str The string from which the data is written to the stream
* \return The number of bytes written
*/
- (size_t)writeString: (OFString*)str;
/**
* Writes a string into the stream with a trailing newline.
*
* \param str The string from which the data is written to the stream
* \return The number of bytes written
*/
- (size_t)writeLine: (OFString*)str;
/**
* Writes a formatted string into the stream.
*
* \param fmt A string used as format
* \return The number of bytes written
*/
- (size_t)writeFormat: (OFString*)fmt, ...;
/**
* Writes a formatted string into the stream.
*
* \param fmt A string used as format
* \param args The arguments used in the format string
* \return The number of bytes written
*/
- (size_t)writeFormat: (OFString*)fmt
withArguments: (va_list)args;
/**
* \return The number of bytes still present in the internal cache.
*/
- (size_t)pendingBytes;
/**
* \return Whether the stream is in blocking mode
*/
- (BOOL)isBlocking;
/**
* Enables or disables non-blocking I/O.
*
* By default, a stream is in blocking mode.
* On Win32, this currently only works for sockets!
*
* \param enable Whether the stream should be blocking
*/
- (void)setBlocking: (BOOL)enable;
/**
* \return The file descriptor for the stream.
*/
- (int)fileDescriptor;
/**
* Closes the stream.
*/
- (void)close;
@end