Creating a new ZIP archive

ZipCreate

To create a new ZIP archive, use ZipCreate. It has three, optional, Input Parameters:

• FilePath - the path to the ZIP file to create, including it's name. If you do not specify one, BigZip will create a temporary file in the temporary directory of the Server (probably C:\Windows\Temp).
• CompressionLevel - determines the effort BigZip uses to compress the files you add. 0 is the least effort, 9 the most. The more effort, the slower BigZip will be, but the smaller the end result is. The default value is 5, which is a good trade-off between speed and compression. Note that this value won't be used until you actually add a file to the archive.
• Password - optional password for protecting the ZIP archive. If you specify a password, the password is needed to extract a file from the archive. Note that regardless of whether a password is specified, the file names are always visible (e.g. in Windows), so it's not a full protection.

As Output Parameters, ZipCreate returns:

• ZipHandle - a magic Object that you need as Input Parameter to subsequent Actions to add files etc.
• FilePathCreated - the file path (including the file name) of the created ZIP archive. If you specified a FilePath as Input Parameter, it's equal to that value, otherwise ZipCreate returns the name of the temporary file.

Note that after the ZIP archive is created, it is also opened, and ready for adding files to.

Opening an existing ZIP archive

There are two ways to open an existing ZIP archive: you can open it directly from disk (by specifying its path), or you can open it from memory (e.g. when a user uploaded it via the browser). Note that opening a ZIP archive hardly uses any memory, as opposed to the standard ZIP Actions from the Platform's ZIP Extension, which loads the entire file in memory.

ZipLoadPath

Use ZipLoadPath if you want to open a ZIP archive that's located someplace the Server can reach it. Note this probably means this can't be a file you have stored locally on your PC! ZipLoadPath has two Input Parameters:

• FilePath - the path to the ZIP archive to open, including it's name.
• Password - if the ZIP is password protected, the password to allow access to the file content.

Like ZipCreate, it returns a ZipHandle, but since it doesn't create a new file, there's no FilePathCreated:

• ZipHandle - a magic Object that you need as Input Parameter to subsequent Actions to add files etc.

ZipLoadMemory

Use ZipLoadMemory if you want to open a ZIP archive that's present in memory, for example when the user uploaded it via an upload Screen, or when you retrieved the archive from the database. For further manipulation, it writes the entire file to disk, like ZipCreate, and returns the path of the created file. ZipLoadMemory has three input Parameters:

• ZipBinary - the content of the ZIP archive in memory, with data type Binary Data.
• FilePath - the path to the ZIP file to create, including it's name. If you do not specify one, BigZip will create a temporary file in the temporary directory of the Server (probably C:\Windows\Temp).
• Password - optional password for protecting the ZIP archive. If you specify a password, the password is needed to extract a file from the archive. Note that regardless of whether a password is specified, the file names are always visible (e.g. in Windows), so it's not a full protection.

As Output Parameters, ZipLoadMemory returns:

• ZipHandle - a magic Object that you need as Input Parameter to subsequent Actions to add files etc.
• FilePathCreated - the file path (including the file name) of the created ZIP archive. If you specified a FilePath as Input Parameter, it's equal to that value, otherwise ZipLoadMemory returns the name of the temporary file.

Listing files in a ZIP archive

ZipFileListGet

To retrieve a list of all the files and directories (a.k.a. folders) in a ZIP archive, use ZipFileListGet. It takes a ZipHandle as Input Parameter, and returns a List of entries (files or directories). Note this is meta data only, the actual files are not extracted. The Input Parameter:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.

Output Parameter:

• FileList - a Record List of ZipEntry Structures, which have the following format:
  • Name - the name of the file or directory.
  • IsDirectory - if False, the entry is a file, if True, the entry is a directory. Note that BigZip doesn't support adding directories to a ZIP archive, so this only pertains to ZIP archives that were created with different tooling.
  • Size - the original, uncompressed size of the file (0 in case of a directory).
  • CompressedSize - the size of the file inside the ZIP archive (0 in case of a directory).
  • CompressionRatio - value specifying the percentage of compression (0 means no compression, 99.9999... is maximum).
  • LastModified - the date/time of last modification of the file (in local file time).
  • CreationDateTime - the date/time when the file was created.
  • ModifiedTime - the date/time when the file was last modified.
  • AccessedTime - the date/time when the file was last accessed.

Note that there is both a LastModified and a ModifiedTime because of historical reasons. See e.g. here for more explanation.

Extracting a file from a ZIP archive

There are two ways to extract a file from a ZIP archive: writing it to disk, and loading it in memory. Note that since extracting a file does not alter the ZIP archive itself, the file is extracted directly (as opposed to adding or deleting a file from a ZIP archive, which is performed when saving the archive.)

FileGetPath

Use FileGetPath to extract a file from a ZIP archive, and write it directly to a file on disk. BigZip uses a technique that limits memory use while extracting, so that even very large files will be extracted without memory use increasing much. This as opposed to the standard ZIP Actions from the Platform's ZIP Extension, which loads the entire file in memory before you can save it, like FileGetMemory does. FileGetPath has the following Input Parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• FileName - name of the file to extract, as retrieved by using ZipFileListGet. Use the name as specified in the Name Attribute of the FileList Structure. This is including a possible directory path; if you were to omit the directory inside the ZIP archive, the file cannot be found.
• FileDirectory - optional path (without file name) as the destination of the extracted file. If you do not specify a path, the file will be written to the temporary directory (probably C:\Windows\Temp).

Output Parameter:

• FilePathCreated - the full path (including the file name) of the extracted file. Note that the name of the file in ZIP the archive is always used, there's no way to override it. Also note that if the file is inside a directory in the archive, the directory is also created (if it doesn't already exist), and the file written to that directory.

FileGetMemory

Use FileGetMemory if you want to extract a file from a ZIP archive and keep it in memory, e.g. to allow the user to download it. It has the following Input Parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• FileName - name of the file to extract, as retrieved by using ZipFileListGet. Use the name as specified in the Name Attribute of the FileList Structure. This is including a possible directory path; if you were to omit the directory inside the ZIP archive, the file cannot be found.

Output Parameter:

• FileContent - Binary Data containing the file content.

Adding a file to a ZIP archive

There are two ways to add a file to a ZIP archive: from disk, and from memory. As with ZIP archives themselves, if you want to add a file from disk, it needs to be accessible by the Server, so files stored on the user's local hard disk can only be added after uploading them in the browser. Note that the Actions will only collect meta data, and the file won't actually be added to the ZIP archive until it is saved.

FileAddPath

Use FileAddPath if you have a file stored on disk, and you want to add it to the ZIP archive. You need a ZipHandle from one of the Actions to create or open a ZIP archive, and the path to the file to add. Optionally you can also specify the name the file has to have inside the archive, if it must be different than the name on disk. Input Parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• FilePath - the path to the file to add to the archive, including it's name.
• FileName - optional name to use when adding the file; if not specified, the name is taken from the FilePath.

FileAddPath has no output parameters.

FileAddMemory

Use FileAddMemory if you have a file in memory, e.g. because a user uploaded it or it's stored in the database, and you want to add it to the ZIP archive. Input parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• FileContent - the content of the file in memory, with data type Binary Data.
• FilePath - the path to the file to add to the archive, including it's name.
• FileName - optional name to use when adding the file; if not specified, the name is taken from the FilePath.

FileAddMemory has no output parameters.

Replacing a file from a ZIP archive

There are two ways to replace the content of a file inside a ZIP archive: from disk, and from memory. As with ZIP archives themselves, if you want to add a file from disk, it needs to be accessible by the Server, so files stored on the user's local hard disk can only be added after uploading them in the browser. Note that the Actions will only collect meta data, and the file won't actually be replaced until the ZIP archive is saved.

FileReplacePath

Use FileReplacePath if you have a file stored on disk, and you want to add it to the ZIP archive replacing an existing file. You need a ZipHandle from one of the Actions to create or open a ZIP archive, and the path to the file to add. Input Parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• FilePath - the path to the file to add to the archive, including it's name.
• FileName - name of the file to replace. The new file will receive this name, not its original name.

FileReplacePath has no output parameters.

FileReplaceMemory

Use FileReplaceMemory if you have a file in memory, e.g. because a user uploaded it or it's stored in the database, and you want to add it to the ZIP archive replacing an existing file. Input parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• FileContent - the content of the file in memory, with data type Binary Data.
• FileName - name of the file to replace. The new file will receive this name.
• DateTime - date and time to use as CreationDate of the file in the archive. If you do not specify it (or NullDate() is specified), the CreationDate of the replaced file is used.

FileReplaceMemory has no output parameters.

Removing a file from a ZIP archive

To remove (a.k.a. delete) a file from a ZIP archive, use FileDelete. Note the file won't actually be removed from the ZIP archive until the archive is saved.

FileDelete

FileDelete removes a file from the ZIP archive. Input Parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• FileName - name of the file to delete.

FileDelete has no output parameters.

Applying all changes to (a.k.a. saving) a ZIP archive

To apply all changes to a ZIP archive, i.e. apply all FileAdd*, FileReplace* and FileDelete Actions, use ZipSave. When calling ZipSave, all added and replaced files will be compressed and added to the ZIP archive on disk, and all deleted files will removed from the archive. After saving, it is still possible to add, replace and delete files, but those changes will not be made until the next ZipSave.

ZipSave

Updates the ZIP archive, applying all changes made to it. Files added will be compressed and added, files replaced will be deleted and replaced by new files, which are compressed before they are added, and deleted files are deleted. Input Parameter:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.

Unloading a ZIP archive from memory

Normally, the ZIP archive will unload itself from memory automatically. However, if you handle multiple ZIP archives within a single Action, you may want to unload a ZIP archive explicitly, to free up memory for subsequent calls to BigZip (note that in general, memory usage should not be a problem, as BigZip uses little memory to begin with).  To do so, use ZipUnload.

ZipUnload

Unloads the ZIP file from memory. Note that any files retrieved with FileGetMemory are not unloaded. Also note that after calling ZipLoad, the ZipHandle is no longer valid. Using it will lead to unpredictable results (most likely an Exception). Input Parameter:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.

Changing compression level, password or encryption algorithm

Compression level, password and encryption algorithm can be set per file in a ZIP archive. To do so, change any of these properties before adding a file to the ZIP archive, and any subsequent addition will use the properties as set.

CfgCompressionLevelSet

Sets the compression level. Input parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• CompressionLevel - determines the effort BigZip uses to compress the files you add. 0 is the least effort, 9 the most. The more effort, the slower BigZip will be, but the smaller the end result is. The default value is 5, which is a good trade-off between speed and compression. Note that this value won't be used until you actually add a file to the archive.

CfgPasswordSet

Sets the password for encrypted files or removes the password for normal storage. Input parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• Password - the password is needed to extract a file from the archive. If it is empty, subsequent files added to the archive will not be encrypted. Note that regardless of whether a password is specified, the file names are always visible (e.g. in Windows), so it's not a full protection.

CfgEncryptionAlgorithmSet

Sets the encryption algorithm used for password protected files. Input parameters:

• ZipHandle - a valid ZIP archive handle returned by ZipCreate, ZipLoadPath or ZipLoadMemory.
• EncryptionAlgorithm - the encryption algorithm to be used for password protected files. Accepted values: 0 - no encryption, 1 - classic pkzip encryption (weak), 2 - WinZip AES encryption (128 key bits), 3 - WinZip AES encryption (256 key bits). Any other value will be set to 1 (classic).