@@ -242,10 +242,12 @@ * * @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 @@ -259,10 +261,12 @@ * 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 /** @@ -471,10 +475,12 @@ * * @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. @@ -481,10 +487,12 @@ * * @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. @@ -491,10 +499,12 @@ * * @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. @@ -501,10 +511,12 @@ * * @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. @@ -511,10 +523,12 @@ * * @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. @@ -521,10 +535,12 @@ * * @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. @@ -531,10 +547,12 @@ * * @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. @@ -541,10 +559,12 @@ * * @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. @@ -551,10 +571,12 @@ * * @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. @@ -561,10 +583,12 @@ * * @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. @@ -571,10 +595,12 @@ * * @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 @@ -583,10 +609,12 @@ * @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 @@ -596,18 +624,22 @@ * 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. @@ -620,10 +652,14 @@ * @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. @@ -637,19 +673,27 @@ * 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 @@ -656,10 +700,14 @@ * 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 /** @@ -753,10 +801,14 @@ * @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 @@ -764,10 +816,14 @@ * 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 @@ -774,10 +830,14 @@ * 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 @@ -785,10 +845,14 @@ * * @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; /** @@ -797,10 +861,14 @@ * 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 @@ -809,10 +877,14 @@ * * @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; /** @@ -834,10 +906,12 @@ * @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 /** @@ -991,118 +1065,144 @@ * @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 @@ -1110,19 +1210,23 @@ * * 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 @@ -1130,10 +1234,12 @@ * * 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. @@ -1143,10 +1249,13 @@ * `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. @@ -1157,10 +1266,13 @@ * * 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 /** @@ -1194,10 +1306,12 @@ /** * @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. @@ -1208,10 +1322,12 @@ * 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. @@ -1222,10 +1338,12 @@ * 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.