Index: src/OFLHAArchive.h ================================================================== --- src/OFLHAArchive.h +++ src/OFLHAArchive.h @@ -44,20 +44,10 @@ /** * @brief The encoding to use for the archive. Defaults to ISO 8859-1. */ @property (nonatomic) OFStringEncoding encoding; -/** - * @brief A stream for reading the current entry. - * - * @note This is only available in read mode. - * - * @note The returned stream conforms to @ref OFReadyForReadingObserving if the - * underlying stream does so, too. - */ -@property (readonly, nonatomic) OFStream *streamForReadingCurrentEntry; - /** * @brief Creates a new OFLHAArchive object with the specified stream. * * @param stream A stream from which the LHA archive will be read. * For read and append mode, this needs to be an OFSeekableStream. @@ -137,10 +127,22 @@ * unsupported version * @throw OFTruncatedDataException The archive was truncated */ - (nullable OFLHAArchiveEntry *)nextEntry; +/** + * @brief Returns a stream for reading the current entry. + * + * @note This is only available in read mode. + * + * @note The returned stream conforms to @ref OFReadyForReadingObserving if the + * underlying stream does so, too. + * + * @return A stream for reading the current entry + */ +- (FStream *)streamForReadingCurrentEntry; + /** * @brief Returns a stream for writing the specified entry. * * @note This is only available in write and append mode. * @@ -161,10 +163,12 @@ */ - (OFStream *)streamForWritingEntry: (OFLHAArchiveEntry *)entry; /** * @brief Closes the OFLHAArchive. + * + * @throw OFNotOpenException The archive is not open */ - (void)close; @end OF_ASSUME_NONNULL_END Index: src/OFTarArchive.h ================================================================== --- src/OFTarArchive.h +++ src/OFTarArchive.h @@ -48,29 +48,22 @@ /** * @brief The encoding to use for the archive. Defaults to UTF-8. */ @property (nonatomic) OFStringEncoding encoding; -/** - * @brief A stream for reading the current entry. - * - * @note This is only available in read mode. - * - * @note The returned stream conforms to @ref OFReadyForReadingObserving if the - * underlying stream does so, too. - */ -@property (readonly, nonatomic) OFStream *streamForReadingCurrentEntry; - /** * @brief Creates a new OFTarArchive object with the specified stream. * * @param stream A stream from which the tar archive will be read. * For append mode, this needs to be an OFSeekableStream. * @param mode The mode for the tar file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return A new, autoreleased OFTarArchive + * @throw OFInvalidFormatException The archive has an invalid format + * @throw OFSeekFailedException The archive was open in append mode and seeking + * failed */ + (instancetype)archiveWithStream: (OFStream *)stream mode: (OFString *)mode; /** * @brief Creates a new OFTarArchive object with the specified file. @@ -78,10 +71,13 @@ * @param URI The URI to the tar archive * @param mode The mode for the tar file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return A new, autoreleased OFTarArchive + * @throw OFInvalidFormatException The archive has an invalid format + * @throw OFSeekFailedException The archive was open in append mode and seeking + * failed */ + (instancetype)archiveWithURI: (OFURI *)URI mode: (OFString *)mode; /** * @brief Creates a URI for accessing a the specified file within the specified @@ -104,10 +100,13 @@ * For append mode, this needs to be an OFSeekableStream. * @param mode The mode for the tar file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return An initialized OFTarArchive + * @throw OFInvalidFormatException The archive has an invalid format + * @throw OFSeekFailedException The archive was open in append mode and seeking + * failed */ - (instancetype)initWithStream: (OFStream *)stream mode: (OFString *)mode OF_DESIGNATED_INITIALIZER; /** @@ -117,10 +116,13 @@ * @param URI The URI to the tar archive * @param mode The mode for the tar file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return An initialized OFTarArchive + * @throw OFInvalidFormatException The archive has an invalid format + * @throw OFSeekFailedException The archive was open in append mode and seeking + * failed */ - (instancetype)initWithURI: (OFURI *)URI mode: (OFString *)mode; /** * @brief Returns the next entry from the tar archive or `nil` if all entries @@ -134,13 +136,26 @@ * invalidated stream will throw an @ref OFReadFailedException or * @ref OFWriteFailedException! * * @return The next entry from the tar archive or `nil` if all entries have * been read + * @throw OFInvalidFormatException The archive has an invalid format */ - (nullable OFTarArchiveEntry *)nextEntry; +/** + * @brief Returns a stream for reading the current entry. + * + * @note This is only available in read mode. + * + * @note The returned stream conforms to @ref OFReadyForReadingObserving if the + * underlying stream does so, too. + * + * @return A stream for reading the current entry + */ +- (OFStream *)streamForReadingCurrentEntry; + /** * @brief Returns a stream for writing the specified entry. * * @note This is only available in write and append mode. * @@ -158,10 +173,12 @@ */ - (OFStream *)streamForWritingEntry: (OFTarArchiveEntry *)entry; /** * @brief Closes the OFTarArchive. + * + * @throw OFNotOpenException The archive is not open */ - (void)close; @end OF_ASSUME_NONNULL_END Index: src/OFThread.h ================================================================== --- src/OFThread.h +++ src/OFThread.h @@ -132,26 +132,36 @@ * @note This has to be set before the thread is started! * * This is a value between -1.0 (meaning lowest priority that still schedules) * and +1.0 (meaning highest priority that still allows getting preempted) * with normal priority being 0.0 (meaning being the same as the main thread). + * + * @throw OFThreadStillRunningException The thread is already/still running and + * thus the priority cannot be changed */ @property (nonatomic) float priority; /** * @brief The stack size of the thread. * * @note This has to be set before the thread is started! + * + * @throw OFThreadStillRunningException The thread is already/still running and + * thus the stack size cannot be changed */ @property (nonatomic) size_t stackSize; /** * @brief Whether the thread supports sockets. * * Some operating systems such as AmigaOS need special per-thread * initialization of sockets. If you intend to use sockets in the thread, set * this property to true before starting the thread. + * + * @throw OFThreadStillRunningException The thread is already/still running and + * thus the sockets support cannot be + * enabled/disabled */ @property (nonatomic) bool supportsSockets; /** * @brief Creates a new thread. @@ -241,10 +251,11 @@ /** * @brief Terminates the current thread, letting it return the specified object. * * @param object The object which the terminated thread will return + * @throw OFInvalidArgumentException The method was called from the main thread */ + (void)terminateWithObject: (nullable id)object OF_NO_RETURN; /** * @brief Sets the name of the current thread. @@ -288,20 +299,24 @@ */ - (void)handleTermination OF_REQUIRES_SUPER; /** * @brief Starts the thread. + * + * @throw OFThreadStillRunningException The thread is still running + * @throw OFThreadStartFailedException Starting the thread failed */ - (void)start; /** * @brief Joins a thread. * * @return The object returned by the main method of the thread. + * @throw OFThreadJoinFailedException Joining the thread failed */ - (id)join; #else - (instancetype)init OF_UNAVAILABLE; #endif @end OF_ASSUME_NONNULL_END Index: src/OFWindowsRegistryKey.h ================================================================== --- src/OFWindowsRegistryKey.h +++ src/OFWindowsRegistryKey.h @@ -77,10 +77,11 @@ * @param accessRights Please refer to the `RegOpenKeyEx()` documentation for * `samDesired` * @param options Please refer to the `RegOpenKeyEx()` documentation for * `ulOptions`. Usually 0. * @return The subkey with the specified path + * @throw OFOpenWindowsRegistryKeyFailedException Opening the key failed */ - (OFWindowsRegistryKey *)openSubkeyAtPath: (OFString *)path accessRights: (REGSAM)accessRights options: (DWORD)options; /** @@ -98,10 +99,11 @@ * @param disposition A pointer to a variable that will be set to whether the * key was created or already existed, or `NULL`. Please * refer to the `RegCreateKeyEx()` documentation for * `lpdwDisposition`. * @return The subkey with the specified path + * @throw OFCreateWindowsRegistryKeyFailedException Creating the key failed */ - (OFWindowsRegistryKey *) createSubkeyAtPath: (OFString *)path accessRights: (REGSAM)accessRights securityAttributes: (nullable SECURITY_ATTRIBUTES *)securityAttributes @@ -112,10 +114,11 @@ * @brief Returns the data for the specified value at the specified path. * * @param name The name of the value to return * @param type A pointer to store the type of the value, or NULL * @return The data for the specified value + * @throw OFGetWindowsRegistryValueFailedException Getting the value failed */ - (nullable OFData *)dataForValueNamed: (nullable OFString *)name type: (nullable DWORD *)type; /** @@ -122,10 +125,11 @@ * @brief Sets the data for the specified value. * * @param data The data to set the value to * @param name The name of the value to set * @param type The type for the value + * @throw OFSetWindowsRegistryValueFailedException Setting the value failed */ - (void)setData: (nullable OFData *)data forValueNamed: (nullable OFString *)name type: (DWORD)type; @@ -132,28 +136,33 @@ /** * @brief Returns the string for the specified value at the specified path. * * @param name The name of the value to return * @return The string for the specified value + * @throw OFGetWindowsRegistryValueFailedException Getting the value failed + * @throw OFInvalidEncodingException The encoding of the value is invalid */ - (nullable OFString *)stringForValueNamed: (nullable OFString *)name; /** * @brief Returns the string for the specified value at the specified path. * * @param name The name of the value to return * @param type A pointer to store the type of the value, or NULL * @return The string for the specified value + * @throw OFGetWindowsRegistryValueFailedException Getting the value failed + * @throw OFInvalidEncodingException The encoding of the value is invalid */ - (nullable OFString *)stringForValueNamed: (nullable OFString *)name type: (nullable DWORD *)type; /** * @brief Sets the string for the specified value. * * @param string The string to set the value to * @param name The name of the value to set + * @throw OFSetWindowsRegistryValueFailedException Setting the value failed */ - (void)setString: (nullable OFString *)string forValueNamed: (nullable OFString *)name; /** @@ -160,10 +169,11 @@ * @brief Sets the string for the specified value. * * @param string The string to set the value to * @param name The name of the value to set * @param type The type for the value + * @throw OFSetWindowsRegistryValueFailedException Setting the value failed */ - (void)setString: (nullable OFString *)string forValueNamed: (nullable OFString *)name type: (DWORD)type; @@ -170,48 +180,56 @@ /** * @brief Returns the DWORD for the specified value at the specified path. * * @param name The name of the value to return * @return The DWORD for the specified value + * @throw OFGetWindowsRegistryValueFailedException Getting the value failed + * @throw OFUndefinedKeyException There is no value with the specified key */ - (uint32_t)DWORDForValueNamed: (nullable OFString *)name; /** * @brief Sets the DWORD for the specified value. * * @param dword The DWORD to set the value to * @param name The name of the value to set + * @throw OFSetWindowsRegistryValueFailedException Setting the value failed */ - (void)setDWORD: (uint32_t)dword forValueNamed: (nullable OFString *)name; /** * @brief Returns the QWORD for the specified value at the specified path. * * @param name The name of the value to return * @return The QWORD for the specified value + * @throw OFGetWindowsRegistryValueFailedException Getting the value failed + * @throw OFUndefinedKeyException There is no value with the specified key */ - (uint64_t)QWORDForValueNamed: (nullable OFString *)name; /** * @brief Sets the QWORD for the specified value. * * @param qword The QWORD to set the value to * @param name The name of the value to set + * @throw OFSetWindowsRegistryValueFailedException Setting the value failed */ - (void)setQWORD: (uint64_t)qword forValueNamed: (nullable OFString *)name; /** * @brief Deletes the specified value. * * @param name The value to delete + * @throw OFDeleteWindowsRegistryValueFailedException Deleting the value failed */ - (void)deleteValueNamed: (nullable OFString *)name; /** * @brief Deletes the specified subkey. * * @param subkeyPath The path of the subkey to delete + * @throw OFDeleteWindowsRegistryKeyFailedException Deleting the key failed */ - (void)deleteSubkeyAtPath: (OFString *)subkeyPath; @end OF_ASSUME_NONNULL_END