Index: src/OFFileManager.h ================================================================== --- src/OFFileManager.h +++ src/OFFileManager.h @@ -257,15 +257,19 @@ #endif #ifdef OF_HAVE_FILES /** * @brief The path of the current working directory. + * + * @throw OFGetCurrentDirectoryFailedException Couldn't get current directory */ @property (readonly, nonatomic) OFString *currentDirectoryPath; /** * @brief The URL of the current working directory. + * + * @throw OFGetCurrentDirectoryFailedException Couldn't get current directory */ @property (readonly, nonatomic) OFURL *currentDirectoryURL; #endif /** @@ -278,10 +282,12 @@ * @brief Returns the attributes for the item at the specified path. * * @param path The path to return the attributes for * @return A dictionary of attributes for the specified path, with the keys of * type @ref OFFileAttributeKey + * @throw OFGetItemAttributesFailedException Failed to get the attributes of + * the item */ - (OFFileAttributes)attributesOfItemAtPath: (OFString *)path; #endif /** @@ -288,10 +294,14 @@ * @brief Returns the attributes for the item at the specified URL. * * @param URL The URL to return the attributes for * @return A dictionary of attributes for the specified URL, with the keys of * type @ref OFFileAttributeKey + * @throw OFGetItemAttributesFailedException Failed to get the attributes of + * the item + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (OFFileAttributes)attributesOfItemAtURL: (OFURL *)URL; #ifdef OF_HAVE_FILES /** @@ -299,10 +309,15 @@ * * All attributes not part of the dictionary are left unchanged. * * @param attributes The attributes to set for the specified path * @param path The path of the item to set the attributes for + * @throw OFSetItemAttributesFailedException Failed to set the attributes of + * the item + * @throw OFNotImplementedException Setting one or more of the specified + * attributes is not implemented for the + * specified item */ - (void)setAttributes: (OFFileAttributes)attributes ofItemAtPath: (OFString *)path; #endif @@ -311,10 +326,17 @@ * * All attributes not part of the dictionary are left unchanged. * * @param attributes The attributes to set for the specified URL * @param URL The URL of the item to set the attributes for + * @throw OFSetItemAttributesFailedException Failed to set the attributes of + * the item + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme + * @throw OFNotImplementedException Setting one or more of the specified + * attributes is not implemented for the + * specified item */ - (void)setAttributes: (OFFileAttributes)attributes ofItemAtURL: (OFURL *)URL; #ifdef OF_HAVE_FILES /** @@ -329,10 +351,12 @@ /** * @brief Checks whether a file exists at the specified URL. * * @param URL The URL to check * @return A boolean whether there is a file at the specified URL + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (bool)fileExistsAtURL: (OFURL *)URL; #ifdef OF_HAVE_FILES /** @@ -347,43 +371,55 @@ /** * @brief Checks whether a directory exists at the specified URL. * * @param URL The URL to check * @return A boolean whether there is a directory at the specified URL + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (bool)directoryExistsAtURL: (OFURL *)URL; #ifdef OF_HAVE_FILES /** * @brief Creates a directory at the specified path. * * @param path The path of the directory to create + * @throw OFCreateDirectoryFailedException Creating the directory failed */ - (void)createDirectoryAtPath: (OFString *)path; /** * @brief Creates a directory at the specified path. * * @param path The path of the directory to create * @param createParents Whether to create the parents of the directory + * @throw OFCreateDirectoryFailedException Creating the directory or one of its + * parents failed */ - (void)createDirectoryAtPath: (OFString *)path createParents: (bool)createParents; #endif /** * @brief Creates a directory at the specified URL. * * @param URL The URL of the directory to create + * @throw OFCreateDirectoryFailedException Creating the directory failed + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (void)createDirectoryAtURL: (OFURL *)URL; /** * @brief Creates a directory at the specified URL. * * @param URL The URL of the directory to create * @param createParents Whether to create the parents of the directory + * @throw OFCreateDirectoryFailedException Creating the directory or one of its + * parents failed + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (void)createDirectoryAtURL: (OFURL *)URL createParents: (bool)createParents; #ifdef OF_HAVE_FILES /** @@ -391,10 +427,12 @@ * * @note `.` and `..` are not part of the returned array. * * @param path The path to the directory whose items should be returned * @return An array of OFString with the items in the specified directory + * @throw OFOpenItemFailedException Opening the directory failed + * @throw OFReadFailedException Reading from the directory failed */ - (OFArray OF_GENERIC(OFString *) *)contentsOfDirectoryAtPath: (OFString *)path; #endif /** @@ -403,10 +441,14 @@ * * @note `.` and `..` are not part of the returned array. * * @param URL The URL to the directory whose items should be returned * @return An array with the URLs of the items in the specified directory + * @throw OFOpenItemFailedException Opening the directory failed + * @throw OFReadFailedException Reading from the directory failed + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (OFArray OF_GENERIC(OFURL *) *)contentsOfDirectoryAtURL: (OFURL *)URL; #ifdef OF_HAVE_FILES /** @@ -422,17 +464,21 @@ /** * @brief Changes the current working directory. * * @param path The new directory to change to + * @throw OFChangeCurrentDirectoryFailedException Changing the current working + * directory failed */ - (void)changeCurrentDirectoryPath: (OFString *)path; /** * @brief Changes the current working directory. * * @param URL The new directory to change to + * @throw OFChangeCurrentDirectoryFailedException Changing the current working + * directory failed */ - (void)changeCurrentDirectoryURL: (OFURL *)URL; /** * @brief Copies a file, directory or symbolic link (if supported by the OS). @@ -444,10 +490,13 @@ * if a directory is copied and an item already exists in the destination * directory. * * @param source The file, directory or symbolic link to copy * @param destination The destination path + * @throw OFCopyItemFailedException Copying failed + * @throw OFCreateDirectoryFailedException Creating a destination directory + * failed */ - (void)copyItemAtPath: (OFString *)source toPath: (OFString *)destination; #endif /** @@ -460,10 +509,15 @@ * if a directory is copied and an item already exists in the destination * directory. * * @param source The file, directory or symbolic link to copy * @param destination The destination URL + * @throw OFCopyItemFailedException Copying failed + * @throw OFCreateDirectoryFailedException Creating a destination directory + * failed + * @throw OFUnsupportedProtocolException No handler is registered for either of + * the URL's scheme */ - (void)copyItemAtURL: (OFURL *)source toURL: (OFURL *)destination; #ifdef OF_HAVE_FILES /** @@ -476,10 +530,18 @@ * copied to the destination using @ref copyItemAtPath:toPath: and the source * removed using @ref removeItemAtPath:. * * @param source The item to rename * @param destination The new name for the item + * @throw OFMoveItemFailedException Moving failed + * @throw OFCopyItemFailedException Copying (to move between different devices) + * failed + * @throw OFRemoveItemFailedException Removing the source after copying to the + * destination (to move between different + * devices) failed + * @throw OFCreateDirectoryFailedException Creating a destination directory + * failed */ - (void)moveItemAtPath: (OFString *)source toPath: (OFString *)destination; #endif /** @@ -492,10 +554,20 @@ * scheme, the source will be copied to the destination using * @ref copyItemAtURL:toURL: and the source removed using @ref removeItemAtURL:. * * @param source The item to rename * @param destination The new name for the item + * @throw OFMoveItemFailedException Moving failed + * @throw OFCopyItemFailedException Copying (to move between different devices) + * failed + * @throw OFRemoveItemFailedException Removing the source after copying to the + * destination (to move between different + * devices) failed + * @throw OFCreateDirectoryFailedException Creating a destination directory + * failed + * @throw OFUnsupportedProtocolException No handler is registered for either of + * the URL's scheme */ - (void)moveItemAtURL: (OFURL *)source toURL: (OFURL *)destination; #ifdef OF_HAVE_FILES /** @@ -502,10 +574,11 @@ * @brief Removes the item at the specified path. * * If the item at the specified path is a directory, it is removed recursively. * * @param path The path to the item which should be removed + * @throw OFRemoveItemFailedException Removing the item failed */ - (void)removeItemAtPath: (OFString *)path; #endif /** @@ -512,10 +585,13 @@ * @brief Removes the item at the specified URL. * * If the item at the specified URL is a directory, it is removed recursively. * * @param URL The URL to the item which should be removed + * @throw OFRemoveItemFailedException Removing the item failed + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (void)removeItemAtURL: (OFURL *)URL; #ifdef OF_FILE_MANAGER_SUPPORTS_LINKS /** @@ -526,10 +602,13 @@ * * This method is not available on some systems. * * @param source The path to the item for which a link should be created * @param destination The path to the item which should link to the source + * @throw OFLinkItemFailedException Linking the item failed + * @throw OFNotImplementedException Hardlinks are not implemented for the + * specified URL */ - (void)linkItemAtPath: (OFString *)source toPath: (OFString *)destination; #endif /** @@ -540,10 +619,15 @@ * * This method is not available for all URLs. * * @param source The URL to the item for which a link should be created * @param destination The URL to the item which should link to the source + * @throw OFLinkItemFailedException Linking the item failed + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme + * @throw OFNotImplementedException Hardlinks are not implemented for the + * specified URL */ - (void)linkItemAtURL: (OFURL *)source toURL: (OFURL *)destination; #ifdef OF_FILE_MANAGER_SUPPORTS_SYMLINKS /** @@ -557,10 +641,13 @@ * @note On Windows, this requires at least Windows Vista and administrator * privileges! * * @param path The path to the item which should symbolically link to the target * @param target The target of the symbolic link + * @throw OFCreateSymbolicLinkFailedException Creating the symbolic link failed + * @throw OFNotImplementedException Symbolic links are not implemented for the + * specified URL */ - (void)createSymbolicLinkAtPath: (OFString *)path withDestinationPath: (OFString *)target; #endif @@ -575,97 +662,99 @@ * @note On Windows, this requires at least Windows Vista and administrator * privileges! * * @param URL The URL to the item which should symbolically link to the target * @param target The target of the symbolic link + * @throw OFUnsupportedProtocolException No handler is registered for the URL's + * scheme */ - (void)createSymbolicLinkAtURL: (OFURL *)URL withDestinationPath: (OFString *)target; @end @interface OFDictionary (FileAttributes) /** * @brief The @ref OFFileSize key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) unsigned long long fileSize; /** * @brief The @ref OFFileType key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFFileAttributeType fileType; /** * @brief The @ref OFFilePOSIXPermissions key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) unsigned long filePOSIXPermissions; /** * @brief The @ref OFFileOwnerAccountID key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) unsigned long fileOwnerAccountID; /** * @brief The @ref OFFileGroupOwnerAccountID key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) unsigned long fileGroupOwnerAccountID; /** * @brief The @ref OFFileOwnerAccountName key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFString *fileOwnerAccountName; /** * @brief The @ref OFFileGroupOwnerAccountName key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFString *fileGroupOwnerAccountName; /** * @brief The @ref OFFileLastAccessDate key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFDate *fileLastAccessDate; /** * @brief The @ref OFFileModificationDate key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFDate *fileModificationDate; /** * @brief The @ref OFFileStatusChangeDate key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFDate *fileStatusChangeDate; /** * @brief The @ref OFFileCreationDate key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFDate *fileCreationDate; /** * @brief The @ref OFFileSymbolicLinkDestination key from the dictionary. * - * Raises an @ref OFUndefinedKeyException if the key is missing. + * @throw OFUndefinedKeyException The key is missing */ @property (readonly, nonatomic) OFString *fileSymbolicLinkDestination; @end OF_ASSUME_NONNULL_END