@@ -19,10 +19,11 @@ #import "OFTarArchiveEntry.h" OF_ASSUME_NONNULL_BEGIN @class OFStream; +@class OFURI; /** * @class OFTarArchive OFTarArchive.h ObjFW/OFTarArchive.h * * @brief A class for accessing and manipulating tar archives. @@ -35,52 +36,61 @@ OFTarArchiveModeRead, OFTarArchiveModeWrite, OFTarArchiveModeAppend } _mode; OFStringEncoding _encoding; + OFTarArchiveEntry *_Nullable _currentEntry; +#ifdef OF_TAR_ARCHIVE_M +@public +#endif OFStream *_Nullable _lastReturnedStream; } /** * @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; -#ifdef OF_HAVE_FILES /** * @brief Creates a new OFTarArchive object with the specified file. * - * @param path The path to the tar archive + * @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 + * tar archive. + * + * @param path The path of the file within the archive + * @param URI The URI of the archive + * @return A URI for accessing the specified file within the specified tar + * archive */ -+ (instancetype)archiveWithPath: (OFString *)path mode: (OFString *)mode; -#endif ++ (OFURI *)URIForFilePath: (OFString *)path inArchiveWithURI: (OFURI *)URI; - (instancetype)init OF_UNAVAILABLE; /** * @brief Initializes an already allocated OFTarArchive object with the @@ -90,27 +100,31 @@ * 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; -#ifdef OF_HAVE_FILES /** * @brief Initializes an already allocated OFTarArchive object with the * specified file. * - * @param path The path to the tar archive + * @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)initWithPath: (OFString *)path mode: (OFString *)mode; -#endif +- (instancetype)initWithURI: (OFURI *)URI mode: (OFString *)mode; /** * @brief Returns the next entry from the tar archive or `nil` if all entries * have been read. * @@ -122,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. * @@ -146,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