Zip Configuration

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

Zip Configuration Settings

AESGenerateUniqueKeys:   Whether to generate unique keys for each file encrypted.

This setting controls the algorithm that generates AES cryptographic keys from the Password specified. For added security, a random salt value is generated, and a unique key will be generated for every unique combination of Password and salt.

If true, a unique salt value and key will be generated for each file encrypted. If false, a single salt value and key will be generated for all encrypted files in the archive.

If you are encrypting a lot of files, the value of this setting can have a substantial effect on both security and performance. By default, the class will set this to false.

CheckForFileLocks:   If true, the component requests an exclusive lock during initialization.

If set to true, the component will request an exclusive lock during initialization to ensure there are no other processes locking a file. This is a temporary lock and is released before work is done. This is especially useful when another process has a partial lock on a file, for instance when Outlook is working with a .pst.

False by default.

CloseArchiveAfterCompress:   Whether to close the archive after calling Compress.

This setting determines whether the archive is closed after calling Compress. When set to False the archive remains open and additional files can be added at any time. This allows files to be added to the archive incrementally as they become available. For instance:

zip.Config("CloseArchiveAfterCompress=false");

//Add one file
zip.Files.Add(new ZIPFile("..\\..\\files\\test.txt"));
zip.Compress();

//Add another file
zip.Files.Clear();
zip.Files.Add(new ZIPFile("..\\..\\files\\test2.txt"));
zip.Compress();

//Ready to finish creating the archive
zip.Config("CloseArchiveAfterCompress=true");

zip.Files.Clear();
zip.Compress(); //Must be called to finish archive creation
As illustrated in the code above this setting must be set to True after all files are added to the archive and Compress must be called a final time to complete the archive creation.

The default value of this setting is True.

CloseStreamAfterCompress:   If true, the component will close the output stream after compression.

This property is true by default. Therefore, by default, the output stream will be closed after compression is completed. In order to keep streams open after the compression completes, you must set this config to false.

CompressionMethod:   Used to set the method of compression.

This is used to specify different compression methods. By default the class uses the Deflate compression method (a value of 0). Supported values are:

ValueMethod
0Deflate (default)
1PPMd

EnableStreamingEncryption:   Whether to allow streaming and encryption simultaneously.

If true, the class will allow encrypted files to be streamed out during compression; i.e., the class will allow you to compress with WriteToProgressEvent set to true or with SetArchiveOutputStream set to a valid stream and a Password has been set.

Use extreme caution when setting this option, as streamed and encrypted zip files may be unreadable by other zip software.

Encoding:   Encoding to be used for filenames.

The encoding to be used for filenames, and for Zip files, the password. The file contents are treated as binary data, and so encoding does not apply to the contents. At present only supported for Zip and Jar.

Default - Zip: "" (use default encoding of current machine, if possible)

Default - Jar: "UTF-8"

Example - This would set encoding to Japanese Shift-JIS.

Zip1.Config("Encoding=SJIS");

ExcludedAttributes:   Attributes of files to be excluded.

Files with attributes matching those specified will be excluded from compression or decompression. May be set to any combination of H (hidden), S (system), A (archive), and R (read-only). (Example: "HSR") Alternatively, may be set to a bitmask of the following flags: Readonly (1), Hidden (2), System (4), Directory (16), Archive (32).

For Java, when compressing, attributes other than "H" and "R" will be ignored (due to JRE limitations).

Default: "" (no excluded attributes)

ExtractFilesOnly:   Whether to only extract the files contained within the archive.

If true, only the files contained within the ArchiveFile are extracted directly to the specified ExtractToPath. Folders contained within the ArchiveFile will not be created within the ExtractToPath. If an archive contains files with the same name, you can control whether or not they get overwritten by setting OverwriteFiles.

FileHashAlgorithm:   The algorithm to use when computing the file hash.

This setting specifies the algorithm (if any) to use when computing the hash for files within the archive. If specified, when Compress is called the hash will be computed for each file within the archive and Hash will be populated with the computed hash value. Possible values are:

  • "" (Default - no hash is computed)
  • "SHA1"
  • "SHA224"
  • "SHA256"
  • "SHA284"
  • "MD5"

ForceZip64Format:   Whether to explicitly compress a Zip64 format archive.

Setting this value to true will force the component to always create a Zip64 format archive when compressing. By default, this value is false and the component will detect whether or not compressing in Zip64 format is necessary.

MarkAsText:   Whether to mark files as text files.

If true, the class will mark files as text within the zip archive. This may allow decompression software on other platforms to translate between character sets, etc.

If false (the default), files will be written as binary. To mark some files as text and others as binary, it is recommended that you trap the BeginFile event and set this property value as appropriate for each file.

OverwriteReadonlyFiles:   Whether to overwrite readonly files.

If true, the class will overwrite readonly files when decompressing. If false (the default), the class will fire the Error event, instead, and will fail with an exception if the error is not trapped and explicitly ignored in the event.

PreserveModifiedTime:   Whether or not to preserve the original modified time on extracted files.

Specifies whether or not the modified time of the extracted files use the current time or the original time of the file in the archive.

When set to True (default) the extracted files will have the same modified time as the original file.

When set to False the modified time on the extracted files will be set to the current time.

VerifyPassword:   Check whether the specified Password can decrypt the archive without extracting files.

If the password set in the Password property can successfully decrypt the archive, this config will return the string "True". Otherwise, it will return the string "False". No files are extracted when this config is referenced.

For example:

Zip zip = new Zip();
zip.ArchiveFile = myArchive;
zip.Password = myPassword;
string verified = zip.Config("VerifyPassword");
// verified contains either "True" or "False"

WriteToProgressEvent:   Whether or not to write data to the Progress Event.

If WriteToProgressEvent is set to true, then all data produced through invocations of Extract, ExtractAll, and Compress will be written to the Progress event as well as to disk. Applications may stream out the compressed or decompressed data by trapping this event and copying the data.

If WriteToProgressEvent is set to false, the data will not be streamed out, and the Data parameter of the Progress event will contain null.

Note that if streaming is enabled the zip files written will be slightly larger. Moreover, zip files produced with WriteToProgressEvent may be incompatible with certain older zip utilities.

By default, Password encryption is not allowed for archives created with WriteToProgressEvent set to true. You may set the EnableStreamingEncryption setting to allow this, but streamed and encrypted zip files may be incompatible with other utilities.

By default, this config is set to false.

Base Configuration Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Tells the class whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The class will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the class does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g. RuntimeLicense, License File).
  • License Type: The type of license installed (e.g. Royalty Free, Single Server).
UseDaemonThreads:   Whether threads created by the class are daemon threads.

If set to True (default), when the class creates a thread the thread's Daemon property will be explicitly set to True. When set to False the class will not set the Daemon property on the created thread. The default value is True.

UseInternalSecurityAPI:   Tells the class whether or not to use the system security libraries or an internal implementation.

By default the class will use the system security libraries to perform cryptographic functions. Setting this to True tells the class to use the internal implementation instead of using the system's security API.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks ZIP 2020 Java Edition - Version 20.0 [Build 8300]