zipAddFile (Function)

WINDEV, WEBDEV AND WINDEV MOBILE
ONLINE HELP

Version:

Home | Sign in | English

Functions for managing archives

Compression level of ZIP or 7z archives

Error codes

Adding a file that is already found in the archive

Subscript of files in the archive

Path kept (archives in WDZ or ZIP format)

Progress Bar

See also

zipAddFile (Function)

In french: zipAjouteFichier

Adds a file (of any type) into an archive in CAB, ZIP, WDZ and 7z, TAR or TGZ (TAR.GZ) format and compresses it. This function cannot be used on the RAR archives.

To add the files found in a directory, use zipAddDirectory.

Versions 15 and later

This function is now available for Android applications.

New in version 15

This function is now available for Android applications.

Versions 17 and later

This function is now available for iPhone/iPad applications.

New in version 17

This function is now available for iPhone/iPad applications.

Versions 18 and later

This function is now available in Android Widget mode.

This function now supports the 7z format.

New in version 18

This function is now available in Android Widget mode.

This function now supports the 7z format.

This function is now available in Android Widget mode.

This function now supports the 7z format.

Versions 19 and later

This function is now available in Windows Store apps mode.

New in version 19

This function is now available in Windows Store apps mode.

Versions 21 and later

This function is now available in Universal Windows 10 App mode.

This function now supports the TAR and TGZ (TAR.GZ) formats.

New in version 21

This function is now available in Universal Windows 10 App mode.

This function now supports the TAR and TGZ (TAR.GZ) formats.

This function is now available in Universal Windows 10 App mode.

This function now supports the TAR and TGZ (TAR.GZ) formats.

Example

See additional examples

MyArchive is zipArchive
// Create the archive
ResCreate = zipCreate(MyArchive, "C:\Temp\Archive.zip")
IF ResCreate = 0 THEN
// Add a file into an archive
ResAddFile = zipAddFile(MyArchive, ...
"C:\MyDirectory\MyFiles\File.pdf", zipDrive)
END
// Display an error message if the file was not added
IF ResAddFile <> 0 THEN
Error(zipMsgError(ResAddFile))
END

MyArchive is zipArchive
// Create the archive
ResCreate = zipCreate(MyArchive, "\Temp\Archive.zip")
IF ResCreate = 0 THEN
// Add a file into an archive
ResAddFile = zipAddFile(MyArchive, ...
"\MyDirectory\MyFiles\File.pdf", zipNone)
END
// Display an error message if the file was not added
IF ResAddFile <> 0 THEN
Error(zipMsgError(ResAddFile))
END

Syntax

Adding a file while specifying the path section to keep Hide the details

<Result> = zipAddFile(<Archive> , <File path> [, <Path section to keep> [, <Progress bar management>]])

<Result>: Integer

0 if the addition was performed,
an error code (value greater than 0) otherwise. For more details on these error codes, see the remarks.

<Archive>: Character string (with quotes) or zipArchive variable

Name of archive into which the file will be added.
This name can correspond to:
the name of an archive, defined by zipOpen or zipCreate.
Versions 15 and later
the name of a zipArchive variable.
New in version 15
the name of a zipArchive variable.
the name of a zipArchive variable.

<File path>: Character string (with quotes)

Path of the file to be added to the archive (260 characters maximum, 90 maximum in the case of an archive in TAR or TGZ format (TAR.GZ)). This path can be a full path or a path relative to the current directory. The wildcard characters (*,?) are not allowed in the file name.
The size of this file must not exceed 4 GB. Otherwise, an error occurs.
The access path to the file is a full path. Indeed, the notion of current directory does not exist on Pocket PC.
The access path to the file is a full path or a path relative to the working directory of the application (returned by fDataDir). Only the files found in the working directory can be added to the archive.

<Path section to keep>: Optional constant

Indicates the section of the file path that will be kept in the archive:
zipNone Keeps the file name and extension. For example: FileName.pdf
zipDirectory
(Default value) Keeps the different directories of the file path as well as the file name and extension. For example: \Directory\Files\FileName.pdf
zipDrive Keeps the full and absolute file path (name of disk, name of directories, file name and file extension). For example: C:\Directory\Files\FileName.pdf
For the ZIP format: This constant has no effect.
For the 7z format: This constant and zipDirectory will have the same effect.
This constant is not available as there is no root for the drive.
This constant and zipDirectory will have the same effect.
If you are using an archive in .CAB format, only the zipNone constant is taken into account. Indeed, the .CAB format cannot be used to save the paths inside the archive.
This parameter is not available: only the file name and extension are kept.

<Progress bar management>: Character string (with or without quotes)

Versions 21 and later
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
This parameter is not available.
New in version 21
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
This parameter is not available.
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
This parameter is not available.

Not available in Universal Windows 10 App

Adding a file while specifying the path to ignore Hide the details

<Result> = zipAddFile(<Archive> , <File path> [, <Path section to ignore> [, <Progress bar management>]])

<Result>: Integer

0 if the addition was performed,
an error code (value greater than 0) otherwise. For more details on these error codes, see the Remarks.

<Archive>: Character string (with quotes) or zipArchive variable

Name of archive into which the file will be added.
This name can correspond to:
the name of an archive, defined by zipOpen or zipCreate.
Versions 15 and later
the name of a zipArchive variable.
New in version 15
the name of a zipArchive variable.
the name of a zipArchive variable.

<File path>: Character string (with quotes)

Path of the file to be added to the archive (260 characters maximum, 90 maximum in the case of an archive in TAR or TGZ format (TAR.GZ)). This path can be a full path or a path relative to the current directory. The wildcard characters (*,?) are not allowed in the file name.
The size of this file must not exceed 4 GB. Otherwise, an error occurs.
The access path to the file is a full path. Indeed, the notion of current directory does not exist on Pocket PC.

<Path section to ignore>: Optional character string (with quotes)

Indicates the section of file path that must not be stored in the archive.
For example, in WINDEV, if the full path of the file added into the archive is: "C:\My Documents\Work\Report.doc" and if <Path section to ignore> is set to "C:\My Documents\", only the "Work\Report.doc" section will be kept.

<Progress bar management>: Character string (with or without quotes)

Versions 21 and later
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
This parameter is not available.
New in version 21
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
This parameter is not available.
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
This parameter is not available.

Adding a file found in a buffer (WDZ and ZIP format only) Hide the details

<Result> = zipAddFile(<Archive> , <File to add> , <Buffer management> , <Path to keep> [, <Progress bar management>])

<Result>: Integer

0 if the addition was performed,
an error code (value greater than 0) otherwise. For more details on these error codes, see the Remarks.

<Archive>: Character string (with quotes) or zipArchive variable

Name of archive into which the file will be added.
This name can correspond to:
the name of an archive, defined by zipOpen or zipCreate.
Versions 15 and later
the name of a zipArchive variable.
New in version 15
the name of a zipArchive variable.
the name of a zipArchive variable.

<File to add>: Buffer

Buffer that corresponds to the file content that will be added into the archive.

<Buffer management>: Constant

Mode for managing the buffer:
zipInMemory Saves the content of the buffer (i.e. the file) in the archive.

<Path to keep>: Character string (with quotes)

File path or file name associated with the buffer that will be kept in the archive.

<Progress bar management>: Optional character string (with or without quotes)

Versions 21 and later
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
New in version 21
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
The procedure must be a server procedure.

Versions 15 and later

Adding a file by using a zipArchivedFile variable Hide the details

<Result> = zipAddFile(<Archive> , <File> [, <Progress bar management>])

<Result>: Integer

0 if the addition was performed,
an error code (value greater than 0) otherwise. For more details on these error codes, see the Remarks.

<Archive>: Character string (with quotes) or zipArchive variable

Name of archive into which the file will be added.
This name can correspond to:
the name of an archive, defined by zipOpen or zipCreate.
the name of a zipArchive variable.

<File>: zipArchivedFile variable

Name of the zipArchivedFile variable that contains information about the file to add (including its content).
The file does not necessarily have to exist on the disk: only the information found in this parameter is taken into account.

<Progress bar management>: Optional character string (with or without quotes)

Versions 21 and later
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
New in version 21
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.

New in version 15

Adding a file by using a zipArchivedFile variable Hide the details

<Result> = zipAddFile(<Archive> , <File> [, <Progress bar management>])

<Result>: Integer

0 if the addition was performed,
an error code (value greater than 0) otherwise. For more details on these error codes, see the Remarks.

<Archive>: Character string (with quotes) or zipArchive variable

Name of archive into which the file will be added.
This name can correspond to:
the name of an archive, defined by zipOpen or zipCreate.
the name of a zipArchive variable.

<File>: zipArchivedFile variable

Name of the zipArchivedFile variable that contains information about the file to add (including its content).
The file does not necessarily have to exist on the disk: only the information found in this parameter is taken into account.

<Progress bar management>: Optional character string (with or without quotes)

Versions 21 and later
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
New in version 21
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.

Adding a file by using a zipArchivedFile variable Hide the details

<Result> = zipAddFile(<Archive> , <File> [, <Progress bar management>])

<Result>: Integer

0 if the addition was performed,
an error code (value greater than 0) otherwise. For more details on these error codes, see the Remarks.

<Archive>: Character string (with quotes) or zipArchive variable

Name of archive into which the file will be added.
This name can correspond to:
the name of an archive, defined by zipOpen or zipCreate.
the name of a zipArchive variable.

<File>: zipArchivedFile variable

Name of the zipArchivedFile variable that contains information about the file to add (including its content).
The file does not necessarily have to exist on the disk: only the information found in this parameter is taken into account.

<Progress bar management>: Optional character string (with or without quotes)

Versions 21 and later
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
New in version 21
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.
Mode for managing the progress bar. This parameter can correspond to:
the name of a Progress Bar control found in a window. The progress bar will display the addition and compression progress of the file being managed.
the name of a WLanguage procedure. This procedure has the following format:

<Procedure name> (<Current file>, <Progress percentage>)

where:
<Current file> corresponds to the name of the file currently processed.
<Progress percentage> corresponds to the progress percentage of the current file being added into the archive.
If you are using an archive in TAR or TGZ (TAR.GZ) format, the progress bar is updated at the end of file addition only.

Remarks

Use condition

Adding files into an archive can be performed if:

The archive exists (an archive is created by zipCreate).
The archive is accessible in read/write.
The archive is a single-part archive.
The size of the file is less than 4 GB.

Caution:

Archives in CAB format: The files must be added immediately after the archive creation. This format cannot be used to add files into an existing archive.
Archives in 7z format: The archive is entirely compressed whenever zipAddFile is called. This function is recommended when adding a single file. If several files must be added into the archive, use zipAddFileList or zipAddDirectory.

The maximum number of files that can be included:

in a WDZ file: 2³²-1.
in a ZIP file: 65535.
in a CAB file: 65535.

Reminder:

Only the archives in ZIP, TAR or TGZ (TAR.GZ) format are available.
Only the archives in ZIP format are available.

Compression level of ZIP or 7z archives

The files added into an archive in ZIP or 7z format are compressed by default. The compression level of files added into an archive can be modified by zipCompressionLevel.

Error codes

The following error codes are returned:

1: The path passed as parameter does not exist.
2: Access denied: the user has no sufficient rights or the file is currently used. If the file to insert is a HFSQL data file, it must be closed by the following code:

HClose(FileName)
Multitask() // Waits for the effective file closing
3: The archive is corrupted.
4: The path does not exist in the archive.
5: Unable to write into the archive.
7: The file is already found in the archive.
8: An archive cannot be added to itself. For example, "MyArchive" cannot be added to "MyArchive".

The message corresponding to the error code is returned by zipMsgError.

Adding a file that is already found in the archive

An error occurs when adding a file that is already found in the archive. A file is identified according to the path saved in the archive. Therefore, two files with the same name and with the same relative path cannot be added into an archive.

For example, the zipNone constant cannot be used to add two files with the same name found in different directories.

Subscript of files in the archive

When a file is added into an archive, a subscript is automatically assigned to the file. This subscript corresponds to the order in which the files are included in the archive. To select a file in the archive, you can use:

the element subscript (remark: the subscript of an element is returned by zipFindFile).
or the path of the element saved in the archive.

Path kept (archives in WDZ or ZIP format)

The array below shows the paths kept in the archive according to:

the access path to the file,
the path section to keep.

The current directory is: "C:\Temp":


zipAddFile	File location	zipNone	zipDirectory	zipDrive
zipAddFile ("Archi", "File.txt")	C:\Temp\File.txt	File.txt	File.txt	File.txt
zipAddFile ("Archi", "Data\File.txt")	C:\Temp\Data\File.txt	File.txt	Data\File.txt	Data\File.txt
zipAddFile ("Archi", "D:\Data\File.txt")	D:\Data\File.txt	File.txt	Data\File.txt	D:\Data\File.txt

Remark: If the constant zipDrive is used, the WDZ format keeps the full path of the file (including the drive letter) while the ZIP format does not keep the drive letter.

There is no current directory:


zipAddFile	File location	zipNone	zipDirectory
zipAddFile("Archi", "\File.txt")	\File.txt	File.txt	File.txt
zipAddFile("Archi", "\Temp\File.txt")	\Temp\File.txt	File.txt	Temp\File.txt

The disk is not kept in the archive path.

The directory and disk are not kept in the archive path. Only the file name and extension are kept.

Progress Bar

In Windows, to view the progress of file addition and compression, an event must be branched on CompressProgressBar (1174). When this message is received, the _EVE.wParam variable contains the percentage of file already compressed.

Caution: This event is not supported if the call to zipAddFile is performed in a secondary thread.

Versions 21 and later
From version 21, <Progress bar management> can also be used to manage the progress of file addition.

New in version 21
From version 21, <Progress bar management> can also be used to manage the progress of file addition.

From version 21, <Progress bar management> can also be used to manage the progress of file addition.

Special case: Archives in 7z format: The compression being global, the percentage of compression for a single file is not known (_EVE.wParam variable). Only the _EVE.lParam variable that contains the global progress is refreshed.

Business / UI classification : Business Logic

Component : wd250zip.dll