From b7dcbb63b3c06c109fd02b3a52d087a33f94cec6 Mon Sep 17 00:00:00 2001 From: Gianluca Bertani Date: Wed, 9 Sep 2015 18:30:10 +0200 Subject: [PATCH] Added API docs --- Objective-Zip/OZFileInZipInfo.h | 40 +++ Objective-Zip/OZZipCompressionLevel.h | 25 ++ Objective-Zip/OZZipException.h | 15 + Objective-Zip/OZZipFile.h | 469 +++++++++++++++++++++++++- Objective-Zip/OZZipFile.m | 6 +- Objective-Zip/OZZipFileMode.h | 20 +- Objective-Zip/OZZipReadStream.h | 42 +++ Objective-Zip/OZZipWriteStream.h | 40 +++ 8 files changed, 651 insertions(+), 6 deletions(-) diff --git a/Objective-Zip/OZFileInZipInfo.h b/Objective-Zip/OZFileInZipInfo.h index fc0a890..e8d6045 100644 --- a/Objective-Zip/OZFileInZipInfo.h +++ b/Objective-Zip/OZFileInZipInfo.h @@ -36,18 +36,58 @@ #import "OZZipCompressionLevel.h" +/** + @brief OZFileInZipInfo provides properties to inspect a file contained in + the zip file. + */ @interface OZFileInZipInfo : NSObject #pragma mark - #pragma mark Properties +/** + @brief Name of the file in the zip file. +

Note: in case the zip file has a directory structure, directory and + subdirectory names are prepended to the file name, e.g. + "docs/html/index.html".

+ */ @property (nonatomic, readonly, nonnull) NSString *name; + +/** + @brief Length in bytes of the uncompressed file. + */ @property (nonatomic, readonly) unsigned long long length; + +/** + @brief Compression level of the file. Can be: + */ @property (nonatomic, readonly) OZZipCompressionLevel level; + +/** + @brief YES if the file has been encrypted during + writing, NO if the file is not encrypted. + */ @property (nonatomic, readonly) BOOL crypted; + +/** + @brief Length in bytes of the (compressed) file in the zip file. + */ @property (nonatomic, readonly) unsigned long long size; + +/** + @brief Date/time the of file. + */ @property (nonatomic, readonly, nonnull) NSDate *date; + +/** + @brief CRC32 of the file. + */ @property (nonatomic, readonly) NSUInteger crc32; diff --git a/Objective-Zip/OZZipCompressionLevel.h b/Objective-Zip/OZZipCompressionLevel.h index b4d3364..599dd9d 100644 --- a/Objective-Zip/OZZipCompressionLevel.h +++ b/Objective-Zip/OZZipCompressionLevel.h @@ -35,11 +35,36 @@ #define Objective_Zip_OZZipCompressionLevel_h +/** + @brief Compression level to be used to compress new files added to the zip + file. + */ typedef enum { + + /** + @brief Compression level that compresses the new file somewhere inbetween + OZZipCompressionLevelBest and OZZipCompressionLevelFastest. + */ OZZipCompressionLevelDefault= -1, + + /** + @brief Compression level that does not compress the new file, it is + stored as is. + */ OZZipCompressionLevelNone= 0, + + /** + @brief Compression level that compresses the new file as fast as + possible, corresponding to the least compression. + */ OZZipCompressionLevelFastest= 1, + + /** + @brief Compression level that compresses the new file as much as + possible, corresponding to the slowest compression. + */ OZZipCompressionLevelBest= 9 + } OZZipCompressionLevel; diff --git a/Objective-Zip/OZZipException.h b/Objective-Zip/OZZipException.h index e1afe78..4333388 100644 --- a/Objective-Zip/OZZipException.h +++ b/Objective-Zip/OZZipException.h @@ -36,12 +36,27 @@ #define ERROR_NO_SUCH_FILE (-9001) +/** + @brief OZZipException is a custom exception type to quickly discern between + error originated during the zip/unzip process or elsewhere. +

All exceptions thrown by Objective-Zip are of OZZipException type.

+ */ @interface OZZipException : NSException #pragma mark - #pragma mark Properties +/** + @brief Underlying error code provided by MiniZip/ZLib libraries. May be + 0 if the exception originated in the Objective-Zip layer. +

Common error codes are:

+ */ @property (nonatomic, readonly) NSInteger error; diff --git a/Objective-Zip/OZZipFile.h b/Objective-Zip/OZZipFile.h index 3b0ab73..50a6ec0 100644 --- a/Objective-Zip/OZZipFile.h +++ b/Objective-Zip/OZZipFile.h @@ -41,93 +41,560 @@ @class OZZipWriteStream; @class OZFileInZipInfo; +/** + @brief OZZipFile provides read or write access to a single zip file. +

During initialization you must specify the access mode, i.e. if the zip + file is being created, appended, or unzipped. You can also specify if the zip + file must be opened in legacy 32-bit mode, to be compatible with older + operating systems (such as some versions of Android).

+

If the zip file has been opened in unzip mode, you can list its content, + move within its content from file to file, and finally open a reading stream + of the selected file.

+

If the zip file has been opened in creation or append mode, you can open a + writing stream to add new files to its content.

+ */ @interface OZZipFile : NSObject #pragma mark - #pragma mark Initialization +/** + @brief Creates a OZZipFile with the specified zip file name and access mode. +

The access mode specifies if the zip is being created, appended, or + unzipped.

+

Note: the zip file is opened in 64-bit mode.

+ @param fileName File name of the zip file. + @param mode Access mode, can be: + @throws OZZipException If the file can't be opened due to an erroror if the + access mode is invalid. + */ - (nonnull instancetype) initWithFileName:(nonnull NSString *)fileName mode:(OZZipFileMode)mode; + +/** + @brief Creates a OZZipFile with the specified zip file name, access mode and + legacy 32-bit mode compatibility. +

The access mode specifies if the zip is being created, appended, or + unzipped.

+ @param fileName File name of the zip file. + @param mode Access mode, can be: + @param legacy32BitMode If set, the zip file is opened in 32-bit mode to + provide compatibility with older operating systems (such as some + version of Android). + @throws OZZipException If the file can't be opened due to an error or if the + access mode is invalid. + */ - (nonnull instancetype) initWithFileName:(nonnull NSString *)fileName mode:(OZZipFileMode)mode legacy32BitMode:(BOOL)legacy32BitMode; + #pragma mark - #pragma mark Initialization (NSError variants) +/** + @brief Creates a OZZipFile with the specified zip file name and access mode. +

The access mode specifies if the zip is being created, appended, or + unzipped.

+

Note: the zip file is opened in 64-bit mode.

+ @param fileName File name of the zip file. + @param mode Access mode, can be: + @param error If passed, may be filled with an NSError is case the file + can't be opened. + @throws OZZipException If the access mode is invalid. + */ - (nullable instancetype) initWithFileName:(nonnull NSString *)fileName mode:(OZZipFileMode)mode error:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Creates a OZZipFile with the specified zip file name, access mode and + legacy 32-bit mode compatibility. +

The access mode specifies if the zip is being created, appended, or + unzipped.

+ @param fileName File name of the zip file. + @param mode Access mode, can be: + @param legacy32BitMode If set, the zip file is opened in 32-bit mode to + provide compatibility with older operating systems (such as some + version of Android). + @param error If passed, may be filled with an NSError is case the file + can't be opened. + @throws OZZipException If the access mode is invalid. + */ - (nullable instancetype) initWithFileName:(nonnull NSString *)fileName mode:(OZZipFileMode)mode legacy32BitMode:(BOOL)legacy32BitMode error:(NSError * __autoreleasing __nullable * __nullable)error; #pragma mark - #pragma mark File writing +/** + @brief Creates a new OZZipWriteStream for adding a new file in the zip file + content. +

The returned write stream can be used to write data to the new file.

+

Note: the new file is added with the current date/time.

+ @param fileNameInZip Name of the new file that must be added to the zip file + content. +
Note: to structure the zip file with directories and subdirectories, + ensure to prepend them in the file name, e.g. "docs/html/index.html" + @param compressionLevel The compression level that must be used to compress + the new file added to the zip file content. Can be: + @return A new OZZipWriteStream for writing data to the new file in the zip + file content. + @throws OZZipException If the file stream can't be created due to an error or + if the zip file has been opened in unzip mode. + */ - (nonnull OZZipWriteStream *) writeFileInZipWithName:(nonnull NSString *)fileNameInZip compressionLevel:(OZZipCompressionLevel)compressionLevel; + +/** + @brief Creates a new OZZipWriteStream for adding a new file in the zip file + content. +

The returned write stream can be used to write data to the new file.

+ @param fileNameInZip Name of the new file that must be added to the zip file + content. +
Note: to structure the zip file with directories and subdirectories, + ensure to prepend them in the file name, e.g. "docs/html/index.html" + @param fileDate The date/time of the new file that must be added to the zip + file content. + @param compressionLevel The compression level that must be used to compress + the new file added to the zip file content. Can be: + @return A new OZZipWriteStream for writing data to the new file in the zip + file content. + @throws OZZipException If the file stream can't be created due to an error or + if the zip file has been opened in unzip mode. + */ - (nonnull OZZipWriteStream *) writeFileInZipWithName:(nonnull NSString *)fileNameInZip fileDate:(nonnull NSDate *)fileDate compressionLevel:(OZZipCompressionLevel)compressionLevel; + +/** + @brief Creates a new OZZipWriteStream for adding a new encrypted file in the + zip file content. +

The returned write stream can be used to write data to the new file.

+ @param fileNameInZip Name of the new file that must be added to the zip file + content. +
Note: to structure the zip file with directories and subdirectories, + ensure to prepend them in the file name, e.g. "docs/html/index.html" + @param fileDate The date/time of the new file that must be added to the zip + file content. + @param compressionLevel The compression level that must be used to compress + the new file added to the zip file content. Can be: + @param password The password that must be used to encrypt the new file data. + @param crc32 A precomputed CRC32 of the new file data (needed for crypting). + @return A new OZZipWriteStream for writing data to the new file in the zip + file content. + @throws OZZipException If the file stream can't be created due to an error or + if the zip file has been opened in unzip mode. + */ - (nonnull OZZipWriteStream *) writeFileInZipWithName:(nonnull NSString *)fileNameInZip fileDate:(nonnull NSDate *)fileDate compressionLevel:(OZZipCompressionLevel)compressionLevel password:(nonnull NSString *)password crc32:(NSUInteger)crc32; #pragma mark - #pragma mark File writing (NSError variants) +/** + @brief Creates a new OZZipWriteStream for adding a new file in the zip file + content. +

The returned write stream can be used to write data to the new file.

+

Note: the new file is added with the current date/time.

+ @param fileNameInZip Name of the new file that must be added to the zip file + content. +
Note: to structure the zip file with directories and subdirectories, + ensure to prepend them in the file name, e.g. "docs/html/index.html" + @param compressionLevel The compression level that must be used to compress + the new file added to the zip file content. Can be: + @param error If passed, may be filled with an NSError is case the write + stream can't be opened. + @return A new OZZipWriteStream for writing data to the new file in the zip + file content, or nil if an error occurs. + @throws OZZipException If the zip file has been opened in unzip mode. + */ - (nullable OZZipWriteStream *) writeFileInZipWithName:(nonnull NSString *)fileNameInZip compressionLevel:(OZZipCompressionLevel)compressionLevel error:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Creates a new OZZipWriteStream for adding a new file in the zip file + content. +

The returned write stream can be used to write data to the new file.

+ @param fileNameInZip Name of the new file that must be added to the zip file + content. +
Note: to structure the zip file with directories and subdirectories, + ensure to prepend them in the file name, e.g. "docs/html/index.html" + @param fileDate The date/time of the new file that must be added to the zip + file content. + @param compressionLevel The compression level that must be used to compress + the new file added to the zip file content. Can be: + @param error If passed, may be filled with an NSError is case the write + stream can't be opened. + @return A new OZZipWriteStream for writing data to the new file in the zip + file content, or nil if an error occurs. + @throws OZZipException If the zip file has been opened in unzip mode. + */ - (nullable OZZipWriteStream *) writeFileInZipWithName:(nonnull NSString *)fileNameInZip fileDate:(nonnull NSDate *)fileDate compressionLevel:(OZZipCompressionLevel)compressionLevel error:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Creates a new OZZipWriteStream for adding a new encrypted file in the + zip file content. +

The returned write stream can be used to write data to the new file.

+ @param fileNameInZip Name of the new file that must be added to the zip file + content. +
Note: to structure the zip file with directories and subdirectories, + ensure to prepend them in the file name, e.g. "docs/html/index.html" + @param fileDate The date/time of the new file that must be added to the zip + file content. + @param compressionLevel The compression level that must be used to compress + the new file added to the zip file content. Can be: + @param password The password that must be used to encrypt the new file data. + @param crc32 A precomputed CRC32 of the new file data (needed for crypting). + @param error If passed, may be filled with an NSError is case the write + stream can't be opened. + @return A new OZZipWriteStream for writing data to the new file in the zip + file content, or nil if an error occurs. + @throws OZZipException If the zip file has been opened in unzip mode. + */ - (nullable OZZipWriteStream *) writeFileInZipWithName:(nonnull NSString *)fileNameInZip fileDate:(nonnull NSDate *)fileDate compressionLevel:(OZZipCompressionLevel)compressionLevel password:(nonnull NSString *)password crc32:(NSUInteger)crc32 error:(NSError * __autoreleasing __nullable * __nullable)error; #pragma mark - #pragma mark File seeking and info +/** + @brief Moves selection to the first file contained in the zip file. +

The selected file may then be read by obaining a OZZipReadStream with + readCurrentFileInZip.

+ @throws OZZipException If the first file can't be selected due to an error or + if the zip file has been opened with a mode other than Unzip. + */ - (void) goToFirstFileInZip; + +/** + @brief Moves selection to the next file contained in the zip file. +

The selected file may then be read by obaining a OZZipReadStream with + readCurrentFileInZip.

+ @return YES if the next file has been selected, + NO if there were no more files to select in the zip file. + @throws OZZipException If the next file can't be selected due to an error or + if the zip file has been opened with a mode other than Unzip. + */ - (BOOL) goToNextFileInZip; + +/** + @brief Locates a file by name in the zip file and selects it. +

The selected file may then be read by obaining a OZZipReadStream with + readCurrentFileInZip.

+ @return YES if the file has been located and selected, + NO if the specified file name is not present in the zip file. + @throws OZZipException If the file can't be located due to an error or if the + zip file has been opened with a mode other than Unzip. + */ - (BOOL) locateFileInZip:(nonnull NSString *)fileNameInZip; +/** + @brief Returns the number of files contained in the zip file. + @return The number of files contained in the zip file. + @throws OZZipException If the number of files could not be obtained due to an + error or if the zip file has been opened with a mode other than Unzip. + */ - (NSUInteger) numFilesInZip; + +/** + @brief Returns a list of OZFileInZipInfo with the information on all the files + contained in the zip file. + @return The list of OZFileInZipInfo with the information on all the files + contained in the zip file. + @throws OZZipException If the list of file info could not be obtained due to + an error or if the zip file has been opened with a mode other than Unzip. + */ - (nonnull NSArray *) listFileInZipInfos; + +/** + @brief Returns an OZFileInZipInfo with the information on the currently + selected file in the zip file. + @return An OZFileInZipInfo with the information on the currently + selected file in the zip file. + @throws OZZipException If the info info could not be obtained due to an error + or if the zip file has been opened with a mode other than Unzip. + */ - (nonnull OZFileInZipInfo *) getCurrentFileInZipInfo; #pragma mark - #pragma mark File seeking and info (NSError variants) +/** + @brief Moves selection to the first file contained in the zip file. +

The selected file may then be read by obaining a OZZipReadStream with + readCurrentFileInZip.

+ @param error If passed, may be filled with an NSError is case the first file + can't be selected. + @return YES if the first file has been selected, NO + if it could not select the first file due to an error. + @throws OZZipException If the zip file has been opened with a mode other than + Unzip. + */ - (BOOL) goToFirstFileInZipWithError:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Moves selection to the next file contained in the zip file. +

The selected file may then be read by obaining a OZZipReadStream with + readCurrentFileInZip.

+ @param error If passed, may be filled with an NSError is case the next file + can't be selected. + @return YES if the next file has been selected, NO + if there were no more files to select in the zip file, or the next file could + not be selected due to an error. + @throws OZZipException If the zip file has been opened with a mode other than + Unzip. + */ - (BOOL) goToNextFileInZipWithError:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Locates a file by name in the zip file and selects it. +

The selected file may then be read by obaining a OZZipReadStream with + readCurrentFileInZip.

+ @param error If passed, may be filled with an NSError is case the file can't + be located. + @return YES if the file has been located and selected, + NO if the specified file name is not present in the zip file or + the file could not be located due to an error. + @throws OZZipException If the zip file has been opened with a mode other than + Unzip. + */ - (BOOL) locateFileInZip:(nonnull NSString *)fileNameInZip error:(NSError * __autoreleasing __nullable * __nullable)error; +/** + @brief Returns the number of files contained in the zip file. + @param error If passed, may be filled with an NSError is case the number of + files could not be obtained. + @return The number of files contained in the zip file, 0 if the number of + files could not be obtained due to an error. + @throws OZZipException If the zip file has been opened with a mode other + than Unzip. + */ - (NSUInteger) numFilesInZipWithError:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Returns a list of OZFileInZipInfo with the information on all the files + contained in the zip file. + @param error If passed, may be filled with an NSError is case the list of + file info could not be obtained. + @return The list of OZFileInZipInfo with the information on all the files + contained in the zip file, nil if the list of file info could + not be obtained due to an error. + @throws OZZipException If the zip file has been opened with a mode other than + Unzip. + */ - (nullable NSArray *) listFileInZipInfosWithError:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Returns an OZFileInZipInfo with the information on the currently + selected file in the zip file. + @param error If passed, may be filled with an NSError is case the file info + could not be obtained. + @return An OZFileInZipInfo with the information on the currently + selected file in the zip file, nil if the file info could not be + obtained due to an error. + @throws OZZipException If the zip file has been opened with a mode other than + Unzip. + */ - (nullable OZFileInZipInfo *) getCurrentFileInZipInfoWithError:(NSError * __autoreleasing __nullable * __nullable)error; #pragma mark - #pragma mark File reading +/** + @brief Creates a OZZipReadStream for reading the currently selected file in + the zip file. +

A file in the zip file can be selected using + goToFirstFileInZip, goToNextFileInZip and + locateFileInZip:.

+ @return The OZZipReadStream to be used for reading the currently selected file + in the zip file. + @throws OZZipException If the read stream could not be created due to an error + or if the zip file has been opened with a mode other than Unzip. + */ - (nonnull OZZipReadStream *) readCurrentFileInZip; + +/** + @brief Creates a OZZipReadStream for reading the currently selected file in + the zip file, if it is encrypted. +

A file in the zip file can be selected using + goToFirstFileInZip, goToNextFileInZip and + locateFileInZip:.

+ @param password The password that must be used to decrypt the file data. + @return The OZZipReadStream to be used for reading the currently selected file + in the zip file. + @throws OZZipException If the read stream could not be created due to an error + or if the zip file has been opened with a mode other than Unzip. + */ - (nonnull OZZipReadStream *) readCurrentFileInZipWithPassword:(nonnull NSString *)password; #pragma mark - #pragma mark File reading (NSError variants) +/** + @brief Creates a OZZipReadStream for reading the currently selected file in + the zip file. +

A file in the zip file can be selected using + goToFirstFileInZip, goToNextFileInZip and + locateFileInZip:.

+ @param error If passed, may be filled with an NSError is case the read stream + could not be created. + @return The OZZipReadStream to be used for reading the currently selected file + in the zip file, nil if the read stream could not be created + due to an error. + @throws OZZipException If the zip file has been opened with a mode other than + Unzip. + */ - (nullable OZZipReadStream *) readCurrentFileInZipWithError:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Creates a OZZipReadStream for reading the currently selected file in + the zip file, if it is encrypted. +

A file in the zip file can be selected using + goToFirstFileInZip, goToNextFileInZip and + locateFileInZip:.

+ @param password The password that must be used to decrypt the file data. + @param error If passed, may be filled with an NSError is case the read stream + could not be created. + @return The OZZipReadStream to be used for reading the currently selected file + in the zip file, nil if the read stream could not be created + due to an error. + @throws OZZipException If the zip file has been opened with a mode other than + Unzip. + */ - (nullable OZZipReadStream *) readCurrentFileInZipWithPassword:(nonnull NSString *)password error:(NSError * __autoreleasing __nullable * __nullable)error; #pragma mark - #pragma mark Closing -- (BOOL) close; +/** + @brief Closes the zip file and releases its resources. +

Once you have finished working with the zip file (e.g. all files have been + unzipped, or all files have been added), it is important to close it so system + resources may be freed.

+

Note: after the zip file has been closed any subsequent call will result in an + error.

+ @throws OZZipException If the zip file could not be closed due to an error. + */ +- (void) close; #pragma mark - #pragma mark Closing (NSError variants) +/** + @brief Closes the zip file and releases its resources. +

Once you have finished working with the zip file (e.g. all files have been + unzipped, or all files have been added), it is important to close it so system + resources may be freed.

+

Note: after the zip file has been closed any subsequent call will result in an + error.

+ @param error If passed, may be filled with an NSError is case the zip file + could not be closed. + @return YES if the zip file has been closed, NO if + the zip file could not be closed due to an error. + */ - (BOOL) closeWithError:(NSError * __autoreleasing __nullable * __nullable)error; #pragma mark - #pragma mark Properties +/** + @brief File name of the zip file. + */ @property (nonatomic, readonly, nonnull) NSString *fileName; + +/** + @brief Access mode specified during opening. Can be: + */ @property (nonatomic, readonly) OZZipFileMode mode; + +/** + @brief YES if the zip file has been opened in 32-bit + compatibility mode, NO if it has been opened in standard + (default) 64-bit mode. + */ @property (nonatomic, readonly) BOOL legacy32BitMode; diff --git a/Objective-Zip/OZZipFile.m b/Objective-Zip/OZZipFile.m index 1c8091c..7efdfcd 100644 --- a/Objective-Zip/OZZipFile.m +++ b/Objective-Zip/OZZipFile.m @@ -542,7 +542,7 @@ #pragma mark - #pragma mark Closing -- (BOOL) close { +- (void) close { switch (_mode) { case OZZipFileModeUnzip: { int err= unzClose(_unzFile); @@ -568,8 +568,6 @@ default: @throw [OZZipException zipExceptionWithReason:@"Unknown mode %d", _mode]; } - - return YES; } @@ -581,6 +579,8 @@ [self close]; + return YES; + } ERROR_WRAP_END_AND_RETURN(error, NO); } diff --git a/Objective-Zip/OZZipFileMode.h b/Objective-Zip/OZZipFileMode.h index 5e209e3..2b7d9a7 100644 --- a/Objective-Zip/OZZipFileMode.h +++ b/Objective-Zip/OZZipFileMode.h @@ -34,11 +34,27 @@ #ifndef Objective_Zip_OZZipFileMode_h #define Objective_Zip_OZZipFileMode_h - +/** + @brief Access mode for opening a zip file. + */ typedef enum { + + /** + @brief Acces mode for opening the zip file for reading. + */ OZZipFileModeUnzip, - OZZipFileModeCreate, + + /** + @brief Acces mode for opening the zip file for creation. +
Note: if the file already exists the behavior is unspecified. + */ + OZZipFileModeCreate, + + /** + @brief Acces mode for opening the zip file for writing. + */ OZZipFileModeAppend + } OZZipFileMode; diff --git a/Objective-Zip/OZZipReadStream.h b/Objective-Zip/OZZipReadStream.h index ffc62ee..231d84e 100644 --- a/Objective-Zip/OZZipReadStream.h +++ b/Objective-Zip/OZZipReadStream.h @@ -34,20 +34,62 @@ #import +/** + @brief OZZipReadStream implements a read stream and provides services to + read content from a file in the zip file. + */ @interface OZZipReadStream : NSObject #pragma mark - #pragma mark Reading data +/** + @brief Reads and uncompresses data from the file in the zip file and stores + them in the specified buffer. + @param buffer The buffer where read and uncompressed data must be stored. + @return The number of uncompressed bytes read, 0 if the end of + the file has been reached. + @throws OZZipException If the data could not be read due to an error. + */ - (NSUInteger) readDataWithBuffer:(nonnull NSMutableData *)buffer; + +/** + @brief Closes the read steam. +

Once you have finished read data to the file, it is important to close + the stream so system resources may be freed.

+

Note: after the stream has been closed any subsequent read will result in + an error.

+ @throws OZZipException If the stream could not be closed due to an error. + */ - (void) finishedReading; #pragma mark - #pragma mark Reading data (NSError variants) +/** + @brief Reads and uncompresses data from the file in the zip file and stores + them in the specified buffer. + @param buffer The buffer where read and uncompressed data must be stored. + @param error If passed, may be filled with an NSError is case data could + not be read. + @return The number of uncompressed bytes read, 0 if the end of + the file has been reached or data could not be read due to an error. + */ - (NSUInteger) readDataWithBuffer:(nonnull NSMutableData *)buffer error:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Closes the read steam. +

Once you have finished read data to the file, it is important to close + the stream so system resources may be freed.

+

Note: after the stream has been closed any subsequent read will result in + an error.

+ @param error If passed, may be filled with an NSError is case the stream could + not be closed. + @return YES if the stream has been closed, NO if + the stream could not be closed due to an error. + */ - (BOOL) finishedReadingWithError:(NSError * __autoreleasing __nullable * __nullable)error; diff --git a/Objective-Zip/OZZipWriteStream.h b/Objective-Zip/OZZipWriteStream.h index bc509d4..a99d1f3 100644 --- a/Objective-Zip/OZZipWriteStream.h +++ b/Objective-Zip/OZZipWriteStream.h @@ -34,20 +34,60 @@ #import +/** + @brief OZZipWriteStream implements a write stream and provides services to + write content to a new file in the zip file. + */ @interface OZZipWriteStream : NSObject #pragma mark - #pragma mark Writing data +/** + @brief Compresses and writes data to the new file in the zip file. +

Data are compressed depending on the choice of compression level specified + during creation of the write stream.

+ @param data The data to be compressed and written. + @throws OZZipException If the data could not be written due to an error. + */ - (void) writeData:(nonnull NSData *)data; + +/** + @brief Closes the write stream. +

Once you have finished writing data to the new file, it is important to + close the stream so system resources may be freed.

+

Note: after the stream has been closed any subsequent write will result in + an error.

+ @throws OZZipException If the stream could not be closed due to an error. + */ - (void) finishedWriting; #pragma mark - #pragma mark Writing data (NSError variants) +/** + @brief Compresses and writes data to the new file in the zip file. +

Data are compressed depending on the choice of compression level specified + during creation of the write stream.

+ @param data The data to be compressed and written. + @param error If passed, may be filled with an NSError is case data could + not be written. + */ - (BOOL) writeData:(nonnull NSData *)data error:(NSError * __autoreleasing __nullable * __nullable)error; + +/** + @brief Closes the write stream. +

Once you have finished writing data to the new file, it is important to + close the stream so system resources may be freed.

+

Note: after the stream has been closed any subsequent write will result in + an error.

+ @param error If passed, may be filled with an NSError is case the stream could + not be closed. + @return YES if the stream has been closed, NO if + the stream could not be closed due to an error. + */ - (BOOL) finishedWritingWithError:(NSError * __autoreleasing __nullable * __nullable)error;