/* * Copyright (c) 2008, 2009, 2010, 2011 * Jonathan Schleifer * * 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 #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 *writeBuffer; size_t cacheLength, writeBufferLength; 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 buffer The buffer into which the data is read * \param length The length of the data that should be read at most. * The buffer MUST be at least this big! * \return The number of bytes read */ - (size_t)readNBytes: (size_t)size intoBuffer: (char*)buffer; /** * Reads exactly 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 length * bytes. * * 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: (char*)buffer; /** * 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 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; /** * 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 items 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 buffer The buffer from which the data is written to the stream * \param length The length of the data that should be written * \return The number of bytes written */ - (size_t)writeNBytes: (size_t)length fromBuffer: (const char*)buffer; /** * 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 string The string from which the data is written to the stream * \return The number of bytes written */ - (size_t)writeString: (OFString*)string; /** * Writes a string into the stream with a trailing newline. * * \param string The string from which the data is written to the stream * \return The number of bytes written */ - (size_t)writeLine: (OFString*)string; /** * Writes a formatted string into the stream. * * \param format A string used as format * \return The number of bytes written */ - (size_t)writeFormat: (OFString*)format, ...; /** * Writes a formatted string into the stream. * * \param format A string used as format * \param arguments The arguments used in the format string * \return The number of bytes written */ - (size_t)writeFormat: (OFString*)format withArguments: (va_list)arguments; /** * \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