CkoZip Objective-C Reference Documentation

CkoZip

Zip compression component.

Properties

@property (nonatomic) BOOL AbortCurrent;

Introduced in version 9.5.0.58

When set to YES, causes the currently running method to abort. Methods that always finish quickly (i.e.have no length file operations or network communications) are not affected. If no method is running, then this property is automatically reset to NO when the next method is called. When the abort occurs, this property is reset to NO. Both synchronous and asynchronous method calls can be aborted. (A synchronous method call could be aborted by setting this property from a separate thread.)

@property (nonatomic, copy) NSString *AppendFromDir;

When files are added to a Zip archive, they are appended from this directory. For example, to add all the files under c:/abc/123/myAppDir, this property could be set to "c:/abc/123", and "myAppDir/*" would be passed to AppendFiles. The path that is saved in the .zip would be "myAppDir/". (The value of the AppendFromDir property does not become part of the file path saved in the .zip.)

Controlling Paths of Files Added to Zip

@property (nonatomic) BOOL CaseSensitive;

If YES then all methods that get or search for zip entries by name will use case-sensitive filename matching. If NO then filename matching will be case insensitive. Methods affected by this property include GetEntryByName, UnzipMatching, FirstMatchingEntry, etc.

The default value is NO.

@property (nonatomic) BOOL ClearArchiveAttribute;

Set this to YES to clear the FILE_ATTRIBUTE_ARCHIVE file attribute of each file during a zipping operation.

The default value is NO.

@property (nonatomic) BOOL ClearReadOnlyAttr;

If YES, the read-only attribute is automatically cleared when unzipping. The default value of this property is NO, which leaves the read-only attribute unchanged when unzipping.

@property (nonatomic, copy) NSString *Comment;

The global Zip file comment.

@property (nonatomic, copy) NSString *DebugLogFilePath;

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

@property (nonatomic, copy) NSString *DecryptPassword;

When opening a password-protected or AES encrypted Zip, this is the password to be used for decryption. Encrypted Zips may be opened without setting a password, but the contents cannot be unzipped without setting this password.

Note:The SetPassword method has the effect of setting both this property as well as the EncryptPassword property. The SetPassword method should no longer be used. It has been replaced by the DecryptPassword and EncryptPassword properties to make it possible to open an encrypted zip and re-write it with a new password.

@property (nonatomic) BOOL DiscardPaths;

If YES, discards all file path information when zipping. The default value is NO.

@property (nonatomic, copy) NSNumber *Encryption;

Indicate whether the Zip is to be strong encrypted or not. Valid values are 0 (not encrypted) or 4 (AES encrypted). When this property is set to the value 4, WinZip AES compatible encrypted zip archives are produced.

Note: Prior to Chilkat v9.4.1, other possible values for this property were: 1 (blowfish), 2 (twofish), and 3 (rijndael). These settings originally provided a way to produce strong encrypted zips prior to when the AES encrypted Zip standard existed. Using these legacy values (1, 2, or 3) produced encrypted zips that only applications using Chilkat could read. Chilkat no longer supports these custom modes of encryption. If using an older version of Chilkat with one of these deprecated encryption modes, make sure to decrypt using the old Chilkat version and re-encrypt using mode 4 (WinZip compatible AES encryption) prior to updating to the new Chilkat version.

Important:The Encryption and PasswordProtect properties are mutually exclusive. PasswordProtect corresponds to the older Zip 2.0 encryption, commonly referred to as a "password-protected" zip. If the PasswordProtect is set to YES, the Encryption property should be set to 0. If the Encryption property is set to a non-zero value, then PasswordProtect should be set to NO. A zip cannot be both password-protected and strong-encrypted.

@property (nonatomic, copy) NSNumber *EncryptKeyLength;

The encryption key length if AES, Blowfish, Twofish, or WinZip-compatible AES encryption is used. This value must be 128, 192, or 256. The default value is 128.

@property (nonatomic, copy) NSString *EncryptPassword;

The password used when writing a password-protected or strong-encrytped Zip.

Note:The SetPassword method has the effect of setting both this property as well as the DecryptPassword property. The SetPassword method should no longer be used. It has been replaced by the DecryptPassword and EncryptPassword properties to make it possible to open an encrypted zip and re-write it with a new password.

@property (nonatomic, readonly, copy) NSNumber *FileCount;

The number of files (excluding directories) contained within the Zip.

@property (nonatomic, copy) NSString *FileName;

The path (absolute or relative) of the Zip archive. This is the path of the file that is created or overwritten when the zip is saved.

@property (nonatomic, readonly) BOOL HasZipFormatErrors;

YES if the opened zip contained file format errors (that were not severe enough to prevent the zip from being opened and parsed).

@property (nonatomic, copy) NSNumber *HeartbeatMs;

The number of milliseconds between each AbortCheck event callback. The AbortCheck callback allows an application to abort any method call prior to completion. If HeartbeatMs is 0 (the default), no AbortCheck event callbacks will fire.

@property (nonatomic) BOOL IgnoreAccessDenied;

If YES, then files that cannot be read due to "access denied" (i.e. a file permission error) will be ignored and the call to WriteZip, WriteZipAndClose, WriteExe, etc. will return a success status. If NO, then the "access denied" filesystem errors are not ignored and any occurrence will cause the zip writing to fail. The default value is YES.

@property (nonatomic, readonly, copy) NSString *LastErrorHtml;

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

@property (nonatomic, readonly, copy) NSString *LastErrorText;

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

Concept of LastErrorText

LastErrorText Standard Information

@property (nonatomic, readonly, copy) NSString *LastErrorXml;

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

@property (nonatomic) BOOL LastMethodSuccess;

Introduced in version 9.5.0.52

Indicate whether the last method call succeeded or failed. A value of YES indicates success, a value of NO indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = YES and failure = NO.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to YES. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

@property (nonatomic, readonly, copy) NSNumber *NumEntries;

The number of entries in the Zip, including both files and directories.

@property (nonatomic, copy) NSNumber *OemCodePage;

Sets the OEM code page to be used for Unicode filenames. This property defaults to the OEM code page of the computer.

@property (nonatomic) BOOL OverwriteExisting;

Determines whether existing files are overwritten during unzipping. The default is YES, which means that already-existing files will be overwritten. Set this property = NO to prevent existing files from being overwritten when unzipping.

@property (nonatomic) BOOL PasswordProtect;

YES if the Zip should be password-protected using older Zip 2.0 encryption, commonly referred to as "password-protection".

This property is set when a zip archive is opened by any of the Open* methods, such as OpenZip, OpenFromMemory, etc.

@property (nonatomic, copy) NSString *PathPrefix;

A prefix that is added to each filename when zipping. One might set the PathPrefix to "subdir/" so that files are unzipped to a specified subdirectory when unzipping.

How to Add a Directory Path to Files when Zipping

@property (nonatomic, copy) NSNumber *PercentDoneScale;

Introduced in version 9.5.0.49

This property is only valid in programming environment and languages that allow for event callbacks.

Sets the value to be defined as 100% complete for the purpose of PercentDone event callbacks. The defaut value of 100 means that at most 100 event PercentDone callbacks will occur in a method that (1) is event enabled and (2) is such that it is possible to measure progress as a percentage completed. This property may be set to larger numbers to get more fine-grained PercentDone callbacks. For example, setting this property equal to 1000 will provide callbacks with .1 percent granularity. For example, a value of 453 would indicate 45.3% competed. This property is clamped to a minimum value of 10, and a maximum value of 100000.

@property (nonatomic, copy) NSString *TempDir;

The temporary directory to use when unzipping files. When running in ASP or ASP.NET, the default value of TempDir is set to the directory where the .zip is being written. Set this property to override the default.

@property (nonatomic) BOOL TextFlag;

If set to YES, the component will set the "text flag" for each file having these filename extensions: .txt, .xml, .htm, and .html. It will also preserve the "text flag" for existing zips that are opened and rewritten. By default, this property is set to NO.

It is generally not necessary to set the text flag for a zip entry.

@property (nonatomic) BOOL VerboseLogging;

If set to YES, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is NO. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

@property (nonatomic, readonly, copy) NSString *Version;

Version of the component/library, such as "9.5.0.63"

@property (nonatomic) BOOL Zipx;

Starting in v9.4.1, Chilkat Zip will automatically unzip ZIPX files using any of the following compression methods: BZIP2, PPMd, LZMA, and Deflate64 ("Deflate64" is a trademark of PKWare, Inc.)

This property, however, controls whether or not a ZipX is automatically produced where the best compression algorithm for each file is automatically chosen based on file type. This property is for writing zip archives. It does not apply to when unzipping ZIPX archives, Chilkat Zip automatically handles the various compression algorithms when unzipping.

@property (nonatomic, copy) NSString *ZipxDefaultAlg;

The default compression algorithm to be used when creating ZIPX archives. The default value is "deflate". Other possible values are "ppmd", "lzma", "bzip2" and "deflate64". When writing a ZIPX archive, if the file extension does not indicate an obvious choice for the appropriate compression algorithm, then the ZipxDefaultAlg is used.

Methods

- (void)AddNoCompressExtension:(NSString *)fileExtension;

Attempting to compress already-compressed data is usually a waste of CPU cycles with little or no benefit. In fact, it is possible that attempting to compress already-compressed data results in a slightly increased size. The Zip file format allows for files to be "stored" rather than compressed. This allows the file data to be streamed directly into a .zip without compression.

An instance of the Zip object has an internal list of "no compress" extensions. A filename with a "no compress" extension is "stored" rather than compressed. Additional "no compress" extensions may be added by calling this method (once per file extension). You should pass the file extension, such as ".xyz" in fileExtension.

"no compress" extensions may be removed by calling RemoveNoCompressExtension.

The default "no compress" extensions are: .zip, .gif, .jpg, .gz, .rar, .jar, .tgz, .bz2, .z, .rpm, .msi, .png

- (CkoZipEntry *)AppendBase64:(NSString *)pathInZip
    data:(NSString *)data;

Creates a new Zip entry and initializes it with already-compressed data that is Base64 encoded. (The ZipEntry.CopyBase64 method can be used to retrieve the compressed data in Base64 format.)

Note 1: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Note 2: It is assumed that the compressed data is unencrypted deflated data. (Meaning data compressed using the "deflate" compression algorithm.)

Returns nil on failure

- (CkoZipEntry *)AppendBd:(NSString *)pathInZip
    byteData:(CkoBinData *)byteData;

Introduced in version 9.5.0.70

Appends the contents of byteData as a new entry to this zip object. The zip entry object containing the data is returned.

Returns nil on failure

Backup Windows Current User / Personal Certificates to a .zip

- (CkoZipEntry *)AppendCompressed:(NSString *)pathInZip
    data:(NSData *)data;

Append memory data that is already Zip-compressed to the Zip object. The ZipEntry object containing the compressed data is returned. Note: This method appends the compressed data for a single zip entry. To load an entire in-memory .zip, call OpenFromMemory instead.

Note 1: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Note 2: It is assumed that the compressed data is unencrypted deflated data. (Meaning data compressed using the "deflate" compression algorithm.)

Returns nil on failure

- (CkoZipEntry *)AppendData:(NSString *)pathInZip
    data:(NSData *)data;

Appends in-memory data as a new entry to a Zip object. The ZipEntry object containing the data is returned.

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns nil on failure

Create a Zip Entirely in Memory

- (CkoZipEntry *)AppendDataEncoded:(NSString *)filename
    encoding:(NSString *)encoding
    data:(NSString *)data;

Introduced in version 9.5.0.59

Appends in-memory data as a new entry to a Zip object. The filename is the filename of the entry as it will appear within the zip. The encoding is the encoding of the data, such as "base64", "hex", etc. The full list of encodings is listed at the web page linked below.

Returns the zip entry object.

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns nil on failure

Binary Encodings Supported by Chilkat

- (BOOL)AppendFiles:(NSString *)filePattern
    recurse:(BOOL)recurse;

Appends one or more files to the Zip object. The filePattern can use the "*" wildcard character for 0 or more of any characterSet recurse equal to True to recursively add all subdirectories, or False to only add files in the current directory.

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns YES for success, NO for failure.

Controlling paths within a Zip

- (CkoTask *)AppendFilesAsync:(NSString *)filePattern
    recurse:(BOOL)recurse;

Creates an asynchronous task to call the AppendFiles method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (BOOL)AppendFilesEx:(NSString *)filePattern
    recurse:(BOOL)recurse
    saveExtraPath:(BOOL)saveExtraPath
    archiveOnly:(BOOL)archiveOnly
    includeHidden:(BOOL)includeHidden
    includeSystem:(BOOL)includeSystem;

Appends one or more files to the Zip object. The filePattern can use the "*" and "?" wildcard characters where "*" means 0 or more of any character and "?" means any single character. The recurse controls whether directories are recursively traversed. Set recurse equal to YES to append files and subdirectories in the directory tree. Set recurse equal to NO to add files only from the indicated directory.

The saveExtraPath only applies when the filePattern is an absolute path pattern, such as "C:/temp/abc/*.txt". If saveExtraPath is YES, then the absolute path will be included in the zip entry filenames as relative paths. For example, "temp/abc/xyz.txt".

The archiveOnly, archiveOnly, and includeHidden flags only apply when on the Windows operating system. These flags control whether files with the Archive, Hidden, or System attributes are included.

Note: This method does not write the zip archive. It simply adds references to the files that will be included in the .zip when the WriteZip or WriteZipAndClose methods are eventually called. Files and/or data may be added to the zip object by calling any combination of the Append* methods before finally writing the zip via one of the Write* methods.

Returns YES for success, NO for failure.

- (CkoTask *)AppendFilesExAsync:(NSString *)filePattern
    recurse:(BOOL)recurse
    saveExtraPath:(BOOL)saveExtraPath
    archiveOnly:(BOOL)archiveOnly
    includeHidden:(BOOL)includeHidden
    includeSystem:(BOOL)includeSystem;

Creates an asynchronous task to call the AppendFilesEx method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (CkoZipEntry *)AppendHex:(NSString *)pathInZip
    data:(NSString *)data;

Creates a new Zip entry and initializes it with already-compressed data that is hexidecimal encoded. (The ZipEntry.CopyHex method can be used to retrieve the compressed data in Hex format.)

Note 1: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Note 2: It is assumed that the compressed data is unencrypted deflated data. (Meaning data compressed using the "deflate" compression algorithm.)

Returns nil on failure

- (BOOL)AppendMultiple:(CkoStringArray *)fileSpecs
    recurse:(BOOL)recurse;

This method is the same as calling AppendFiles multiple times - once for each file pattern in fileSpecs

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns YES for success, NO for failure.

- (CkoTask *)AppendMultipleAsync:(CkoStringArray *)fileSpecs
    recurse:(BOOL)recurse;

Creates an asynchronous task to call the AppendMultiple method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (CkoZipEntry *)AppendNew:(NSString *)pathInZip;

Appends a new and empty entry to the Zip object and returns the ZipEntry object. Data can be appended to the entry by calling ZipEntry.AppendData.

Important: To append an already-existing file, call the AppendOneFileOrDir method. The AppendNew method inserts a new and empty file entry within the Zip object. The purpose of AppendNew is to either create an empty file within the Zip, or to create a new file entry which can then be filled with data by calling the entry's AppendData method.

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns nil on failure

- (CkoZipEntry *)AppendNewDir:(NSString *)pathInZip;

Adds an entry to the zip so that when it unzips, a new directory (with no files) is created. The directory does not need to exist on the local filesystem when calling this method. The dirName is simply a string that is used as the directory path for the entry added to the zip. The zip entry object is returned.

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns nil on failure

- (BOOL)AppendOneFileOrDir:(NSString *)path
    saveExtraPath:(BOOL)saveExtraPath;

Appends a single file or directory to the Zip object. The saveExtraPath applies when fileOrDirPath is an absolute (non-relative) path. If saveExtraPath is YES, then the absolute path is made relative and saved in the zip. For example, if the fileOrDirPath is "C:/temp/xyz/test.txt" and saveExtraPath is YES, then the path in the zip will be "./temp/xyz/test.txt". If however, fileOrDirPath contains a relative path, then saveExtraPath has no effect.

Returns YES for success, NO for failure.

Set Entry Filepath (in output Zip) when Zipping

- (CkoTask *)AppendOneFileOrDirAsync:(NSString *)path
    saveExtraPath:(BOOL)saveExtraPath;

Creates an asynchronous task to call the AppendOneFileOrDir method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (CkoZipEntry *)AppendString:(NSString *)pathInZip
    str:(NSString *)str;

Adds an in-memory string to the Zip object. The textData argument is converted to the ANSI charset before being added to the Zip. If the Zip were written to disk by calling WriteZip, and later unzipped, the entry would unzip to an ANSI text file.

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns nil on failure

- (CkoZipEntry *)AppendString2:(NSString *)pathInZip
    str:(NSString *)str
    charset:(NSString *)charset;

Same as AppendString, but allows the charset to be specified. The textData is converted to charset before being added to the zip. The internalZipFilepath is the path of the file that will be stored within the zip.

Note: This method only updates the zip object. To update (rewrite) a zip file, either the WriteZip or WriteZipAndClose method would need to be called.

Returns nil on failure

Create a Zip Entirely in Memory

- (BOOL)AppendZip:(NSString *)zipPath;

Adds the contents of another existing Zip file to this Zip object.

Returns YES for success, NO for failure.

- (void)CloseZip;

Closes an open Zip file. This is identical to calling NewZip. (NewZip closes the current Zip file, if open, and initializes the Zip object to be empty. Zip files are only created when WriteZip is called.)

- (BOOL)DeleteEntry:(CkoZipEntry *)entry;

Removes a Zip entry from the calling Zip object.

Returns YES for success, NO for failure.

Remove a File from a .zip

- (void)ExcludeDir:(NSString *)dirName;

Adds a directory name to be excluded when AppendFiles is called to add an entire directory tree. All directories having a name equal to an excluded directory will not be included when AppendFiles (or AppendFileEx) is called. Multiple directories can be excluded by calling ExcludeDir multiple times. The name comparison is case-insensitive.

- (BOOL)Extract:(NSString *)dirPath;

Unzip all the files into the specified directory. Subdirectories are automatically created as needed.

Returns YES for success, NO for failure.

- (CkoTask *)ExtractAsync:(NSString *)dirPath;

Creates an asynchronous task to call the Extract method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (BOOL)ExtractInto:(NSString *)dirPath;

Unzips all the files in a Zip into a single directory regardless of the path stored in the Zip

Returns YES for success, NO for failure.

- (BOOL)ExtractMatching:(NSString *)dirPath
    pattern:(NSString *)pattern;

Unzip all files matching a wildcard pattern.

Returns YES for success, NO for failure.

- (BOOL)ExtractNewer:(NSString *)dirPath;

Extracts only the files that have more recent last-modified-times than the files on disk. This allows you to easily refresh only the files that have been updated.

Returns YES for success, NO for failure.

- (BOOL)ExtractOne:(CkoZipEntry *)entry
    dirPath:(NSString *)dirPath;

This method is deprecated. It will be removed in a future version.

Identical to calling ZipEntry.Extract. This method is deprecated and the Extract method of the zip entry should be called instead.

Returns YES for success, NO for failure.

- (CkoZipEntry *)FirstEntry;

Return the first entry in the Zip. Call ZipEntry.NextEntry to iterate over the entries in a Zip until a NULL is returned.

Returns nil on failure

- (CkoZipEntry *)FirstMatchingEntry:(NSString *)pattern;

Returns the first entry having a filename matching a pattern. The "*" characters matches 0 or more of any character. The full filename, including path, is used when matching against the pattern. A NULL is returned if nothing matches.

Returns nil on failure

Iterate over Matching Filenames

- (NSString *)GetDirectoryAsXML;

Return the contents of the Zip file directory in an XML formatted string

Returns nil on failure

- (CkoZipEntry *)GetEntryByID:(NSNumber *)entryID;

Retrieves a ZipEntry by ID. Chilkat Zip.NET automatically assigns a unique ID to each ZipEntry in the Zip. This feature makes it easy to associate an item in a UI control with a ZipEntry.

Returns nil on failure

- (CkoZipEntry *)GetEntryByIndex:(NSNumber *)index;

Retrieves a ZipEntry by index. The first entry is at index 0. This will return directory entries as well as files.

Returns nil on failure

- (CkoZipEntry *)GetEntryByName:(NSString *)entryName;

Returns a ZipEntry by filename. If a full or partial path is part of the filename, this must be included in the filename parameter.

Returns nil on failure

Download a Zip from a URL and OpenFromMemory. (No .zip fie is created)

Set Entry Filepath (in output Zip) when Zipping

- (CkoStringArray *)GetExclusions;

Returns the current collection of exclusion patterns that have been set by SetExclusions.

Returns nil on failure

- (CkoZipEntry *)InsertNew:(NSString *)pathInZip
    beforeIndex:(NSNumber *)beforeIndex;

Inserts a new and empty entry into the Zip object. To insert at the beginning of the Zip, beforeIndex should be 0. The ZipEntry's FileName property is initialized to fileName parameter.

Returns nil on failure

- (BOOL)IsNoCompressExtension:(NSString *)fileExtension;

Returns YES if the fileExtension is contained in the set of "no compress" extensions, otherwise returns NO. (See the documentation for the AddNoCompressExtension method.) The fileExtension may be passed with or without the ".". For example, both ".jpg" and "jpg" are acceptable.

- (BOOL)IsPasswordProtected:(NSString *)zipPath;

Return True if a Zip file is password protected

- (BOOL)IsUnlocked;

Returns True if the class is already unlocked, otherwise returns False.

- (BOOL)NewZip:(NSString *)zipPath;

Clears and initializes the contents of the Zip object. If a Zip file was open, it is closed and all entries are removed from the object. The FileName property is set to the zipFilePath argument.

Chilkat Zip API Concepts

- (BOOL)OpenBd:(CkoBinData *)binData;

Introduced in version 9.5.0.66

Open a Zip contained in binData.

When a zip is opened, the PasswordProtect and Encryption properties will be appropriately set. If the zip is password protected (i.e. uses older Zip 2.0 encrypion), then the PasswordProtect property will be set to YES. If the zip is strong encrypted, the Encryption property will be set to a value 1 through 4, where 4 indicates WinZip compatible AES encryption.

Returns YES for success, NO for failure.

Create Enveloping XML Digital Signature

- (BOOL)OpenFromByteData:(NSData *)byteData;

Same as OpenFromMemory.

When a zip is opened, the PasswordProtect and Encryption properties will be appropriately set. If the zip is password protected (i.e. uses older Zip 2.0 encrypion), then the PasswordProtect property will be set to YES. If the zip is strong encrypted, the Encryption property will be set to a value 1 through 4, where 4 indicates WinZip compatible AES encryption.

Returns YES for success, NO for failure.

- (BOOL)OpenFromMemory:(NSData *)inData;

Open a Zip that is completely in-memory. This allows for Zip files to be opened from non-filesystem sources, such as a database.

When a zip is opened, the PasswordProtect and Encryption properties will be appropriately set. If the zip is password protected (i.e. uses older Zip 2.0 encrypion), then the PasswordProtect property will be set to YES. If the zip is strong encrypted, the Encryption property will be set to a value 1 through 4, where 4 indicates WinZip compatible AES encryption.

Returns YES for success, NO for failure.

Download a Zip from a URL and OpenFromMemory. (No .zip fie is created)

- (BOOL)OpenZip:(NSString *)zipPath;

Opens a Zip archive. Encrypted and password-protected zips may be opened without providing the password, but their contents may not be unzipped unless the correct password is provided via the DecryptPassword proprety, or the SetPassword method.

When a zip is opened, the PasswordProtect and Encryption properties will be appropriately set. If the zip is password protected (i.e. uses older Zip 2.0 encrypion), then the PasswordProtect property will be set to YES. If the zip is strong encrypted, the Encryption property will be set to a value 1 through 4, where 4 indicates WinZip compatible AES encryption.

Returns YES for success, NO for failure.

- (CkoTask *)OpenZipAsync:(NSString *)zipPath;

Creates an asynchronous task to call the OpenZip method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (BOOL)QuickAppend:(NSString *)zipPath;

Efficiently appends additional files to an existing zip archive. QuickAppend leaves all entries in the existing .zip untouched. It operates by appending new files and updating the internal "central directory" of the zip archive.

Returns YES for success, NO for failure.

Append Files to Existing Zip w/out Rewriting Entire Zip

- (CkoTask *)QuickAppendAsync:(NSString *)zipPath;

Creates an asynchronous task to call the QuickAppend method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (void)RemoveNoCompressExtension:(NSString *)fileExtension;

Removes a file extension from the zip object's internal list of "no compress" extensions. (For more information, see AddNoCompressExtension.)

- (BOOL)SaveLastError:(NSString *)path;

Saves the last-error information (the contents of LastErrorXml) to an XML formatted file.

Returns YES for success, NO for failure.

- (void)SetCompressionLevel:(NSNumber *)level;

Sets the compression level for all file and data entries. The compression level for a mapped entry (i.e. an entry that is contained within an opened .zip, cannot be changed.) The default compression level is 6. A compression level of 0 is equivalent to no compression. The maximum compression level is 9.

The zip.SetCompressionLevel method must be called after appending the files (i.e. after the calls to AppendFile*, AppendData, or AppendOneFileOrDir).

A single call to SetCompressionLevel will set the compression level for all existing file and data entries.

- (void)SetExclusions:(CkoStringArray *)excludePatterns;

Specify a collection of exclusion patterns to be used when adding files to a Zip. Each pattern in the collection can use the "*" wildcard character, where "*" indicates 0 or more occurrences of any character.

- (void)SetPassword:(NSString *)password;

Set the password for an encrypted or password-protected Zip.

- (BOOL)UnlockComponent:(NSString *)regCode;

Unlocks the component allowing for the full functionality to be used. If a purchased unlock code is passed, there is no expiration. Any other string automatically begins a fully-functional 30-day trial the first time UnlockComponent is called.

Returns YES for success, NO for failure.

Diagnosing UnlockComponent Problems

UnlockComponent LastErrorText shows exact string passed to it.

Verify UnlockComponent Success w/ Purchased Unlock Code

LastErrorText Standard Information

- (NSNumber *)Unzip:(NSString *)dirPath;

Unzips and returns the number of files unzipped, or -1 if a failure occurs. Subdirectories are automatically created during the unzipping process.

- (CkoTask *)UnzipAsync:(NSString *)dirPath;

Creates an asynchronous task to call the Unzip method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (NSNumber *)UnzipInto:(NSString *)dirPath;

Unzips and returns the number of files unzipped, or -1 if a failure occurs. All files in the Zip are unzipped into the specfied dirPath regardless of the directory path information contained in the Zip. This has the effect of collapsing all files into a single directory. If several files in the Zip have the same name, the files unzipped last will overwrite the files already unzipped.

- (CkoTask *)UnzipIntoAsync:(NSString *)dirPath;

Creates an asynchronous task to call the UnzipInto method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (NSNumber *)UnzipMatching:(NSString *)dirPath
    pattern:(NSString *)pattern
    verbose:(BOOL)verbose;

Same as Unzip, but only unzips files matching a pattern. If no wildcard characters ('*') are used, then only files that exactly match the pattern will be unzipped. The "*" characters matches 0 or more of any character.

Unzip Files Matching a Pattern (such as *.xml)

- (CkoTask *)UnzipMatchingAsync:(NSString *)dirPath
    pattern:(NSString *)pattern
    verbose:(BOOL)verbose;

Creates an asynchronous task to call the UnzipMatching method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (NSNumber *)UnzipMatchingInto:(NSString *)dirPath
    pattern:(NSString *)pattern
    verbose:(BOOL)verbose;

Unzips matching files into a single directory, ignoring all path information stored in the Zip.

- (CkoTask *)UnzipMatchingIntoAsync:(NSString *)dirPath
    pattern:(NSString *)pattern
    verbose:(BOOL)verbose;

Creates an asynchronous task to call the UnzipMatchingInto method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (NSNumber *)UnzipNewer:(NSString *)dirPath;

Same as Unzip, but only files that don't already exist on disk, or have later file modification dates are unzipped.

- (CkoTask *)UnzipNewerAsync:(NSString *)dirPath;

Creates an asynchronous task to call the UnzipNewer method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (BOOL)VerifyPassword;

Tests the current DecryptPassword setting against the currently opened zip. Returns YES if the password is valid, otherwise returns NO.

Verify a Zip's Password

- (BOOL)WriteBd:(CkoBinData *)binData;

Introduced in version 9.5.0.66

Same as WriteZip, but instead of writing the Zip to a file, it writes to binData. Zips that are written to binData can be opened by calling OpenBd. Note: Both WriteBd and OpenBd are added in Chilkat v9.5.0.66

Returns YES for success, NO for failure.

- (CkoTask *)WriteBdAsync:(CkoBinData *)binData;

Introduced in version 9.5.0.66

Creates an asynchronous task to call the WriteBd method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (NSData *)WriteToMemory;

Same as WriteZip, but instead of writing the Zip to a file, it writes to memory. Zips that are written to memory can also be opened from memory by calling OpenFromMemory.

Returns nil on failure

Create a Zip Entirely in Memory

- (CkoTask *)WriteToMemoryAsync;

Creates an asynchronous task to call the WriteToMemory method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (BOOL)WriteZip;

Saves the Zip to a file and implictly re-opens it so further operations can continue. Use WriteZipAndClose to write and close the Zip. There is no limitation on the size of files that may be contained within a .zip, the total number of files in a .zip, or the total size of a .zip. If necessary, WriteZip will use the ZIP64 file format extensions when 4GB or file count limitations of the old zip file format are exceeded.

Returns YES for success, NO for failure.

- (CkoTask *)WriteZipAsync;

Creates an asynchronous task to call the WriteZip method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

- (BOOL)WriteZipAndClose;

Saves the Zip to a file and closes it. On return, the Zip object will be in the state as if NewZip had been called. There is no limitation on the size of files that may be contained within a .zip, the total number of files in a .zip, or the total size of a .zip. If necessary, WriteZip will use the ZIP64 file format extensions when 4GB or file count limitations of the old zip file format are exceeded.

Returns YES for success, NO for failure.

- (CkoTask *)WriteZipAndCloseAsync;

Creates an asynchronous task to call the WriteZipAndClose method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

How to Run an Asynchronous Task

Events

To implement an event callback, your application would define and implement a class that inherits from CkoZipProgress. Your application can implement methods to override some or all of the default/empty method implementations of the CkoZipProgress base class.

For example:

  CkoZip *zip = [[CkoZip alloc] init];

  MyZipProgress *callbackObj = [[MyZipProgress alloc] init];

  [zip setEventCallbackObject:callbackObj];

MyZipProgress interface example:

#import "CkoZipProgress.h"

@interface MyZipProgress : CkoZipProgress {

}

    - (id)init;
    - (void)dealloc;
    - (void)dispose;

    - (void)AbortCheck:(BOOL *)abort;

    - (void)AddFilesBegin;

    - (void)AddFilesEnd;

    - (void)BinaryData:(NSData *)data 
        length:(NSNumber *)length;

    - (void)DirToBeAdded:(NSString *)path 
        skip:(BOOL *)skip;

    - (void)FileAdded:(NSString *)path 
        fileSize:(NSNumber *)fileSize 
        abort:(BOOL *)abort;

    - (void)FileUnzipped:(NSString *)path 
        compressedSize:(NSNumber *)compressedSize 
        fileSize:(NSNumber *)fileSize 
        abort:(BOOL *)abort;

    - (void)FileZipped:(NSString *)path 
        fileSize:(NSNumber *)fileSize 
        compressedSize:(NSNumber *)compressedSize 
        abort:(BOOL *)abort;

    - (void)PercentDone:(NSNumber *)pctDone 
        abort:(BOOL *)abort;

    - (void)ProgressInfo:(NSString *)name 
        value:(NSString *)value;

    - (void)SkippedForUnzip:(NSString *)path 
        compressedSize:(NSNumber *)compressedSize 
        fileSize:(NSNumber *)fileSize 
        isDirectory:(BOOL)isDirectory;

    - (void)TaskCompleted:(CkoTask *)task;

    - (void)TextData:(NSString *)data;

    - (void)ToBeAdded:(NSString *)path 
        fileSize:(NSNumber *)fileSize 
        skip:(BOOL *)skip;

    - (void)ToBeUnzipped:(NSString *)path 
        compressedSize:(NSNumber *)compressedSize 
        fileSize:(NSNumber *)fileSize 
        skip:(BOOL *)skip;

    - (void)ToBeZipped:(NSString *)path 
        fileSize:(NSNumber *)fileSize 
        skip:(BOOL *)skip;

    - (void)UnzipBegin;

    - (void)UnzipEnd;

    - (void)WriteZipBegin;

    - (void)WriteZipEnd;

@end

- (void)AbortCheck:(BOOL *)abort;

Provides the opportunity for a method call to be aborted. The AbortCheck event is fired periodically based on the value of the HeartbeatMs property. If HeartbeatMs is 0, then no AbortCheck events will fire. As an example, to fire 5 AbortCheck events per second, set the HeartbeatMs property equal to 200.

- (void)AddFilesBegin;

Fired at the start of the AppendFiles or AppendFIlesEx method.

- (void)AddFilesEnd;

Fired at the end of the AppendFiles or AppendFIlesEx method.

- (void)BinaryData:(NSData *)data
    length:(NSNumber *)length;

Binary data provided by certain methods.

- (void)DirToBeAdded:(NSString *)path
    skip:(BOOL *)skip;

This event fires during the AppendFiles and AppendFilesEx method calls. It is called just before each directory is to be added. The skip output-only argument may be set to YES to prevent the directory and everything it contains from being added.

- (void)FileAdded:(NSString *)path
    fileSize:(NSNumber *)fileSize
    abort:(BOOL *)abort;

This event fires during the AppendFiles and AppendFilesEx method calls. It is called just after each file is added. The abort output-only argument may be set to YES to abort the method call.

- (void)FileUnzipped:(NSString *)path
    compressedSize:(NSNumber *)compressedSize
    fileSize:(NSNumber *)fileSize
    abort:(BOOL *)abort;

This event fires during method calls that unzip a zip archive. It is called just after each file is unzipped. The abort output-only argument may be set to YES to abort the method call.

- (void)FileZipped:(NSString *)path
    fileSize:(NSNumber *)fileSize
    compressedSize:(NSNumber *)compressedSize
    abort:(BOOL *)abort;

This event fires during method calls that write a zip archive. It is called just after each file is zipped. The abort output-only argument may be set to YES to abort the method call.

- (void)PercentDone:(NSNumber *)pctDone
    abort:(BOOL *)abort;

Provides the percentage completed for any method that involves network communications or time-consuming processing (assuming it is a method where a percentage completion can be measured). This event is only fired when it is possible to know a percentage completion, and when it makes sense to express the operation as a percentage completed. The pctDone argument will have a value from 1 to 100. For operations (Chilkat method calls) that complete very quickly, the number of PercentDone callbacks will vary, but the final callback should have a value of 100. For long running operations, no more than one callback per percentage point will occur (for example: 1, 2, 3, ... 98, 99, 100).

The PercentDone callback counts as an AbortCheck event. For method calls that complete quickly such that PercentDone events fire, it may be that AbortCheck events don't fire because the opportunity to abort is already provided in the PercentDone callback. For time consuming operations, where the amount of time between PercentDone callbacks are long, AbortCheck callbacks may be used to allow for the operation to be aborted in a more responsive manner.

The abort output argument provides a means for aborting the operation. Setting it to YES will cause the method to abort and return a failed status (or whatever return value indicates failure).

- (void)ProgressInfo:(NSString *)name
    value:(NSString *)value;

A general name/value event that provides information about what is happening during a method call. To find out what information is available, write code to handle this event and log the name/value pairs. Most are self-explanatory.

- (void)SkippedForUnzip:(NSString *)path
    compressedSize:(NSNumber *)compressedSize
    fileSize:(NSNumber *)fileSize
    isDirectory:(BOOL)isDirectory;

This event fires during method calls that unzip a zip archive. It is called for each file that was skipped for some reason (such as for when UnzipNewer or UnzipMatching is called).

- (void)TaskCompleted:(CkoTask *)task;

Called in the background thread when an asynchronous task completes.

- (void)TextData:(NSString *)data;

Text data provided by certain methods.

- (void)ToBeAdded:(NSString *)path
    fileSize:(NSNumber *)fileSize
    skip:(BOOL *)skip;

This event fires during the AppendFiles and AppendFilesEx method calls. It is called just before each file is to be added. The skip output-only argument may be set to YES to prevent the file from being added.

- (void)ToBeUnzipped:(NSString *)path
    compressedSize:(NSNumber *)compressedSize
    fileSize:(NSNumber *)fileSize
    skip:(BOOL *)skip;

This event fires during method calls that unzip a zip archive. It is called just before each file is unzipped. The skip output-only argument may be set to YES to prevent the file from being unzipped.

- (void)ToBeZipped:(NSString *)path
    fileSize:(NSNumber *)fileSize
    skip:(BOOL *)skip;

This event fires during method calls that create a zip archive. It is called just before each file is to be zipped. The skip output-only argument may be set to YES to prevent the file from being zipped.

- (void)UnzipBegin;

To be documented soon...

- (void)UnzipEnd;

Fired when finished unzipping.

- (void)WriteZipBegin;

Fired when starting to write a zip.

- (void)WriteZipEnd;

Fired when finished writing a zip.