Zip Rust Reference Documentation

Zip

Current Version: 11.6.1
Requires Chilkat Bundle License

Chilkat.Zip

Create, read, modify, encrypt, and extract ZIP archives.

Chilkat.Zip provides a comprehensive API for working with ZIP archives from files, memory, BinData, embedded resources, and Windows self-extracting EXEs. It can create new archives, open existing ZIPs, add files or in-memory data, inspect entries, extract selectively, and write the final archive to disk or memory.

Create ZIP archives

Add files, directories, strings, byte arrays, BinData, and StringBuilder content.

Open ZIPs from many sources

Open archives from disk, memory, BinData, embedded Windows resources, or Chilkat-created self-extracting EXEs.

Control stored paths

Use options such as AppendFromDir, DiscardPaths, PathPrefix, and saveExtraPath.

Extract selectively

Extract all files, matching entries, newer files, or flatten all output into a single directory.

Encryption support

Work with WinZip-compatible AES encryption and legacy Zip 2.0 password protection.

Large archive support

ZIP64 is used automatically when older ZIP limits are exceeded.

Important: Many methods update the in-memory ZIP object first. The archive is not written until a method such as WriteZip, WriteZipAndClose, WriteBd, or WriteToMemory is called.

For an extended overview, see Zip Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::Zip;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let zip = Zip::new();
// ... the native object is freed when `zip` goes out of scope.
pub fn new() -> Zip

Creates the underlying native Chilkat object (Zip also implements Default). Every method takes &self, so the object never needs to be declared mut. A Zip is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for Zip

The native object is freed when the Zip is dropped — when it goes out of scope, or explicitly with drop(zip). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<Zip>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match zip.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

AbortCurrent
// read/write
pub fn abort_current(&self) -> bool
pub fn set_abort_current(&self, value: bool)
Introduced in version 9.5.0.58

Stops the currently executing operation when set to true.

  • Used to cancel long-running operations such as compression or extraction.
  • Can be triggered from another thread.
  • Automatically resets to false after the operation stops.

top
AppendFromDir
// read/write
pub fn append_from_dir(&self) -> String
pub fn set_append_from_dir(&self, value: &str)

Specifies a base directory when adding files to the ZIP.

  • This portion of the path is not included in stored ZIP entry paths.
  • Useful for controlling relative paths inside the archive.

For example, to add all files under c:/abc/123/myAppDir, this property could be set to c:/abc/123, and myAppDir/* would be passed to AppendFiles.

The path stored in the ZIP would begin with myAppDir/.

More Information and Examples
Control Stored ZIP Paths Using AppendFromDirControl Stored ZIP Paths Using AppendFromDir and saveExtraPath
top
AutoRun
// read/write
pub fn auto_run(&self) -> String
pub fn set_auto_run(&self, value: &str)

(Windows only, for creating self-extracting EXE's)

Specifies the name of an executable inside a self-extracting EXE that runs automatically after extraction.

top
AutoRunParams
// read/write
pub fn auto_run_params(&self) -> String
pub fn set_auto_run_params(&self, value: &str)

(Windows only, for creating self-extracting EXE's)

Command-line arguments passed to the AutoRun executable.

top
AutoTemp
// read/write
pub fn auto_temp(&self) -> bool
pub fn set_auto_temp(&self, value: bool)

(Windows only, for creating self-extracting EXE's)

If true, the EXE being created will automatically select and create a temporary directory for unzipping.

This property is often used together with AutoRun to create a self-extracting EXE that automatically unzips to a temporary directory and runs a setup program, such as setup.exe, without user interaction.

Note: To create a self-extracting EXE with no user interaction, set the following properties:

ExeSilentProgress = false
ExeNoInterface = true
ExeFinishNotifier = false

The default value is false.

top
CaseSensitive
// read/write
pub fn case_sensitive(&self) -> bool
pub fn set_case_sensitive(&self, value: bool)

Controls whether filename matching is case-sensitive.

  • Affects methods such as EntryMatching and UnzipMatching.
  • Default: false

top
ClearArchiveAttribute
// read/write
pub fn clear_archive_attribute(&self) -> bool
pub fn set_clear_archive_attribute(&self, value: bool)

(Windows only)

If true, clears the Windows archive attribute after files are successfully added to the ZIP.

The archive attribute indicates that a file has changed since the last backup.

The default value is false.

top
ClearReadOnlyAttr
// read/write
pub fn clear_read_only_attr(&self) -> bool
pub fn set_clear_read_only_attr(&self, value: bool)

If true, removes the read-only attribute from extracted files.

If false, the read-only attribute remains unchanged.

The default value is false.

top
Comment
// read/write
pub fn comment(&self) -> String
pub fn set_comment(&self, value: &str)

Sets or retrieves the global ZIP file comment.

The default value is the empty string.

top
DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
DecryptPassword
// read/write
pub fn decrypt_password(&self) -> String
pub fn set_decrypt_password(&self, value: &str)

Password used to extract encrypted ZIP archives.

  • Required to unzip encrypted entries.
  • Encrypted ZIP files may still be opened without a password, but their contents cannot be extracted until the correct password is provided.

The default value is the empty string.

top
DiscardPaths
// read/write
pub fn discard_paths(&self) -> bool
pub fn set_discard_paths(&self, value: bool)

If true, removes all directory path information when adding files.

Only filenames are stored in the ZIP.

The default value is false.

More Information and Examples
Extract ZIP Files Without Preserving Directory Paths Using DiscardPaths
top
Encryption
// read/write
pub fn encryption(&self) -> i32
pub fn set_encryption(&self, value: i32)

Specifies encryption mode:

  • 0 → No encryption
  • 4 → WinZip-compatible AES encryption

Important: Encryption and PasswordProtect are mutually exclusive.

If PasswordProtect = true, then Encryption should be 0.

The default value is 0.

More Information and Examples
Create a WinZip/7-Zip compatible AES Encrypted ZipDetermine if a Zip is Encrypted or Password-Protected
top
EncryptKeyLength
// read/write
pub fn encrypt_key_length(&self) -> i32
pub fn set_encrypt_key_length(&self, value: i32)

Specifies the AES encryption key length.

  • Valid values: 128, 192, or 256

The default value is 128.

top
EncryptPassword
// read/write
pub fn encrypt_password(&self) -> String
pub fn set_encrypt_password(&self, value: &str)

Password used when creating encrypted ZIP archives.

The default value is the empty string.

top
ExeDefaultDir
// read/write
pub fn exe_default_dir(&self) -> String
pub fn set_exe_default_dir(&self, value: &str)

(Windows only, for creating self-extracting EXE's)

Default extraction directory shown in the self-extracting EXE user interface.

The default value is the empty string.

top
ExeFinishNotifier
// read/write
pub fn exe_finish_notifier(&self) -> bool
pub fn set_exe_finish_notifier(&self, value: bool)

(Windows only, for creating self-extracting EXE's)

If true, displays a completion dialog after extraction finishes.

The default value is false.

top
ExeIconFile
// read/write
pub fn exe_icon_file(&self) -> String
pub fn set_exe_icon_file(&self, value: &str)

(Windows only, for creating self-extracting EXE's)

Path to an .ico file used as the EXE icon.

This feature is only available when the application creating the EXE is 32-bit.

The default value is the empty string.

top
ExeNoInterface
// read/write
pub fn exe_no_interface(&self) -> bool
pub fn set_exe_no_interface(&self, value: bool)

(Windows only, for creating self-extracting EXE's)

If true, runs the self-extracting EXE without displaying the main user interface.

The default value is false.

top
ExeSilentProgress
// read/write
pub fn exe_silent_progress(&self) -> bool
pub fn set_exe_silent_progress(&self, value: bool)

(Windows only, for creating self-extracting EXE's)

Controls whether a progress dialog is shown during extraction.

If ExeNoInterface = false, the progress bar appears within the main dialog and this property has no effect.

The default value is false.

top
ExeTitle
// read/write
pub fn exe_title(&self) -> String
pub fn set_exe_title(&self, value: &str)

(Windows only, for creating self-extracting EXE's)

Title displayed in the self-extracting EXE dialog.

The default value is the empty string.

top
ExeUnzipCaption
// read/write
pub fn exe_unzip_caption(&self) -> String
pub fn set_exe_unzip_caption(&self, value: &str)

(Windows only, for creating self-extracting EXE's)

Caption text displayed in the self-extracting EXE dialog.

The default value is the empty string.

top
ExeUnzipDir
// read/write
pub fn exe_unzip_dir(&self) -> String
pub fn set_exe_unzip_dir(&self, value: &str)

(Windows only, for creating self-extracting EXE's)

Specifies a predefined extraction directory.

  • Supports environment variables such as %TEMP%.
  • UNC paths are not supported.

The default value is the empty string.

top
ExeWaitForSetup
// read/write
pub fn exe_wait_for_setup(&self) -> bool
pub fn set_exe_wait_for_setup(&self, value: bool)

If true, waits for the AutoRun executable to finish before exiting.

If false, the self-extracting EXE may exit before the AutoRun executable completes.

The default value is true.

top
ExeXmlConfig
// read/write
pub fn exe_xml_config(&self) -> String
pub fn set_exe_xml_config(&self, value: &str)

Allows for an XML config document to be used to specify all possible options for self-extracting EXEs. This property is a string containing the XML config document.

The XML should have this format:

<SfxConfig>
<ErrPwdTitle>Title for incorrect password dialog</ErrPwdTitle>
<ErrPwdCaption>Caption for incorrect password dialog</ErrPwdCaption>
<FinOkBtn>Text on finish notifier button</FinOkBtn>
<PwdOkBtn>Text on password challenge dialog's "OK" button.</PwdOkBtn>
<PwdCancelBtn>Text on password challenge dialog's Cancel button.</PwdCancelBtn>
<ErrInvalidPassword>Incorrect password error message.</ErrInvalidPassword>
<MainUnzipBtn>Text on main dialog's unzip button. Note: The MainUnzipLabel must also be set for this to take effect.</MainUnzipBtn>
<MainCloseBtn>Text on main dialog's quit/exit button. Note: The MainUnzipLabel must also be set for this to take effect.</MainCloseBtn>
<MainBrowseBtn>Text on main dialog's browse-for-directory button. Note: The MainUnzipLabel must also be set for this to take effect.</MainBrowseBtn>
<MainUnzipLabel>Caption displayed in main dialog.</MainUnzipLabel>
<AutoTemp>0 or 1 (Maps to the AutoTemp property)</AutoTemp>
<Cleanup>0 or 1 (If 1, extracted files are deleted after the SetupExe is run.)</Cleanup>
<Debug>0 or 1 (If 1, the EXE will not extract any files.)</Debug>
<Verbose>0 or 1 (If 1, verbose information is written to the log.)</Verbose>
<ShowFin>0 or 1 (Maps to the ExeFinishNotifier property)</ShowFin>
<ShowMain>0 or 1 (Maps to the ExeNoInterface property)</ShowMain>
<ShowProgress>0 or 1 (Maps to the ExeSilentProgress property)</ShowProgress>
<WaitForSetup>0 or 1 (Maps to the ExeWaitForSetup property)</WaitForSetup>
<Encryption>0 or 1 (1 = Yes, 0 = No)</Encryption>
<KeyLength>128|192|256</KeyLength>
<SetupExe>EXE to run after extracting. (Maps to the AutoRun property)</SetupExe>
<UnzipDir>Pre-defined unzip directory. (Maps to the ExeUnzipDir property. UNC paths, such as \\servername\path, are not supported.)</UnzipDir>
<DefaultDir>Default unzip directory to appear in the main dialog. (Maps to the ExeDefaultDir property)</DefaultDir>
<IconFile>Icon file to be used (Maps to the ExeIconFile property)</IconFile>
<MainTitle>Maps to the ExeTitle property.</MainTitle>
<MainCaption>Maps to the ExeUnzipCaption property.</MainCaption>
<FinTitle>Title for the finish notifier dialog.</FinTitle>
<FinCaption>Caption for the finish notifier dialog.</FinCaption>
<ProgressTitle>Title for the progress dialog.</ProgressTitle>
<ProgressCaption>Caption for the progress dialog.</ProgressCaption>
<PwTitle>Title for the password challenge dialog.</PwTitle>
<PwCaption>Caption for the password challenge dialog.</PwCaption>
</SfxConfig>

A self-extracting EXE can be run from the command line with the -log {logFilePath} option to create a log with information for debugging.

top
FileCount
// read-only
pub fn file_count(&self) -> i32

Number of files in the ZIP, excluding directory entries.

top
FileName
// read/write
pub fn file_name(&self) -> String
pub fn set_file_name(&self, value: &str)

Path of the ZIP file to be written or overwritten.

The default value is the empty string.

top
HasZipFormatErrors
// read-only
pub fn has_zip_format_errors(&self) -> bool

Indicates whether minor ZIP format problems were detected when opening the ZIP archive.

top
HeartbeatMs
// read/write
pub fn heartbeat_ms(&self) -> i32
pub fn set_heartbeat_ms(&self, value: i32)

Interval, in milliseconds, between abort-check callbacks.

If set to 0, abort callbacks are disabled.

The default value is 0.

More Information and Examples
Event Callback Examples
top
IgnoreAccessDenied
// read/write
pub fn ignore_access_denied(&self) -> bool
pub fn set_ignore_access_denied(&self, value: bool)

If true, files that cannot be read, written, or created due to filesystem permission errors are skipped.

If false, any access-denied error causes the ZIP operation to fail.

The default value is true.

top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
MaxDate
// read/write
pub fn max_date(&self) -> String
pub fn set_max_date(&self, value: &str)
Introduced in version 10.0.0

Maximum last-modified timestamp for files processed during add or extract operations.

Files having modification timestamps later than this value are skipped.

Supports ISO 8601 date/time formats, including:

  • YYYY-MM-DD
    Example: 2024-07-31
  • YYYY-MM-DDTHH:MM:SS±HH:MM
    Example: 2024-07-31T12:34:56+02:00
  • YYYY-MM-DDTHH:MM:SSZ
    Example: 2024-07-31T12:34:56Z

The default value is the empty string, meaning no maximum date restriction.

More Information and Examples
Unzip Files in a Date RangeZip Files in a Date Range
top
MaxUncompressSize
// read/write
pub fn max_uncompress_size(&self) -> u32
pub fn set_max_uncompress_size(&self, value: u32)
Introduced in version 9.5.0.96

Prevents extraction of files larger than the specified uncompressed size.

A value of 0 means no size limit.

The default value is 0.

top
MinDate
// read/write
pub fn min_date(&self) -> String
pub fn set_min_date(&self, value: &str)
Introduced in version 10.0.0

Minimum last-modified timestamp for files processed during add or extract operations.

Supports ISO 8601 date/time formats, including:

  • YYYY-MM-DD
    Example: 2024-07-31
  • YYYY-MM-DDTHH:MM:SS±HH:MM
    Example: 2024-07-31T12:34:56+02:00
  • YYYY-MM-DDTHH:MM:SSZ
    Example: 2024-07-31T12:34:56Z

The default value is the empty string, meaning no minimum date restriction.

More Information and Examples
Unzip Files in a Date RangeZip Files in a Date Range
top
NumEntries
// read-only
pub fn num_entries(&self) -> i32

Total number of entries in the ZIP, including both files and directories.

More Information and Examples
List Files/Directories in Zip by Index
top
OemCodePage
// read/write
pub fn oem_code_page(&self) -> i32
pub fn set_oem_code_page(&self, value: i32)

Specifies the OEM code page used for ZIP filename encoding.

Defaults to the OEM code page of the current computer.

top
OverwriteExisting
// read/write
pub fn overwrite_existing(&self) -> bool
pub fn set_overwrite_existing(&self, value: bool)

If true, existing files are overwritten during extraction.

The default value is true.

top
PasswordProtect
// read/write
pub fn password_protect(&self) -> bool
pub fn set_password_protect(&self, value: bool)

Indicates whether the ZIP uses legacy Zip 2.0 password protection.

This property is set automatically when a ZIP archive is opened by any of the Open* methods, such as OpenZip, OpenFromMemory, OpenBd, and related methods.

Important: PasswordProtect and Encryption are mutually exclusive.

If PasswordProtect = true, then Encryption should be 0.

The default value is false.

More Information and Examples
Determine if a Zip is Encrypted or Password-Protected
top
PathPrefix
// read/write
pub fn path_prefix(&self) -> String
pub fn set_path_prefix(&self, value: &str)

Gets or sets a path prefix that is prepended to ZIP entry paths for files appended from the local filesystem.

This is useful when you want all extracted files to appear under a specific subdirectory.

This property affects only the following methods:

  • AppendFiles
  • AppendFilesEx
  • AddFile
  • AppendOneFileOrDir

The PathPrefix value is prepended to the stored ZIP path for each appended filesystem file.

For example, set PathPrefix to subdir/ so that files are stored in the ZIP with subdir/ prepended to their paths. When extracted, the files will be placed under the subdir directory.

This property does not affect entries added entirely from memory, such as entries added using:

  • AddString
  • AddData
  • AddBd
  • AddSb

For in-memory entries, the ZIP entry path is determined solely by the filename/path argument passed to the method.

The default value is the empty string.

More Information and Examples
Add a Common Root Directory to ZIP Entries Using PathPrefix
top
PercentDoneScale
// read/write
pub fn percent_done_scale(&self) -> i32
pub fn set_percent_done_scale(&self, value: i32)
Introduced in version 9.5.0.49

Controls the granularity of PercentDone event callbacks.

This property is only applicable in programming environments that support event callbacks.

The value specifies what should be considered 100% complete for progress reporting purposes.

  • A value of 100 provides whole-percent progress updates.
  • A value of 1000 provides tenth-percent granularity.
  • For example, with a scale of 1000, a PercentDone callback value of 453 represents 45.3% complete.

Increasing this value allows for more frequent and finer-grained progress callbacks during long-running operations.

The value is automatically clamped to the range:

  • Minimum: 10
  • Maximum: 100000

The default value is 100.

top
PwdProtCharset
// read/write
pub fn pwd_prot_charset(&self) -> String
pub fn set_pwd_prot_charset(&self, value: &str)
Introduced in version 9.5.0.73

Specifies the character encoding used to convert the decrypt password into its binary byte representation for legacy password-protected ZIP archives that use Zip 2.0 encryption.

The default value is ansi.

Other possible values include:

  • cp850
  • cp437
  • Any supported Windows or OEM code page listed at the link below.

This property applies only to older Zip 2.0 password protection and is not used for AES-encrypted ZIP archives.

top
TempDir
// read/write
pub fn temp_dir(&self) -> String
pub fn set_temp_dir(&self, value: &str)

Directory used for temporary files during ZIP operations.

When overwriting an existing ZIP file, a temporary file is used to avoid corrupting the original ZIP if an error occurs.

The default value depends on the runtime environment.

top
UncommonOptions
// read/write
pub fn uncommon_options(&self) -> String
pub fn set_uncommon_options(&self, value: &str)
Introduced in version 9.5.0.84

Advanced options for uncommon scenarios.

  • ForceZip64 → Forces ZIP64 format even when not required.

The default value is the empty string.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

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

top
Version
// read-only
pub fn version(&self) -> String

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

More Information and Examples
How to get the Chilkat version at runtime.
top
Zipx
// read/write
pub fn zipx(&self) -> bool
pub fn set_zipx(&self, value: bool)

If true, creates ZIPX archives using the most appropriate compression method for each file.

The default value is false.

top
ZipxDefaultAlg
// read/write
pub fn zipx_default_alg(&self) -> String
pub fn set_zipx_default_alg(&self, value: &str)

Default compression algorithm used when creating ZIPX archives.

  • Possible values include:
    • deflate
    • ppmd
    • lzma
    • bzip2
    • deflate64

The default value is deflate.

top

Methods

AddBd
pub fn add_bd(&self, path_in_zip: &str, bd: &BinData) -> Result<()>
Introduced in version 11.0.0

Adds the contents of a BinData object as a new entry in the ZIP archive.

  • pathInZip specifies the filename and optional directory path stored within the ZIP.
  • The bytes contained in bd become the contents of the ZIP entry.
  • The entry is added to the in-memory ZIP object and is not written to disk until WriteZip, WriteZipAndClose, WriteBd, or WriteToMemory is called.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Binary Data to a ZIP Using AddBd
top
AddEmpty
pub fn add_empty(&self, is_dir: bool, path_in_zip: &str) -> Result<()>
Introduced in version 11.0.0

Adds an empty file or directory entry to the ZIP archive.

  • If isDir = true, an empty directory entry is created.
  • If isDir = false, an empty file entry is created.
  • pathInZip specifies the path stored in the ZIP archive.

This method is useful when directory structure entries must exist even if no files are present.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Create Empty File and Directory Entries in a ZIP
top
AddEncoded
pub fn add_encoded(&self, path_in_zip: &str, encoding: &str, data: &str) -> Result<()>
Introduced in version 11.0.0

Adds encoded binary data as a ZIP entry.

  • encoding specifies how data is encoded.
  • Common encodings include base64 and hex.
  • The decoded binary bytes become the contents of the ZIP entry.

This method is useful when binary data already exists in textual encoded form.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Base64-Encoded Data to a ZIP Using AddEncoded
top
AddFile
pub fn add_file(&self, local_path: &str, save_extra_path: bool) -> Result<()>
Introduced in version 11.0.0

Adds a file or directory from the local filesystem to the ZIP archive.

  • If localPath is an absolute path and saveExtraPath = true, the stored ZIP path includes the relative directory structure.
  • If saveExtraPath = false, only the filename is stored.
  • If localPath is already relative, the relative path is stored as-is regardless of saveExtraPath.

This method adds a reference to the file or directory in the local filesystem. The file data is not immediately read or compressed.

The actual file contents are consumed only when a Write* method is called, such as:

  • WriteZip
  • WriteZipAndClose
  • WriteBd
  • WriteToMemory

This allows files and data entries to be accumulated in the in-memory ZIP object prior to writing the final ZIP archive.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Files to a ZIP Using AddFile
top
AddNoCompressExtension
pub fn add_no_compress_extension(&self, file_extension: &str)

Adds a file extension to the internal "no-compression" list.

Files having these extensions are stored without compression because they are already compressed or because compression would provide little benefit.

For example:

  • .zip
  • .jpg
  • .png
  • .gz

The extension may be specified with or without the leading dot.

Additional extensions remain active for the lifetime of the Zip object unless removed with RemoveNoCompressExtension.

top
AddSb
pub fn add_sb(&self, path_in_zip: &str, sb: &StringBuilder, charset: &str) -> Result<()>
Introduced in version 11.0.0

Adds the contents of a StringBuilder object as a text entry in the ZIP archive.

  • The text is converted to bytes using the specified charset.
  • pathInZip specifies the filename stored in the ZIP.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Text from a StringBuilder to a ZIP Using AddSb
top
AddString
pub fn add_string(&self, path_in_zip: &str, content: &str, charset: &str) -> Result<()>
Introduced in version 11.0.0

Adds a string as a text file entry in the ZIP archive.

  • The string is converted to bytes using the specified charset.
  • pathInZip specifies the path stored within the ZIP archive.

This method is useful for dynamically generating text files directly in memory.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Text Files to a ZIP Using AddString
top
AppendFiles
pub fn append_files(&self, file_pattern: &str, recurse: bool) -> Result<()>

Adds one or more files matching a wildcard pattern.

  • The wildcard character * matches zero or more characters.
  • If recurse = true, subdirectories are processed recursively.
  • If recurse = false, only the current directory is searched.

For example:

AppendFiles("c:/temp/*.txt", false)

This method only updates the in-memory ZIP object. The ZIP file itself is not written until a Write* method is called.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Multiple Files to a ZIP Using AppendFilesControlling paths within a ZipZip Append Files Verbose Logging
top
AppendFilesEx
pub fn append_files_ex(&self, file_pattern: &str, recurse: bool, save_extra_path: bool, archive_only: bool, include_hidden: bool, include_system: bool) -> Result<()>

Advanced version of AppendFiles with additional filtering and path options.

  • saveExtraPath controls whether the extra leading path information from the filePattern is preserved in the ZIP.
  • archiveOnly applies only on Windows and limits processing to files having the archive attribute set.
  • includeHidden controls whether hidden files are included.
  • includeSystem controls whether files with the System attribute are included.

This method adds references to files in the in-memory ZIP object. No ZIP file is written until a Write* method is called.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Recursively Add Files to a ZIP Using AppendFilesEx
top
AppendZip
pub fn append_zip(&self, zip_path: &str) -> Result<()>

Note: This method is currently not working and will be fixed in v11.5.0

Adds all entries from another existing ZIP archive into the current ZIP object.

The zipPath argument specifies the path of a ZIP file located in the local filesystem.

All entries from the specified ZIP archive are appended to the current in-memory ZIP object.

The ZIP archive itself is not rewritten until a Write* method is called.

This method is useful for merging the contents of multiple ZIP archives into a single ZIP.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Merge ZIP Archives Using AppendZip
top
CloseZip
pub fn close_zip(&self)

Closes the currently open ZIP archive and clears all entries from the Zip object.

This method has the same effect as calling NewZip without specifying a filename.

top
DeleteEntry
pub fn delete_entry(&self, entry: &ZipEntry) -> Result<()>

Removes a ZIP entry from the current ZIP object.

The ZIP file itself is not rewritten until a Write* method is called.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Remove an Entry from an Existing ZIP Using DeleteEntry
top
EntryAt
pub fn entry_at(&self, index: i32, entry: &ZipEntry) -> Result<()>
Introduced in version 11.0.0

Retrieves the ZIP entry at the specified zero-based index.

  • The first entry is at index 0.
  • The matching entry is returned in the supplied ZipEntry object.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Iterate Over ZIP Entries Using EntryAtIterate Through ZIP Entries Using EntryAt and ZipEntry.GetNext
top
EntryById
pub fn entry_by_id(&self, id: i32, entry: &ZipEntry) -> Result<()>
Introduced in version 11.0.0

Finds a ZIP entry by its unique EntryID.

The matching entry is returned in the supplied ZipEntry object.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Find a ZIP Entry by EntryID Using EntryById
top
EntryMatching
pub fn entry_matching(&self, pattern: &str, entry: &ZipEntry) -> Result<()>
Introduced in version 11.0.0

Finds the first ZIP entry whose stored path matches a wildcard pattern.

  • The wildcard character * matches zero or more characters.
  • The comparison is performed against the full stored ZIP path.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Find ZIP Entries Matching a Wildcard Pattern Using EntryMatchingIterate Through Matching ZIP Entries Using EntryMatching and ZipEntry.GetNextMatch
top
EntryOf
pub fn entry_of(&self, path_in_zip: &str, entry: &ZipEntry) -> Result<()>
Introduced in version 11.0.0

Finds a ZIP entry whose stored path exactly matches pathInZip.

The matching entry is returned in the supplied ZipEntry object.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Find a ZIP Entry by Exact Path Using EntryOf
top
ExcludeDir
pub fn exclude_dir(&self, dir_name: &str)

Adds a directory name to the exclusion list used by recursive append operations.

  • All directories having the specified name are skipped.
  • The comparison is case-insensitive.
  • Call multiple times to exclude multiple directory names.

This affects methods such as AppendFiles and AppendFilesEx.

More Information and Examples
Exclude Multiple Directories When Adding Files to a ZIPZIP a Visual Studio Project and Exclude Build Artifacts
top
ExtractExe
pub fn extract_exe(&self, exe_path: &str, dir_path: &str) -> Result<()>
Introduced in version 9.5.0.44

Extracts files from a Chilkat-created self-extracting EXE.

  • Files are extracted into dirPath.
  • Subdirectories are automatically created as needed.
  • If the EXE is encrypted, DecryptPassword must be set before extraction.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
GetDirectoryAsXML
pub fn get_directory_as_xml(&self) -> Result<String>

Returns the ZIP directory structure as an XML document.

The returned XML contains information about the entries currently contained within the ZIP archive, including files and directories.

This method is useful for inspecting ZIP contents without extracting files.

Returns the XML document as a string.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Get ZIP Directory Information as XML
top
GetExeConfigParam
pub fn get_exe_config_param(&self, name: &str) -> Result<String>

(Windows only, for creating self-extracting EXE's)

Returns the value of a configuration parameter embedded within a self-extracting EXE.

The name argument should be one of the XML tag names described in the ExeXmlConfig property documentation.

For example:

  • MainTitle
  • MainCaption
  • SetupExe

Returns the parameter value as a string.

Returns Err(chilkat::Error) on failure.

top
GetMaxUncompressedSize
pub fn get_max_uncompressed_size(&self) -> Result<String>
Introduced in version 9.5.0.96

Returns the largest uncompressed file size contained within the ZIP archive.

The size is returned as a string rather than an integer because the value may exceed the range of a 32-bit integer.

This method is useful when:

  • Checking for extremely large files before extraction
  • Estimating required disk space
  • Detecting unusually large compressed entries

Returns the size as a decimal string.

Returns Err(chilkat::Error) on failure.

top
IsNoCompressExtension
pub fn is_no_compress_extension(&self, file_extension: &str) -> bool

Checks whether a file extension is contained in the internal "no-compression" extension list.

Files having extensions in this list are stored without compression because they are typically already compressed.

The extension may be specified with or without the leading dot.

For example, both of the following are valid:

  • .jpg
  • jpg

Returns true if the extension exists in the list, otherwise returns false.

top
IsPasswordProtected
pub fn is_password_protected(&self, zip_path: &str) -> bool

Checks whether a ZIP archive uses legacy Zip 2.0 password protection.

The zipPath argument specifies the path of a ZIP file in the local filesystem.

This method checks only for traditional Zip 2.0 password protection.

Returns true if the ZIP archive is password protected, otherwise returns false.

top
NewZip
pub fn new_zip(&self, zip_path: &str) -> Result<()>

Initializes a new empty ZIP archive.

  • If another ZIP archive is currently open, it is closed.
  • All existing in-memory ZIP entries are discarded.
  • The FileName property is set to zipPath.

No ZIP file is actually created until a Write* method is called.

This method resets the Zip object to a clean empty state.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Chilkat Zip API Concepts
top
OpenBd
pub fn open_bd(&self, bin_data: &BinData) -> Result<()>
Introduced in version 9.5.0.66

Opens a ZIP archive contained entirely within a BinData object.

This method allows ZIP archives to be processed entirely in memory without requiring a filesystem file.

When a ZIP archive is opened:

  • PasswordProtect is automatically set if legacy Zip 2.0 encryption is detected.
  • Encryption is automatically set if strong encryption is detected.
  • A value of 4 for Encryption indicates WinZip-compatible AES encryption.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Create Enveloping XML Digital Signature
top
OpenEmbedded
pub fn open_embedded(&self, exe_filename: &str, resource_name: &str) -> Result<()>

(Windows only)

Opens a ZIP archive embedded as a resource within a Windows executable.

  • exeFilename specifies the EXE file path.
  • resourceName specifies the embedded resource name containing the ZIP data.

This method is useful when ZIP archives are packaged within Windows applications.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
OpenZip
pub fn open_zip(&self, zip_path: &str) -> Result<()>

Opens a ZIP archive from the local filesystem.

The zipPath argument specifies the path of the ZIP file to open.

Encrypted ZIP archives may be opened without providing a password, but encrypted entries cannot be extracted until the correct password is provided using DecryptPassword.

When the ZIP archive is opened:

  • PasswordProtect is automatically set if legacy Zip 2.0 encryption is detected.
  • Encryption is automatically set if strong encryption is detected.
  • Encryption = 4 indicates WinZip-compatible AES encryption.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Open a Zip Archive
top
QuickAppend
pub fn quick_append(&self, zip_path: &str) -> Result<()>

Efficiently appends additional entries to an existing ZIP archive.

The zipPath argument specifies the path of an existing ZIP archive in the local filesystem.

This method avoids rewriting existing entries.

  • Existing ZIP entries remain unchanged.
  • New entries are appended to the end of the ZIP archive.
  • The ZIP central directory is updated accordingly.

This method is typically faster than rebuilding the entire ZIP archive.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Append Files to Existing Zip w/out Rewriting Entire Zip
top
RemoveNoCompressExtension
pub fn remove_no_compress_extension(&self, file_extension: &str)

Removes a file extension from the internal "no-compression" extension list.

After removal, files having this extension may be compressed normally.

The extension may be specified with or without the leading dot.

top
SetCompressionLevel
pub fn set_compression_level(&self, level: i32)

Sets the compression level for all file and data entries currently contained within the ZIP object.

  • 0 → No compression
  • 9 → Maximum compression

The default compression level is 6.

Important: This method should be called after files or data entries have already been added to the ZIP object.

The compression level cannot be changed for mapped entries originating from an already-open ZIP archive.

top
SetExclusions
pub fn set_exclusions(&self, exclude_patterns: &StringArray)

Specifies a collection of wildcard exclusion patterns used when adding files to the ZIP archive.

Each pattern may use the wildcard character * to match zero or more characters.

Files matching any exclusion pattern are skipped.

More Information and Examples
ZIP a Visual Studio Project and Exclude Build ArtifactsZip -- Exclude Files Based on Wildcard Matching
top
SetExeConfigParam
pub fn set_exe_config_param(&self, param_name: &str, param_value: &str)

(Windows only, for creating self-extracting EXE's)

Sets a configuration parameter embedded within a self-extracting EXE created by WriteExe or WriteExe2.

The paramName should be one of the XML configuration tag names described in the ExeXmlConfig property documentation.

For example:

SetExeConfigParam("MainUnzipBtn","Extract")

This changes the text displayed on the self-extractor's main unzip button.

top
Unzip
pub fn unzip(&self, dir_path: &str) -> i32

Extracts all files and directories from the ZIP archive.

  • dirPath specifies the destination directory.
  • Subdirectories are automatically created as needed.

Returns the number of files extracted.

Returns -1 if a failure occurs.

More Information and Examples
Unzip
top
UnzipInto
pub fn unzip_into(&self, dir_path: &str) -> i32

Extracts all files into a single directory.

All directory path information stored within the ZIP archive is ignored.

If multiple files have the same filename, later extracted files overwrite earlier ones.

Returns the number of files extracted, or -1 on failure.

More Information and Examples
Unzip all Files to a Single Directory (Ignoring Subdirectories in Zip)
top
UnzipMatching
pub fn unzip_matching(&self, dir_path: &str, pattern: &str, verbose: bool) -> i32

Extracts only entries whose stored paths match a wildcard pattern.

  • The wildcard character * matches zero or more characters.
  • If no wildcard is used, an exact filename match is required.

Subdirectories are automatically created as needed.

Returns the number of files extracted, or -1 on failure.

More Information and Examples
Unzip Files Matching a Pattern (such as *.xml)
top
UnzipMatchingInto
pub fn unzip_matching_into(&self, dir_path: &str, pattern: &str, verbose: bool) -> i32

Extracts matching entries into a single directory while ignoring all stored ZIP path information.

Matching behavior is identical to UnzipMatching.

If duplicate filenames occur, later extracted files overwrite earlier ones.

Returns the number of files extracted, or -1 on failure.

top
UnzipNewer
pub fn unzip_newer(&self, dir_path: &str) -> i32

Extracts only files that:

  • Do not already exist
  • Or have older modification timestamps than the ZIP entry

Subdirectories are automatically created as needed.

Returns the number of files extracted, or -1 on failure.

More Information and Examples
Extract Only Newer Files Using UnzipNewer
top
VerifyPassword
pub fn verify_password(&self) -> bool

Verifies that the current DecryptPassword value is correct for the currently opened ZIP archive.

This method allows password validation before attempting extraction.

Returns true if the password is valid, otherwise returns false.

More Information and Examples
Verify a Zip's Password
top
WriteBd
pub fn write_bd(&self, bin_data: &BinData) -> Result<()>
Introduced in version 9.5.0.66

Writes the ZIP archive to a BinData object instead of a filesystem file.

The generated ZIP archive exists entirely in memory.

The ZIP data written by this method may later be opened using OpenBd.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Create Zip in a BinData Object
top
WriteExe
pub fn write_exe(&self, exe_filename: &str) -> Result<()>

(Windows only, for creating self-extracting EXE's)

Creates a Windows self-extracting executable (EXE).

The generated EXE contains both the extraction logic and the ZIP archive data.

There are no limitations on:

  • Total ZIP size
  • Individual file size
  • Number of files

The generated EXE supports the following command-line arguments:

  • -log logFileName
  • -unzipDir unzipDirectoryPath
  • -pwd password
  • -ap autoRunParams

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
More information about self-extracting executables.Create Self-Extractor
top
WriteZip
pub fn write_zip(&self) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Zip and Keep Open
top
WriteZipAndClose
pub fn write_zip_and_close(&self) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Zip
top

Events

All Chilkat methods are synchronous: the call returns when the work is done. During a call, Zip raises three events so your application can show progress and offer a way out. Implement the chilkat::EventHandler trait (every method has a do-nothing default, so implement only the events you need) and install it with set_event_handler:

use chilkat::{Zip, EventHandler};

struct Progress;

impl EventHandler for Progress {
    fn percent_done(&mut self, pct: i32) -> bool {
        println!("{pct}%");
        false   // return true to abort the method in progress
    }
    fn progress_info(&mut self, name: &str, value: &str) {
        println!("{name}: {value}");
    }
}

let zip = Zip::new();
zip.set_event_handler(Progress);
zip.set_heartbeat_ms(250);   // raise abort_check 4 times per second during Chilkat calls

For a one-off handler the closure methods avoid writing a type; they may be combined, and each replaces the previously set closure for that one event (installing a closure removes a trait handler set earlier, and vice versa):

zip.on_percent_done(|pct| { println!("{pct}%"); false });
zip.on_progress_info(|name, value| println!("{name}: {value}"));
pub fn set_event_handler<H: EventHandler>(&self, handler: H)

Installs handler as the receiver of this object's events, replacing any handler or closures set earlier. The object owns the handler, which must be Send + 'static.

pub fn clear_event_handler(&self)

Removes the handler and any closures; events are no longer delivered.

AbortCheck fires at regular intervals controlled by the HeartbeatMs property (0, the default, disables it); PercentDone fires when an operation's completion percentage is known; ProgressInfo delivers named progress values. Returning true from abort_check or percent_done aborts the running method, which then returns Err.

Events fire on the thread that called the method, before that method returns. A panic inside a handler aborts the running method and is re-raised to the caller once the native library has returned, so it never unwinds through C frames. To abort a long operation from another thread, share an Arc<AtomicBool> with an abort_check handler, or set the object's AbortCurrent property to true.

AbortCheck
// EventHandler trait method; closure form: on_abort_check(FnMut() -> bool)
fn abort_check(&mut self) -> bool

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

zip.set_heartbeat_ms(250);   // call abort_check 4 times per second

let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let flag = stop.clone();
zip.on_abort_check(move || flag.load(std::sync::atomic::Ordering::Relaxed));
// ... another thread may now abort the method in progress with stop.store(true, Ordering::Relaxed)
top
PercentDone
// EventHandler trait method; closure form: on_percent_done(FnMut(i32) -> bool)
fn percent_done(&mut self, pct: i32) -> bool

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pct_done argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pct_done equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to true. This will cause the method to terminate and return a failure status or corresponding failure value.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

zip.on_percent_done(|pct| {
    // pct ranges from 1 to 100.
    println!("Percent done: {pct}");
    false   // return true to abort the method in progress
});
top
ProgressInfo
// EventHandler trait method; closure form: on_progress_info(FnMut(&str, &str))
fn progress_info(&mut self, name: &str, value: &str)

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

zip.on_progress_info(|name, value| println!("{name}: {value}"));
top