Zip Actions Plugin

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:

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.

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

-- 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