# Zip Actions Plugin

Online Help

## Description

Zip is a zip archive action plugin. Whether you are looking for an easy way to extract files from a zip archive, or add files to a zip archive, the Zip Plugin is for you.

The Zip Plugin includes actions to perform the following tasks:

- Adding files to a Zip archive
- Extracting Files from a Zip archive
- Reading the contents of a Zip Archive

## Actions

Zip.Add
Zip.Extract
Zip.GetContents

### Zip.Add (string ZipFile, table Files, boolean IncludeFolderNames = true, string Password = "", number CompFactor = 5, function CallbackFunction = nil, boolean Recurse = false );

#### Description:

Adds files to a Zip archive.

#### ZipFile:

(string) The full path and file name of the Zip archive file.

#### Files:

(table) A table containing the full paths to all of the files you want to add. You can also use the * and ? wildcards in this table to add all files from one directory, for example, {"C:\\MyFolder\\*.*"}.

When a wildcard is used, each file will be added relative to the base folder. For example, if the file table references {"C:\\MyFolder\\*.*"} and "MyFolder" contains one file called "One.txt" and a folder called "MyInsideFolder" containing a file "Two.txt", the base folder would be "MyFolder". If you want to recurse subfolders, the Recurse parameter must be set to true.

#### IncludeFolderNames:

(boolean) Whether to preserve the relative directory structure in the archive when adding files with wildcards:

true - Include folder names so the structure can be recreated. (Default)
false - Don't include any relative folder names. (The Zip archive will have no internal directory structure.)

For example, given two files located at:
C:\MyFolder\One.txt
C:\MyFolder\MyInsideFolder\Two.txt
If the file table references {"C:\\MyFolder\\*.*"} and IncludeFolderNames and Recurse are set to true, the Zip archive structure would be:
One.txt
MyInsideFolder\Two.txt
If IncludeFolderNames is set to false, the Zip archive structure would be:
One.txt
Two.txt

Note: If no wildcards are used, no relative folder names will be preserved.

#### Password:

(string) The password to use to protect the Zip file. This password will be needed to extract the files. (This parameter is optional. If you don't want to protect the Zip file, just leave this parameter blank.)

#### CompFactor:

(number) The compression factor to use for the Zip file (0-9). 0 is the fastest and compresses the least, 9 is the slowest and compresses the most. The default is 5.

#### CallbackFunction:

(function) The name of a function that will be called whenever progress is made in adding a file to the Zip archive. (You can use this callback function to display the progress of each file's archiving in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

String - (string) A progress message that can be displayed.
Percent - (number) The progress percentage, corresponding to either the current file or the total action.
Status - (number) The status of the current callback message. Either ZIP_STATUS_MAJOR or ZIP_STATUS_MINOR. ZIP_STATUS_MAJOR means that the callback corresponds to the progress of the action as a whole. ZIP_STATUS_MINOR means that the callback corresponds to the progress of the current file.

The callback function should return a boolean value (true or false) indicating whether the archiving of the Zip file should continue:

true - Continue with the Zip file archiving.
false - Stop the Zip file archiving as soon as possible.

#### Recurse:

(boolean) Whether to recurse subfolders when wildcards are used:

true - Recurse subfolders when wildcards are used.
false - Don't recurse subfolders, even if a wildcard is used. (Default)

#### Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

#### Example 1:

    FileTable = {SessionVar.Expand("%SourceFolder%\\Prices.txt"), SessionVar.Expand("%SourceFolder%\\Catalog.txt")};
    Zip.Add("C:\\CompanyInformation\\Info.zip", FileTable, false, "", 5, nil);

The first line adds the file paths of "Prices.txt" and "Catalog.txt" to the table called "FileTable." The second line contains the Zip.Add action that adds the files from the "FileTable" table to the Zip file called "Info.zip."

#### Example 2:

    -- Prompt the user to select files to add to the zip archive.
    archive_files = Dialog.FileBrowse(false, "Files to Add", SessionVar.Expand("%DesktopFolder%"), "All Files (*.*)|*.*|", "", "dat", true, false);

    -- Check to see if an error occurred, or the user cancelled.
    if (archive_files[1] ~= "CANCEL") and (archive_files ~= nil) then

        -- Show the status dialog.
        StatusDlg.Show();

        -- Add the chosen files to the zip archive.
        Zip.Add(SessionVar.Expand("%DesktopFolder%\\NewArchive.zip"), archive_files, true, "", 5, nil);

        -- Get the error code of the zip.add action.
        error = Application.GetLastError();

        -- Hide the status dialog.
        StatusDlg.Hide();

        -- If it succeeded, display a success message and open the folder. Otherwise display the error message.
        if (error == 0) then
            Dialog.Message("Success", "The files were successfully archived.", MB_OK, MB_ICONINFORMATION);

            -- Open the folder where the zip file was created.
            File.ExploreFolder(SessionVar.Expand("%DesktopFolder%"), SW_SHOWNORMAL);
        else
            Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
        end
    end

A file browse dialog is displayed allowing the user to select files they would like added to a Zip archive. The selected files are then added to a Zip archive created on their desktop. If the process is successful, a success message is displayed. If there was an error, the error code message is shown.

### Zip.Extract string ZipFile, table Files, string Destination, boolean Recurse = true, boolean UseInternalFolders = true, string Password = "", number Overwrite = 0, function CallbackFunction = nil);

#### Description:

Extracts files from a Zip archive.

#### ZipFile:

(string) The full path and file name of the Zip archive file.

#### Files:

(table) A table containing the list of files to extract. Use {"*.*"} to extract all files from the Zip archive.

Note: You can also use the * and ? wildcards in the table to extract multiple files.
Wildcards are special symbols that can be used to represent a range of characters in a search:
* - any combination of characters
? - any single character
Examples:
a*le - matches ale, apple, angle, etc.
s?n - matches sun, son, sin, s4n, etc.

#### Destination:

(string) The folder path to extract the files to.

#### Recurse:

(boolean) Whether to recurse into subfolders as it searches for files to extract:

true - Recurse into subfolders when extracting files. (Default)
false - Don't recurse into subfolders.

Note: This is primarily useful when wildcards are used in the files you want to extract.
Wildcards are special symbols that can be used to represent a range of characters in a search:
* - any combination of characters
? - any single character
Examples:
a*le - matches ale, apple, angle, etc.
s?n - matches sun, son, sin, s4n, etc.

#### UseInternalFolders:

(boolean) Whether to recreate the internal file structure of the Zip file when extracting files:

true - The internal file structure will be recreated. (Default)
false - The internal file structure will be ignored and all files will be extracted to the root of the destination folder.

#### Password:

(string) The password required to extract files from the Zip file. (This parameter is optional and only needed if you password protected the Zip file. If no password is required, just leave this parameter blank. )

#### Overwrite:

(number) Whether to overwrite any already existing files in the destination folder when extracting. Choose from:

CONSTANT | VALUE | DESCRIPTION
ZIP_OVERWRITE_NEVER | 0 | Do not overwrite any files. (Default)
ZIP_OVERWRITE_NEWER | 1 | Only overwrite a file if the one being extracted is newer.
ZIP_OVERWRITE_ALWAYS | 2 | Overwrite all existing files with the ones being extracted.

#### CallbackFunction:

(function) The name of a function that will be called whenever progress is made when extracting each file from the Zip archive. (You can use this callback function to display the progress of each file's extraction in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

String - (string) The full destination path and file name currently being extracted from the Zip archive.
Percent - (number) The progress percentage, corresponding to either the current file or the total action.
Status - (number) The status of the current callback message. Either ZIP_STATUS_MAJOR or ZIP_STATUS_MINOR. ZIP_STATUS_MAJOR means that the callback corresponds to the progress of the action as a whole. ZIP_STATUS_MINOR means that the callback corresponds to the progress of the current file.

The callback function should return a boolean value (true or false) indicating whether the extraction of the Zip file should continue:

true - Continue with the Zip file extraction.
false - Stop the Zip file extraction as soon as possible.

#### Returns

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

#### Example 1:

    Zip.Extract("C:\\temp\\downloads\\graphics.zip", {"*.*"}, "C:\\Graphics", true, true, "", 3, nil);

Extracts all of the files from the Zip file called "graphics.zip" to "C:\Graphics" on the user's system. If any of the files already exist in the destination, they will be overwritten.

#### Example 2:

    -- Allow the user to select a directory to unzip the files.
    target_folder = Dialog.FolderBrowse("Select a Folder", "C:\\");

    -- Check to see if the user cancelled or an error occurred.
    if (target_folder ~= "CANCEL") and (target_folder ~= "") then
        -- Gets a list of the contents of a zip file.
        zip_contents = Zip.GetContents("C:\\Temp\\Downloads\\Docs\\Info.zip", true);

        -- Get the error code of the last action.
        error = Application.GetLastError();

        -- If an error occurred, display the error code message.
        if (error ~= 0) then
            Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
        else
            -- Take the table and turn it into a string with newlines for displaying.
            zip_contents_display = Table.Concat(zip_contents, "\r\n", 1, TABLE_ALL);

            -- Ask the user if they are sure they would like to unzip the contents.
            result = Dialog.Message("Information", "The following files will be unzipped:\r\nClick the Cancel button to abort the process.\r\n\r\n"..zip_contents_display, MB_OKCANCEL)

            -- If the user clicked Ok, unzip the files.
            if (result == IDOK) then
                -- Show the status dialog.
                StatusDlg.Show();
                -- Extract the contents of the Zip file.
                Zip.Extract("C:\\Temp\\Downloads\\Docs\\Info.zip", {"*.*"}, target_folder, true, true, "", ZIP_OVERWRITE_NEVER, nil);

                -- Check the error code for the last action.
                error = Application.GetLastError();

                -- Hide the status dialog.
                StatusDlg.Hide();

                -- If an error occurred, display the error code message.
                if (error ~= 0) then
                    Dialog.Message("Errror", tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
                else
                    Dialog.Message("Success", "The unzipping was successful.", MB_OK, MB_ICONINFORMATION);
                end
            end
        end
    end

This example first prompts the user to select a folder using the Dialog.FolderBrowse action. This folder will be used to unzip the files to. The user is then presented with a dialog containing the names of the files that will be unzipped and allows them to abort the process. If the user clicks Ok, the files are unzipped to the folder they selected. Notification will be given at the end of the process as to whether or not the procedure was successful.

### table Zip.GetContents (string ZipFile, boolean IncludeFolderNames = true);

#### Description:

Returns the list of files within a given Zip file.

#### ZipFile:

(string) The full path and file name of the Zip archive file.

#### IncludeFolderNames:

(boolean) Whether to include any folders in the list:

true - Any internal folders will be included in the list as separate entries. (Default)
false - Any internal folders will be omitted from the list. (The file paths will still have folder names in them, however the folders will not be included as separate entries.)

#### Returns:

(table) A table containing a list of the contents of the Zip file. If the Zip file is empty or an error occurs, nil is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.

#### Example 1:

    zip_contents = Zip.GetContents("C:\\Temp\\Downloads\\Docs\\Info.zip", true);

Gets a list of the contents within the Zip file "Info.zip" and returns it in the table called "zip_contents."

#### Example 2

    -- Allow the user to select a directory to unzip the files.
    target_folder = Dialog.FolderBrowse("Select a Folder", "C:\\");

    -- Check to see if the user cancelled or an error occurred.
    if (target_folder ~= "CANCEL") and (target_folder ~= "") then
        -- Gets a list of the contents of a zip file.
        zip_contents = Zip.GetContents("C:\\Temp\\Downloads\\Docs\\Info.zip", true);

        -- Get the error code of the last action.
        error = Application.GetLastError();

        -- If an error occurred, display the error code message.
        if (error ~= 0) then
            Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
        else
            -- Take the table and turn it into a string with newlines for displaying.
            zip_contents_display = Table.Concat(zip_contents, "\r\n", 1, TABLE_ALL);

            -- Ask the user if they are sure they would like to unzip the contents.
            result = Dialog.Message("Information", "The following files will be unzipped:\r\nClick the Cancel button to abort the process.\r\n\r\n"..zip_contents_display, MB_OKCANCEL)

            -- If the user clicked Ok, unzip the files.
            if (result == IDOK) then
                -- Show the status dialog.
                StatusDlg.Show();
                -- Extract the contents of the Zip file.
                Zip.Extract("C:\\Temp\\Downloads\\Docs\\Info.zip", {"*.*"}, target_folder, true, true, "", ZIP_OVERWRITE_NEVER, nil);

                -- Check the error code for the last action.
                error = Application.GetLastError();

                -- Hide the status dialog.
                StatusDlg.Hide();

                -- If an error occurred, display the error code message.
                if (error ~= 0) then
                    Dialog.Message("Errror", tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
                else
                    Dialog.Message("Success", "The unzipping was successful.", MB_OK, MB_ICONINFORMATION);
                end
            end
        end
    end

This example first prompts the user to select a folder using the Dialog.FolderBrowse action. This folder will be used to unzip the files to. The user is then presented with a dialog containing the names of the files that will be unzipped and allows them to abort the process. If the user clicks Ok, the files are unzipped to the folder they selected. Notification will be given at the end of the process as to whether or not the procedure was successful.

## Error Codes

0 | (Zip.OK) | - | (no error)
2600 | (Zip.REENTER_ERROR) | - | Could not reenter the zip file.
2601 | (Zip.ZIP_UNEXPECTED_EOF) | - | Unexpected end of zip file.
2602 | (Zip.ZIP_FILE_STRUCTURE_ERROR) | - | Zip file structure error.
2603 | (Zip.ZIP_OUT_OF_MEMORY) | - | Out of memory.
2604 | (Zip.INTERNAL_LOGIC_ERROR) | - | Internal logic error.
2605 | (Zip.ENTRY_TOO_LARGE) | - | Entry too large to split.
2606 | (Zip.INVALID_COMMENT) | - | Invalid comment format.
2607 | (Zip.ZIP_TEST_FAILED) | - | Zip test failed or out of memory.
2608 | (Zip.ZIP_USER_CANCELLED) | - | User cancelled.
2609 | (Zip.TEMP_FILE_ERROR) | - | An error occurred when using a temp file.
2610 | (Zip.READ_SEEK_ERROR) | - | A read or seek error occurred.
2611 | (Zip.ERROR_NO_FILES) | - | No files were added to the zip file.
2612 | (Zip.MISSING_EMPTY_ZIP) | - | Missing or empty zip file.
2613 | (Zip.WRITING_ERROR) | - | Error writing to a file.
2614 | (Zip.OPEN_ERROR) | - | Couldn't open to write.
2615 | (Zip.BAD_CONTROL_PARAMETERS) | - | Bad control parameters.
2616 | (Zip.OPERATION_NO_COMPLETE) | - | Could not complete operation.
2617 | (Zip.OPEN_READ_ERROR) | - | Could not open a specified file to read.
2618 | (Zip.MEDIA_ERROR) | - | Media error. Disk not ready, hardware read/write error.
2619 | (Zip.MULTI_VOLUME_CONTROL_PARAM) | - | Bad Multi-Volume control parameters.
2620 | (Zip.MULTI_VOLUME_USAGE) | - | Improper usage of a Multi-Volume Zip File.
2621 | (Zip.UNZIP_UNEXPECTED_EOF) | - | Unexpected end of zip file, the zip file may be corrupted.
2622 | (Zip.UNZIP_STRUCTURE_ERROR) | - | The internal structure of the zip file is invalid.
2623 | (Zip.UNZIP_OUT_OF_MEMORY) | - | Out of memory, not enough memory was available to complete the action.
2624 | (Zip.UNZIP_FILE_NOT_FOUND) | - | The zip file could not be found.
2625 | (Zip.NOTHING_TO_EXTRACT) | - | There was nothing to extract in the unzip action.
2626 | (Zip.EXTRACT_VOLUME_ERROR) | - | An error occurred when trying to extract to the same volume.
2627 | (Zip.INDEX_OOB) | - | The index specified in the zip file was out of bounds.
2628 | (Zip.OUTPUT_CREATE_ERROR) | - | An error occurred when creating the output file.
2629 | (Zip.OPEN_ZIP_ERROR) | - | An error occurred when opening the zip file. The zip file may be locked or unavailable.
2630 | (Zip.CRC_EXTRACT_ERROR) | - | An extracted file has an incorrect CRC value and may be corrupted.
2631 | (Zip.UNZIP_OPERATION_CANCELLED) | - | The operation has been cancelled.
2632 | (Zip.FILE_SKIPPED_NO_PASSWORD) | - | A file was skipped during the extraction because it is encrypted and no password was specified, or the password was incorrect.
2633 | (Zip.FILE_SKIPPED_FORMAT) | - | A file was skipped because it used an unknown compression format.
2634 | (Zip.PASSWORD_ERROR) | - | Bad or missing decrypt code, either no password was specified, or the password was incorrect.
2635 | (Zip.BUSY_ERROR) | - | Busy error, the zip file could not be entered.
2636 | (Zip.VOLUME_ID_ERROR) | - | Could not extract volume ID item.
2637 | (Zip.ERROR_UNZIP_COMMAND_STRUCT) | - | A bad command structure was used when attempting to unzip the file.
2638 | (Zip.INTERNAL_CANCEL) | - | The operation was canceled through an internal function.
2639 | (Zip.FILE_SKIPPED_PASSWORD) | - | One or more of the files was skipped during the extraction phase. Usually this is caused by an incorrect password.
2640 | (Zip.DESTINATION_FULL) | - | The destination disk was full, and no more information could be written to it.
2641 | (Zip.ERROR_FOLDER_CREATE) | - | The destination folder could not be created.

## Change Log

### 2.0.0.1

- Fixed an issue where the help file may fail to open in certain browsers.

### 2.0.0.0

- Updated to version 2.0 of the plugin SDK.

## Additional Information

### Author:

Indigo Rose Corporation

### Copyright:

The Zip Actions Plugin is copyright © 2004-2015 Indigo Rose Software Design Corporation.

### Website:

http://www.indigorose.com

Copyright © 2004-2015 Indigo Rose Software Design Corporation.
All Rights Reserved.