Index: src/OFFile.h ================================================================== --- src/OFFile.h +++ src/OFFile.h @@ -60,10 +60,11 @@ * `w+` | Read-write, create or truncate * `w+x` | Read-write, create or fail, exclusive * `a` | Write-only, create or append * `a+` | Read-write, create or append * @return A new autoreleased OFFile + * @throw OFOpenItemFailedException Opening the file failed */ + (instancetype)fileWithPath: (OFString *)path mode: (OFString *)mode; /** * @brief Creates a new OFFile with the specified native file handle. @@ -94,10 +95,11 @@ * `a` | write-only, create, append * `ab` | write-only, create, append, binary * `a+` | read-write, create, append * `ab+` or `a+b` | read-write, create, append, binary * @return An initialized OFFile + * @throw OFOpenItemFailedException Opening the file failed */ - (instancetype)initWithPath: (OFString *)path mode: (OFString *)mode; /** * @brief Initializes an already allocated OFFile. Index: src/OFKernelEventObserver.h ================================================================== --- src/OFKernelEventObserver.h +++ src/OFKernelEventObserver.h @@ -166,10 +166,12 @@ * * If there is an @ref observe call blocking, it will be canceled. The reason * for this is to prevent blocking even though the newly added object is ready. * * @param object The object to observe for reading + * @throw OFObserveKernelEventsFailedException Adding the object for observing + * failed */ - (void)addObjectForReading: (id )object; /** * @brief Adds an object to observe for writing. @@ -176,10 +178,12 @@ * * If there is an @ref observe call blocking, it will be canceled. The reason * for this is to prevent blocking even though the newly added object is ready. * * @param object The object to observe for writing + * @throw OFObserveKernelEventsFailedException Adding the object for observing + * failed */ - (void)addObjectForWriting: (id )object; /** * @brief Removes an object to observe for reading. @@ -186,10 +190,12 @@ * * If there is an @ref observe call blocking, it will be canceled. The reason * for this is to prevent the removed object from still being observed. * * @param object The object to remove from observing for reading + * @throw OFObserveKernelEventsFailedException Removing the object for observing + * failed */ - (void)removeObjectForReading: (id )object; /** * @brief Removes an object to observe for writing. @@ -196,31 +202,37 @@ * * If there is an @ref observe call blocking, it will be canceled. The reason * for this is to prevent the removed object from still being observed. * * @param object The object to remove from observing for writing + * @throw OFObserveKernelEventsFailedException Removing the object for observing + * failed */ - (void)removeObjectForWriting: (id )object; /** * @brief Observes all objects and blocks until an event happens on an object. + * + * @throw OFObserveKernelEventsFailedException Observing for kernel events failed */ - (void)observe; /** * @brief Observes all objects until an event happens on an object or the * timeout is reached. * * @param timeInterval The time to wait for an event, in seconds + * @throw OFObserveKernelEventsFailedException Observing for kernel events failed */ - (void)observeForTimeInterval: (OFTimeInterval)timeInterval; /** * @brief Observes all objects until an event happens on an object or the * specified date is reached. * * @param date The until which to observe + * @throw OFObserveKernelEventsFailedException Observing for kernel events failed */ - (void)observeUntilDate: (OFDate *)date; /** * @brief Cancels the currently blocking observe call. Index: src/OFSeekableStream.h ================================================================== --- src/OFSeekableStream.h +++ src/OFSeekableStream.h @@ -76,10 +76,12 @@ * @brief Seeks to the specified offset. * * @param offset The offset in bytes * @param whence From where to seek. * @return The new offset form the start of the file + * @throw OFSeekFailedException Seeking failed + * @throw OFNotOpenException The stream is not open */ - (OFStreamOffset)seekToOffset: (OFStreamOffset)offset whence: (OFSeekWhence)whence; /** @@ -91,11 +93,13 @@ * subclassing! * * @param offset The offset to seek to * @param whence From where to seek. * @return The new offset from the start of the file + * @throw OFSeekFailedException Seeking failed + * @throw OFNotOpenException The stream is not open */ - (OFStreamOffset)lowlevelSeekToOffset: (OFStreamOffset)offset whence: (OFSeekWhence)whence; @end OF_ASSUME_NONNULL_END Index: src/OFStream.h ================================================================== --- src/OFStream.h +++ src/OFStream.h @@ -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.