ObjFW  Diff

 * read returned 0 bytes - some streams do internal processing that has a
 * result of 0 bytes.
 *
 * @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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (size_t)readIntoBuffer: (void *)buffer length: (size_t)length;

/**
 * @brief Reads exactly the specified `length` bytes from the stream into a
 *	  buffer.
 *
 * Unlike @ref readIntoBuffer:length:, 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 *at least* this big!
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
 - (void)readIntoBuffer: (void *)buffer exactLength: (size_t)length;

#ifdef OF_HAVE_SOCKETS
/**
 * @brief Asynchronously reads *at most* `length` bytes from the stream into a
 *	  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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (double)readBigEndianDouble;

/**
 * @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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (double)readLittleEndianDouble;

/**
 * @brief Reads the specified number of items with an item size of 1 from the
 *	  stream and returns them as OFData.
 *
 * @warning Only call this when you know that enough data is available!
 *	    Otherwise you will get an exception!
 *
 * @param count The number of items to read
 * @return OFData with count items.
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (OFData *)readDataWithCount: (size_t)count;

/**
 * @brief Reads the specified number of items with the specified item size from
 *	  the stream and returns them as OFData.
 *
 * @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 count The number of items to read
 * @return OFData with count items.
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (OFData *)readDataWithItemSize: (size_t)itemSize count: (size_t)count;

/**
 * @brief Returns OFData with all the remaining data of the stream.
 *
 * @return OFData with an item size of 1 with all the data of the stream until
 *	   the end of the stream is reached.
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (OFData *)readDataUntilEndOfStream;

/**
 * @brief Reads a string with the specified length from the stream.
 *
 * If `\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
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (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
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (OFString *)readStringWithLength: (size_t)length
			  encoding: (OFStringEncoding)encoding;

/**
 * @brief Reads 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.
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)readLine;

/**
 * @brief Reads 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.
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)readLineWithEncoding: (OFStringEncoding)encoding;

#ifdef OF_HAVE_SOCKETS
/**
 * @brief Asynchronously reads until a newline, `\0`, end of stream or an
 *	  exception occurs.

/**
 * @brief Tries to read a line from the stream (see @ref readLine) and returns
 *	  `nil` if no complete line has been received yet.
 *
 * @return The line that was read, autoreleased, or `nil` if the line is not
 *	   complete yet
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)tryReadLine;

/**
 * @brief Tries to read a line from the stream with the specified encoding (see
 *	  @ref readLineWithEncoding:) and returns `nil` if no complete line has
 *	  been received yet.
 *
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or `nil` if the line is not
 *	   complete yet
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)tryReadLineWithEncoding: (OFStringEncoding)encoding;

/**
 * @brief Reads 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.
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)readUntilDelimiter: (OFString *)delimiter;

/**
 * @brief Reads 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.
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)readUntilDelimiter: (OFString *)delimiter
				 encoding: (OFStringEncoding)encoding;

/**
 * @brief Tries to reads until the specified string or `\0` is found or the end
 *	  of stream (see @ref readUntilDelimiter:) and returns `nil` if not
 *	  enough data has been received yet.
 *
 * @param delimiter The delimiter
 * @return The line that was read, autoreleased, or `nil` if the end of the
 *	   stream has been reached.
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter;

/**
 * @brief Tries to read until the specified string or `\0` is found or the end
 *	  of stream occurs (see @ref readUntilDelimiter:encoding:) and returns
 *	  `nil` if not enough data has been received yet.
 *
 * @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.
 * @throw OFReadFailedException Reading failed
 * @throw OFInvalidEncodingException The string read from the stream has
 *				     invalid encoding
 * @throw OFNotOpenException The stream is not open
 */
- (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter
				    encoding: (OFStringEncoding)encoding;

/**
 * @brief Writes everything in the write buffer to the stream.
 *

 * being set to `EWOULDBLOCK` or `EAGAIN` (you need to check for both, as they
 * are not the same on some systems) and
 * @ref OFWriteFailedException#bytesWritten being set to the number of bytes
 * that were written, if any.
 *
 * @param buffer The buffer from which the data is written into the stream
 * @param length The length of the data that should be written
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeBuffer: (const void *)buffer length: (size_t)length;

#ifdef OF_HAVE_SOCKETS
/**
 * @brief Asynchronously writes data into the stream.
 *

/**
 * @brief Writes a uint8_t into the stream.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param int8 A uint8_t
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeInt8: (uint8_t)int8;

/**
 * @brief Writes a uint16_t into the stream, encoded in big endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param int16 A uint16_t
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeBigEndianInt16: (uint16_t)int16;

/**
 * @brief Writes a uint32_t into the stream, encoded in big endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param int32 A uint32_t
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeBigEndianInt32: (uint32_t)int32;

/**
 * @brief Writes a uint64_t into the stream, encoded in big endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param int64 A uint64_t
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeBigEndianInt64: (uint64_t)int64;

/**
 * @brief Writes a float into the stream, encoded in big endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param float_ A float
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeBigEndianFloat: (float)float_;

/**
 * @brief Writes a double into the stream, encoded in big endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param double_ A double
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeBigEndianDouble: (double)double_;

/**
 * @brief Writes a uint16_t into the stream, encoded in little endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param int16 A uint16_t
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeLittleEndianInt16: (uint16_t)int16;

/**
 * @brief Writes a uint32_t into the stream, encoded in little endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param int32 A uint32_t
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeLittleEndianInt32: (uint32_t)int32;

/**
 * @brief Writes a uint64_t into the stream, encoded in little endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param int64 A uint64_t
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeLittleEndianInt64: (uint64_t)int64;

/**
 * @brief Writes a float into the stream, encoded in little endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param float_ A float
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeLittleEndianFloat: (float)float_;

/**
 * @brief Writes a double into the stream, encoded in little endian.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param double_ A double
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeLittleEndianDouble: (double)double_;

/**
 * @brief Writes OFData into the stream.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param data The OFData to write into the stream
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeData: (OFData *)data;

/**
 * @brief Writes a string into the stream, without the trailing zero.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param string The string from which the data is written to the stream
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeString: (OFString *)string;

/**
 * @brief Writes a string into the stream in the specified encoding, without
 *	  the trailing zero.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param string The string from which the data is written to the stream
 * @param encoding The encoding in which to write the string to the stream
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeString: (OFString *)string encoding: (OFStringEncoding)encoding;

/**
 * @brief Writes a string into the stream with a trailing newline.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param string The string from which the data is written to the stream
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeLine: (OFString *)string;

/**
 * @brief Writes a string into the stream in the specified encoding with a
 *	  trailing newline.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param string The string from which the data is written to the stream
 * @param encoding The encoding in which to write the string to the stream
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (void)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding;

/**
 * @brief Writes a formatted string into the stream.
 *
 * See printf for the format syntax. As an addition, `%@` is available as
 * format specifier for objects, `%C` for `OFUnichar` and `%S` for
 * `const OFUnichar *`.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param format A string used as format
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 * @throw OFInvalidFormatException The specified format is invalid
 */
- (void)writeFormat: (OFConstantString *)format, ...;

/**
 * @brief Writes a formatted string into the stream.
 *
 * See printf for the format syntax. As an addition, `%@` is available as
 * format specifier for objects, `%C` for `OFUnichar` and `%S` for
 * `const OFUnichar *`.
 *
 * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:.
 *
 * @param format A string used as format
 * @param arguments The arguments used in the format string
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 * @throw OFInvalidFormatException The specified format is invalid
 */
- (void)writeFormat: (OFConstantString *)format arguments: (va_list)arguments;

#ifdef OF_HAVE_SOCKETS
/**
 * @brief Cancels all pending asynchronous requests on the stream.
 */

 */
- (void)unreadFromBuffer: (const void *)buffer length: (size_t)length;

/**
 * @brief Closes the stream.
 *
 * @note If you override this, make sure to call `[super close]`!
 *
 * @throw OFNotOpenException The stream is not open
 */
- (void)close;

/**
 * @brief Performs a lowlevel read.
 *
 * @warning Do not call this directly!
 *
 * @note Override this method with your actual read implementation when
 *	 subclassing!
 *
 * @param buffer The buffer for the data to read
 * @param length The length of the buffer
 * @return The number of bytes read
 * @throw OFReadFailedException Reading failed
 * @throw OFNotOpenException The stream is not open
 */
- (size_t)lowlevelReadIntoBuffer: (void *)buffer length: (size_t)length;

/**
 * @brief Performs a lowlevel write.
 *
 * @warning Do not call this directly!
 *
 * @note Override this method with your actual write implementation when
 *	 subclassing!
 *
 * @param buffer The buffer with the data to write
 * @param length The length of the data to write
 * @return The number of bytes written
 * @throw OFWriteFailedException Writing failed
 * @throw OFNotOpenException The stream is not open
 */
- (size_t)lowlevelWriteBuffer: (const void *)buffer length: (size_t)length;

/**
 * @brief Returns whether the lowlevel is at the end of the stream.
 *
 * @warning Do not call this directly!