Copyright: Copyright ® 1995-1998, Stephen Darlington.


Contents
What's new?         Coming soon

The complete compression solution for Windows developers

v0.71

Read Me First

How do I ... ?

Function reference

ActiveX Custom Controls

Warnings and errors

License

Registration

Distribution

Contacting the author

Release History

Acknowledgements

Questionnaire

Copyright © 1995-1999 Stephen Darlington. All rights reserved.


How do I ... ?

This section presents the solutions to many commonly asked questions - if your question isn't answered here please contact the author.

How do I get the latest version?

How do I use the libraries with <insert your software here>?

How do I get started?

How do I create an archive?

How do I extract files from an archive?

How do I encrypt/decrypt files?

How do I get feedback from the addZIP Compression Libraries?

How do I view the contents of an archive?

How do I use comments in an archive?

How do I check the integrity of a .ZIP archive?

How do I use list files?

How do I repair .ZIP archives?

How do I create multi-disk archives?

How do I extract files from a multi-disk archive?

How do I use callbacks in Visual Basic v5?

How do I report a bug?


How do I get the latest version?

The latest version is always available direct from the author (see Contacting the author). Alternatively you can download the most recently released version from the following Web site(s)

http://welcome.to/addZIP


How do I use the libraries with <insert your software here>?

It is very likely that support files and/or examples exist for your chosen development software. These can be found on the addZIP web site. If there is no support for your software, please email me (sdarlington@bigfoot.com) and I'll try and help as much as I can.


How do I get started?

Please read the section relevant to your programming language. After registering you should also add the appropriate function calls to your start-up code.

Visual Basic

(You may want to look over the VB sample files - these will provide you with a good insight into the libraries).

1) Start a new project, and add the addzip.bas file to your project.

2) Put the following code in the Form_Load event

Dim I as Integer

addZIP_Initialise

addUNZIP_Initialise

I = addZIP_SetParentWindowHandle(Me.hWnd)

I = addUNZIP_SetParentWindowHandle(Me.hWnd)

You can test the return value of these function calls in case there is a problem with setting the Windows handle (this will probably never occur, but you never know).

C

(This example assumes you are using the 16-bit libraries. To use the 32-bit libraries substitute 32 for every 16)

1) Start a new project (or open an existing project) and add the azip16.lib and aunzip16.lib files to the project.

2) Add

#include "addzip.h"

#include "addunzip.h"

to your main .C/.CPP file.

3) Add the following to the function where the main window is created

HWND hWnd;

BOOL bReturn;

addZIP_Initialise();

addUNZIP_Initialise();

hWnd = CreateWindow(...);

bReturn = addZIP_SetParentWindowHandle(hWnd);

bReturn = addUNZIP_SetParentWindowHandle(hWnd);

You may wish to test the return value of these function calls in case there is a problem with setting the Windows handle (this will probably never occur, but you never know).

This code should work with all Windows C/C++ compilers include Borland's C++ Builder - if you have any trouble then email me for guidance.


How do I create an archive?

This can be as simple as calling addZIP_ArchiveName to set the name of the archive, and addZIP to start the compression process. This will take all files in the current directory, compress them at the default (normal) compression level, save full path information (the default) and add them to the archive.

As an example, the following will compress all .INI files and .GRP files on the C:\ drive with maximum compression to an archive name BACKUP.ZIP in the TEMP subdirectory.

I = addZIP_ArchiveName("c:\temp\backup.zip")

I = addZIP_Include("c:\*.ini|c:\*.grp")

I = addZIP_Recurse(TRUE)

I = addZIP_SetCompressionLevel(COMPRESSION_MAXIMUM)

I = addZIP()


How do I extract files from an archive?

Extracting files from an archive can be as simple as setting the name of the .ZIP archive and calling the addUNZIP function. This would extract all files from the archive into the current directory. If there are files in the current directory with the same names as those you are extracting, a dialog box will appear asking if you wish to overwrite the existing file(s).

As a further example, the following would extract only the .INI files from the archive backup.zip (see How do I create an archive?). The stored path information will be ignored (which is the default). The files will be extracted to the TEMP directory, overwriting all previous files without prompting.

I = addUNZIP_ArchiveName(c:\temp\backup.zip)

I = addUNZIP_Include(*.ini)

I = addUNZIP_RestoreStructure(FALSE)

I = addUNZIP_ExtractTo(c:\temp)

I = addUNZIP_Overwrite(OVERWRITE_ALL)

I = addUNZIP()


How do I encrypt/decrypt files?

First of all you must register. Without registering you will only be able to encrypt/decrypt files using the password Unregistered. When you registered, you will have been provided with a registration number. Use this, with the registered user name, in function calls to addZIP_Register and/or addUNZIP_Register. Calling addZIP_Encrypt with a password before adding files to an archive will then encrypt all further files added. Use addUNZIP_Decrypt with the appropriate password to extract encypted files from an archive.

N.B. Remember that after calls to addZIP() and addUNZIP(), all defaults will be reset.


How do I get feedback from the addZIP Compression Libraries?

The addZIP libraries communicates with the calling (parent) program by means of notification messages. These messages are sent at important points during the processing of a addZIP() or addUNZIP() function. It is up to you to process these messages or ignore them.

The ideal way for the addZIP libraries to pass this information to the calling program is via a callback function (see addZIP_InstallCallback or addUNZIP_InstallCallback). This function then gets called as part of the normal running of the libraries as if it were a native part of the code i.e. the execution of the addZIP code stops when the callback function is called and only restarts when the function is exited. However some development environments (most notably Visual Basic pre version 5) do not support callbacks; the addZIP_SetWindowHandle and addUNZIP_SetWindowHandle functions are available to overcome this limitation. N.B. Without using a callback function, some of the event messages are not available.

The information for a particular notification message is passed as a pipe (|) delimited string of parameters relevant to the message. If you are not using a callback function, the first three parameters are the calling library (azLIBRARY_ADDZIP or azLIBRARY_ADDUNZIP), the message id (see descriptions below) and the current archive name. If you are using a callback function, the first parameter in the list is the current archive name.

AM_SEARCHING     0x0a

This message is generated at the start of a compression process when the addZIP library is using the wildcard patterns specified (or the default *.*) to create a list of files to compress. This message will be generated multiple times.The extra parameters provided with this message are |wildcard_pattern|directory_being_searched|.

AM_ZIPCOMMENT     0x0b

This message is only generated once during the processing of an existing ZIP archive if a comment exists for the archive. The extra parameters are |comment_length|comment|. (The comment_length is limited to 1024 characters here)

AM_ZIPPING        0x0c

This message is generated multiple times during the compression of a file. The extra parameters are |filename|original_size|current_bytes_read|percentage_read|total_number_of_files_to_process|files_processed_so_far|total_bytes_to_compress|total_bytes_compressed_so_far

AM_ZIPPED         0x0d

This message is generated once after a file has been compressed. The extra parameters are |filename|original_size|compressed_size|compression_ratio|total_number_of_files_to_process|files_processed_so_far|total_bytes_to_compress|total_bytes_compressed_so_far

AM_UNZIPPING      0x0e

This message is generated multiple times during the de-compression of a file. The extra parameters are |filename|original_size|bytes_decompressed|percentage_decompressed|total_number_of_files_to_process|files_processed_so_far|total_bytes_to_decompress|bytes_decompressed_so_far

AM_UNZIPPED       0x0f

This message is generated once after a file has been de-compressed. The extra parameters are |filename|original_size|decompressed_size|percentage|total_number_of_files_to_process|files_processed_so_far|total_bytes_to_decompress|bytes_decompressed_so_far

AM_TESTING        0x10

Like the AM_UNZIPPING message, this message is generated multiple times during a test decompression of the file. Unlike AM_UNZIPPING no file is actual extracted. The extra parameters are |filename|original_size|bytes_decompressed|percentage_decompressed|total_number_of_files_to_process|files_processed_so_far|total_bytes_to_decompress|bytes_decompressed_so_far

AM_TESTED         0x11

Like the AM_UNZIPPED message, this message is generated once after the test decompression of the file. Unlike AM_UNZIPPED no file is actual extracted. The extra parameters are |filename|original_size|decompressed_size|percentage_decompressed|total_number_of_files_to_process|files_processed_so_far|total_bytes_to_decompress|bytes_decompressed_so_far

AM_DELETING       0x12

This message is generated once at the start of the deletion of a file from the archive. The extra parameter is |filename|.

AM_DELETED        0x13

This message is generated once at the end of the deletion of a file from the archive. The extra parameter is |filename|.

AM_DISKCHANGE     0x14

The message is generated during the processing of multi-disk archives and only if you are using a callback function. You need to prompt the user to remove (if addZIP) or insert (if addUNZIP) the disk before exiting the callback function. The extra parameter is |current_disk_number| (for addZIP) or |required_disk_number| (for addUNZIP). (If the required disk number is 0, it means that the last disk is requested).

AM_VIEW           0x15

Please see the topic How do I view the contents of an archive? for information on the AM_VIEW message.

AM_ERROR          0x16

Should a serious error occur during processing, this message will be generated prior to the process being aborted. The extra parameters are |filename|error_code|.

AM_WARNING        0x17

Should a non-serious error occur during processing, this message will be generated prior to the process continuing. The extra parameters are |filename|warning_code|.

AM_QUERYOVERWRITE 0x18

This message is generated only if using a callback function, and a file with the same name exists in the archive (for addZIP), or on the destination drive (for addUNZIP). You should prompt the user to select an option and then the function should return the required azOW_ constant. The extra parameters are |current_filename|current_size|current_datetime|new_filename|new_size|new_datetime|

AM_COPYING        0x19

This message is generated when copying the archive from its temporary location to its proper location. No extra parameters are passed.

AM_COPIED         0x1a

This message is generated after the archive has been copied from its temporary location to its proper location. No extra parameters are passed.

AM_ABORT          0xff

Only used in the callback function, if the function returns this message the library will abort its current processing. No extra parameters.


How do I view the contents of an archive?

N.B. With archives that span multiple disks, only the addUNZIP_View function should be used.

By including a call to addUNZIP_View() in your code, a notification message will be generated for all the files in the .ZIP archive that match the given file specification (or all the files if none given). See previous How do I ... ? for information on receiving notification messages within your program.

As with other notification messages, the extra information is passed as a list of | (pipe) delimited parameters as detailed below.

|path	the stored directory structure (if included), or empty

|filename	the compressed file name

|original_size	the file's original (uncompressed) size

|compressed_size	the compressed size

|ratio	the percentage compression achieved

|date	the last accessed date (in YYYY-MM-DD sortable format)

|time 	the last accessed time (in HH:MM:SS format)

|attributes	the stored file attributes (operating system dependant)

|method	the compression method used

|encrypted flag	boolean value indicating whether the file is encrypted (1) or not (0)

|CRC	the Cyclical Redundancy Check 32-bit value

|filetype flag	boolean value indicating whether the file is binary (1) or text (0)

|created	floating point value indicating version of PKZIP used to compress file

|needed	floating point value indciating version of PKUNZIP needed to extract file


How do I use comments in an archive?

From version 0.5 of the libraries it is possible to add, retrieve, display and delete a comment stored in a .ZIP archive.

Please see the relevant function reference for more information on the comment functions, and also refer to How do I get feedback from the addZIP Compression Libraries?

N.B. When the comment is passed back to the calling program as part of the processing of an archive it is terminated with a NULL character (ASCII value = 0). Most languages recognise this as the terminator for a line, however other languages, for example Visual Basic, do not. If your language does not recognise NULL as the end of a line, use InStr (or its equivalent) to locate the instance of the NULL character, and then truncate the line at the previous character.


How do I check the integrity of a .ZIP archive?

Briefly you need to make calls to the following functions addUNZIP_ArchiveName, addUNZIP_Test and addUNZIP. You should then check the feedback edit box (see previous How do I ... ?) - any problems will be reported as errors and warnings. See the next How do I ... ? to see how to repair any damaged .ZIP archives.


How do I use list files?

Whilst it is possible to pass all required wildcard specifications to the addZIP_Include and addZIP_Exclude functions (and the addUNZIP equivalent), it may be more prudent to create a list file containing the required wildcards and pass this as a parameter to the relevant listfile function.

The format of an addZIP listfile follows the conventions used by PKZIP. That is, individual wildcards are on seperate lines, and comments are preceeded by semi-colons. For example, a listfile may contain the following

; This listfile is used for backing up all configuration files

c:\*.ini  ; back-up ini files

c:\windows\*.grp

c:\autoexec.bat

....

....

Then instead of specifying an addZIP_Include function (or addUNZIP_Include), you can use code similar to the following

UINT16 i;

UINT32 j;

i = addZIP_ArchiveName("a:\backup.zip");

i = addZIP_IncludeListFile("mylist.lst");

j = addZIP();


How do I repair .ZIP archives?

The short answer to this, at the moment, is that you can't. Well not with the addZIP Compression Libraries. PKWARE provides an excellent zip repair utility with its PKZIP package.


How do I create multi-disk archives?

As of version 0.5 of the libraries it is possible to create .ZIP archives that span multiple diskettes ( or other removable media). These multi-disk archives are compatible with PKUNZIP.

To create a multi-disk archive, include a call to addZIP_Span in your code that sets up the library, and ensure that the .ZIP archive will be created on a diskette and that no previous .ZIP archive of the same name exists at that location (otherwise it will be overwritten). Although the file(s) will be compressed to the specified removable media, some temporary disk space is needed to hold a file whilst it is being compressed. This temporary disk space need not be any more than the largest file to be compressed.

When the disk is full, a notification message will be sent (if using a callback function) or a prompt will be displayed (if not using a callback function) to request the removal and labelling of the current diskette, and the insertion of a new diskette. This disk will then be used until all files are compressed or it too is full - again a prompt will be displayed. This will be repeated until all files are compressed.


How do I extract files from a multi-disk archive?

The addUNZIP libraries have now been made 'multi-disk archive' aware. This means that if you want to extract files from a multi-disk archive, addUNZIP will prompt for the correct disks.

Because a .ZIP archive stores its central information at the end of the archive, it is necessary to insert the last disk of the multi-disk set first. addUNZIP will then read all the relevant information before prompting for the correct disks. If you insert the first disk first, addUNZIP is smart enough to prompt for the last disk. If you insert any other disk in the set first, addUNZIP has no way of knowing whether the archive is part of a multi-disk set or, possibly, a corrupt archive.


How do I use callbacks in Visual Basic v5?

Callback function and function pointers used to be only available to C and Pascal programmers. However, in Visual Basic version 5, Microsoft introduced a new keyword AddressOf that allows the developer to include much of the functionality that had previously been lacking. A downside to the new keyword is that it is very easy to crash your application, the VB5 IDE and even the Windows OS when using function pointers - so be very careful , and save your work often.

The first thing to note about AddressOf is that it can only be used to create function pointers for functions that reside in code modules not in form modules. With this in mind, we create a function similar to the following in a code module.

Function my_callback(ByVal iLibName As Integer, ByVal iMessage As Integer, c As Long) As Integer

    Dim cExtra As String

    Dim lpString As Long

    Dim aNull As Long

    cExtra = Space(2049)

    lpString = lstrcpyA(cExtra, c)

    aNull = InStr(cExtra, Chr$(0))

    If (aNull > 0) Then cExtra = Left$(cExtra, aNull - 1)

    ' your code would go here

    my_callback = 0

End Function

Whats happening here? First note the function's third parameter is declared without the ByVal keyword. This effectively passes the third parameter by reference i.e. in this case referencing a memory location. The information stored at this location can be retrieved into a VB string using the lstrcpyA function. This should be declared as below.

Declare Function lstrcpyA Lib "Kernel32" (ByVal lpString1 As Any, ByRef lpString2 As Any) As  Long

First we dynamically allocate a string buffer of length 2049 (which is one more than the maximum string that could be at the memory location), then we use lstrcpyA to copy the information from the location pointed to by c into our buffer. As this information is NULL terminated we search our buffer for the NULL character and remove all characters from the NULL character to the end of the string.

Note the my_callback = 0 line: this is the return value passed back to the libraries. For most notification messages this is not used, however we could pass AM_ABORT back; this would immediately cause the libraries to abort all further processing (see How do I get feedback from the libraries? for more information on notification messages)

All that remains after setting up our callback function is to install it using a call to addZIP_InstallCallback or addUNZIP_InstallCallback e.g.

    I = addZIP_InstallCallback(AddressOf my_callback)


How do I report a bug?

There may be parts of the libraries that still exhibit undefined or inconsistent behaviour, and if you do come across such behaviour I would be most grateful if you could submit a bug report.

The information that is needed when reporting the existence of a bug

•	Development environment (e.g. Visual Basic 5 or Access 97)

•	Platform (e.g. Windows 98 or Windows NT 4)

•	Current library version and date

•	Description of the problem

•	Sample code (if possible)

•	Sample (small) zip (if possible)

Email the above information to sdarlington@bigfoot.com. I will normally respond within 24 hours. If the problem you report is hampering your use of the libraries, I will normally mail you an up-to-date build of the libraries which will be later than the one available on the addZIP homepage.


Function reference

•	addZIP Compression Libraries azip16.dll and azip32.dll

•	addUNZIP Compression Libraries aunzip16.dll and aunzip32.dll


addZIP Function Reference

addZIP

addZIP_Abort

addZIP_ArchiveName

addZIP_BuildSFX

addZIP_ClearAttributes

addZIP_Comment

addZIP_Delete

addZIP_DeleteComment

addZIP_DisplayComment

addZIP_Encrypt

addZIP_Exclude

addZIP_ExcludeListFile

addZIP_Freshen

addZIP_FromMemory (new)

addZIP_GetLastError

addZIP_GetLastWarning

addZIP_GetVersion

addZIP_Include

addZIP_IncludeDirectoryEntries

addZIP_IncludeEmptyDirectoryEntries

addZIP_IncludeFilesNewer

addZIP_IncludeFilesOlder

addZIP_IncludeArchive

addZIP_IncludeHidden

addZIP_IncludeReadOnly

addZIP_IncludeSystem

addZIP_IncludeListFile

addZIP_Initialise

addZIP_InMemory(new)

addZIP_InstallCallback

addZIP_InstallCallbackEx

addZIP_Move

addZIP_Overwrite

addZIP_Recurse

addZIP_Register

addZIP_SaveAttributes

addZIP_SaveRelativeTo *

addZIP_SaveStructure

addZIP_SetArchiveDate

addZIP_SetCompressionLevel

addZIP_SetParentWindowHandle

addZIP_SetTempDrive

addZIP_SetWindowHandle

addZIP_SFXAutoExecute

addZIP_SFXAutoPasswordPrompt

addZIP_Span

addZIP_SpanCreateImages

addZIP_SpanSizes

addZIP_Store

addZIP_ToMemory (new)

addZIP_Update

addZIP_UseLFN

addZIP_View


addZIP

The addZIP() function actually begins the compression process. This should be called after setting all required options.

Syntax

INT32 addZIP()

Parameters

None.

Returns

This function returns the number of files processed. If -1 is returned, there is no .ZIP archive name specified. 0 indicates no files have been processed.

Remarks

This function should not be called without first initialising the libraries (see addZIP_Initialise) and specifying the name of the .ZIP archive (see addZIP_ArchiveName)

Example(s)


addZIP_Abort

The addZIP_Abort function allows you to abort the compression process started by a call to addZIP().

Syntax

INT16 addZIP_Abort(INT16 bFlag)

Parameters

bFlag	pass a TRUE value if you wish to abort the current compression process

Return

The return value from this function is 0 if the process will be aborted, non-zero otherwise.

Notes

•	this function should only be used when no callback function has been defined

•	the addZIP() function may not return immediatly after calling this function


addZIP_ArchiveName

This function specifies the name of the .ZIP archive to work with.

Syntax

int addZIP_ArchiveName(LPSTR lpsz)

Parameters

lpsz	the name of the .ZIP archive

Returns

The return value is non-zero if no error occurs. If it is zero, an error has occurred (probably out of memory).

Remarks

This function is always required.

Example(s)


addZIP_BuildSFX

The addZIP_BuildSFX function allows the creation of a self-extracting archive. That is, the archive will be able to extract itself without the need for any other program.

Syntax

INT16 addZIP_BuildSFX(INT16 bFlag)

Parameters

bFlag	pass a TRUE value if you wish to build an SFX archive

Returns

This function returns a non-zero value if an SFX archive will be built; 0 indicates a normal ZIP archive will be built.

Notes

•	You must include asfx16.dll or asfx32.dll with your application if you use this function

•	The asfx16.dll or asfx32.dll must be either in the current directory or the SYSTEM directory of Windows

•	Creating a self-extracting archive adds no more than 30K bytes to an archive's size

•	The SFX functionality is still under development. As of version 0.69, the SFX is only available as a 16-bit DOS version, and will only extract all files. Although there are now a couple of customisation functions, these should be treated with caution. Support for command line parameters will be added in a future version.

•	Please contact me with further customisation suggestions

Example(s)


addZIP_ClearAttributes

Allows the specified file attributes to be cleared after the file is compressed. The default is to clear no attributes (equivalent to addZIP_ClearAttributes(azATTR_NONE)).

Syntax

int addZIP_ClearAttributes(int iAttributes)

Parameter

iAttributes	specifies the attributes to be cleared. This can be any combination of  azATTR_READONLY, azATTR_HIDDEN, azATTR_SYSTEM and azATTR_ARCHIVE. For convenience there also flags to specify no attributes are cleared (azATTR_NONE) and to clear all attributes (azATTR_ALL).

Returns

The return value represents the attributes that will be cleared during the processing of addZIP (i.e. it should return the same value that was passed as a parameter).

Remarks

Example(s)


addZIP_Comment

This function allows the user to add a comment to the .ZIP archive.

Syntax

int addZIP_Comment(LPSTR lpsz)

Parameters

lpsz	the comment to add to the archive

Returns

This function returns a non-zero value if no error occurs.

Remarks

The most common cause for an error is a NULL (or zero-length) string being passed in error.

Example(s)


addZIP_Delete

This function will allow the deletion of the specified files from the archive

Syntax

int addZIP_Delete(BOOL bFlag)

Parameters

bFlag	set this value to true if you want to delete files from an archive

Returns

This function returns a non-zero value on success.

Remarks

Example(s)

The following example will delete all files matching *.INI and WINDOWS\*.GRP from the archive BACKUP.ZIP.

addZIP_ArchiveName("BACKUP.ZIP")

addZIP_Include("*.INI|WINDOWS\*.GRP")

addZIP_Delete(TRUE)

addZIP()


addZIP_DeleteComment

This function allows the user to remove the comment (if one exists) from the .ZIP archive.

Syntax

INT16 addZIP_DeleteComment(BOOL bFlag)

Parameters

bFlag	set this value to TRUE to remove the ZIP comment from the archive

Returns

This function returns a non-zero value if the next call to addZIP will delete any existing comment. A value 0 means that the comment will be left untouched.

Remarks

Example(s)


addZIP_DisplayComment

Allows the addZIP library to display the archive comment (if one exists) prior to further processing. The default is not to display the comment.

Syntax

INT16 addZIP_DisplayComment(int iFlag)

Parameter

iFlag	a boolean value (O for FALSE, 1 or -1 for TRUE) indicating whether to display the comment

Returns

This function returns a non-zero value indicating the comment will be displayed, 0 if no comment will be displayed.

Remarks

Example(s)


addZIP_Encrypt

This function will encrypt compressed files with the provided password. The default is not to encrypt files.

Syntax

INT16 addZIP_Encrypt(LPSTR lpsz)

Parameters

lpsz	a password with which to encrypt the files next added to the archive.

Returns

This function returns non-zero if successful. A return value of zero indicates lack of sufficient memory.

Remarks

Example(s)


addZIP_Exclude

These functions allows for the exclusion of specified files. Any files matching those specified will be excluded from any processing.

Syntax

INT16 addZIP_Exclude(LPCSTR lpsz)

Parameters

lpsz	the pipe-delimited (|) list of files to exclude.

Returns

These functions return a non-zero value on success. A return value of zero indicates that lpsz is NULL or there is not enough memory.

Remarks

As in all file functions that accept file specifications (except addZIP_ArchiveName), wildcard characters can be specified. For large numbers of file specifications, you may want to consider using a list file (see How do I use list files?).

Example(s)


addZIP_ExcludeListFile

These functions allow the developer to specify the name of an existing file that contains a list of file specifications to exclude.

Syntax

INT16 addZIP_ExcludeListFile(LPCSTR lpsz)

Parameters

lpsz	the name of the existing file

Returns

These functions return a non-zero value on success. A return value of zero indicates that lpsz doesn't exist, wasn't found or is spelt incorrectly.

Remarks

Please see How do I use list files? for a discussion on list files and there uses.

Example(s)


addZIP_Freshen

Allows an existing .ZIP archive to be freshened - that is, only files that currently exist in the archive will be compressed and only if they are newer that those files already in the archive.

Syntax

INT16 addZIP_Freshen(INT16 iFlag)

Parameter

iFlag	set to TRUE if you want to freshen the archive.

Returns

The return value will be non-zero if the archive will be freshened on the next call to addZIP(). A value of zero indicates that addZIP() will process all files.

Remarks

The .ZIP archive (specified with addZIP_ArchiveName) must exist for this function to be valid.

Example(s)


addZIP_FromMemory

Allows data to be compressed directly from memory rather than a file.

Syntax

INT16 addZIP_FromMemory(LPSTR_T pszBuffer, UINT32_T ulBufferLen)

Parameter

pszBuffer	points to the buffer to compress

ulBufferLen	the number of bytes to compress

Returns

The return value will be non-zero if the function call was successful. If zero, pszBuffer is of zero length and/or ulBufferLen is 0.

Remarks

If this function is used to add information to a .ZIP archive, the filename will be stored as '-' (without the quotes). This function may be combined with addZIP_ToMemory to perform complete in-memory compression.

Example(s)


addZIP_GetLastError

This function can be used to retrieve the last error code generated by the last call to addZIP().

Syntax

INT16 addZIP_GetLastError(void)

Parameters

None

Returns

This function will return a non-zero value if an error occurred during the last call to addZIP(). A value of 0 indicates that no error occurred.

Remarks

This function is useful for developers where the language can call functions in DLLs but cannot provide an interface for retrieving feedback information from the DLL.

Example(s)


addZIP_GetLastWarning

This function can be used to retrieve the last warning code generated by the last call to addZIP().

Syntax

INT16 addZIP_GetLastWarning(void)

Parameters

None

Returns

This function will return a non-zero value if a warning occurred during the last call to addZIP(). A value of 0 indicates that no warning occurred.

Remarks

This function is useful for developers where the language can call functions in DLLs but cannot provide an interface for retrieving feedback information from the DLL.

Example(s)


addZIP_GetVersion

The addZIP_GetVersion function retrieves the current version number of the addZIP Compression Library.

Syntax

void addZIP_GetVersion(UINT16 *iMajor, UINT16 *iMinor)

Parameters

iMajor	points to an unsigned 16-bit integer that will receive the major version number

iMinor	points to an unsigned 16-bit integer that will receive the minor revision number

Returns

This function has no return value.

Remarks

Example(s)


addZIP_Include

These functions allows the developer to specify exactly which files to include during processing. The default is to include all (*.*) files excluding hidden and system files.

Syntax

INT16 addZIP_Include(LPCSTR lpsz)

Parameters

lpsz	a delimited list file specifications (e.g. *.ini|*.grp)

Returns

These functions return a non-zero value on success. A return value of zero indicates that lpsz is NULL or there is not enough memory.

Remarks

As in all file functions that accept file specifications (except addZIP_ArchiveName), wildcard characters can be specified. For large numbers of file specifications, you may want to consider using a list file (see How do I use list files?).

Example(s)


addZIP_IncludeArchive

Allows the inclusion of files based on the existence of the archive attribute The default is to include files irrespective of the archive attribute.

Syntax

INT16 addZIP_IncludeArchive(INT16 iFlag)

Parameter

iFlag	has to be one of the following: azNEVER - a file must not have the archive attribute set to be included; azALWAYS - a file must have the archive attribute set to be included; azYES - a file will be included regardless of the archive attribute.

Returns

This function returns the same value that was passed as a parameter, if correct. If the function was called with an illegal value, this function returns the original value.

Example(s)


addZIP_IncludeDirectoryEntries

Allows the inclusion of directories as seperate entries in a .ZIP archive. The default is not to store directories as seperate entries.

Syntax

INT16 addZIP_IncludeDirectoryEntries(INT16 iFlag)

Parameter

iFlag	a boolean value (O for FALSE, 1 or -1 for TRUE) indicating whether to store directories as seperate entries.

Returns

This function returns a non-zero value indicating that directories will be stored as seperate entries, 0 to store directories as part of a normal .ZIP entry.

Remarks

Example(s)


addZIP_IncludeEmptyDirectoryEntries

Allows the inclusion of directories which do not include any files (i.e. they are empty) as seperate entries in a .ZIP archive. The default is not to store empty directories.

Syntax

INT16 addZIP_IncludeEmptyDirectoryEntries(INT16 iFlag)

Parameter

iFlag	a boolean value (O for FALSE, 1 or -1 for TRUE) indicating whether to store empty directories

Returns

This function returns a non-zero value indicating that empty directories will be stored as seperate entries, 0 to exclude all empty directories.

Notes

Example(s)


addZIP_IncludeFilesNewer

Allows the filtering of files based on last accessed date. Files are included if they were last accessed on or after the specified date. The default is to take all files regardless of the last accessed date.

Syntax

INT16 addZIP_IncludeFilesNewer(LPCSTR szDate)

Parameter

szDate	specifies the date as a string in the format YYYY-MM-DD

Returns

This function returns a non-zero value if the user has passed a valid date, other wise a zero is returned.

Remarks

Example(s)


addZIP_IncludeFilesOlder

Allows the filtering of files based on last accessed date. Files are included if they were last accessed before the specified date. The default is to take all files regardless of the last accessed date.

Syntax

INT16 addZIP_IncludeFilesOlder(LPCSTR szDate)

Parameter

szDate	specifies the date as a string in the format YYYY-MM-DD

Returns

This function returns a non-zero value if the user has passed a valid date, other wise a zero is returned.

Remarks

Example(s)


addZIP_IncludeHidden

Allows the inclusion of files based on the existence of the hidden attribute The default is to exclude a file if it has the hidden attribute set.

Syntax

INT16 addZIP_IncludeHidden(INT16 iFlag)

Parameter

iFlag	has to be one of the following: azNEVER - a file must not have the hidden attribute set to be included; azALWAYS - a file must have the hidden attribute set to be included; azYES - a file will be included regardless of the hidden attribute.

Returns

This function returns the same value that was passed as a parameter, if correct. If the function was called with an illegal value, this function returns the original value.

Example(s)


addZIP_IncludeListFile

These functions allow the developer to specify the name of an existing file that contains a list of file specifications to include.

Syntax

INT16 addZIP_IncludeListFile(LPCSTR lpsz)

Parameters

lpsz	the name of the existing file

Returns

These functions return a non-zero value on success. A return value of zero indicates lpsz doesnt exist, wasnt found or is spelt incorrectly.

Remarks

Please see How do I use list files? for a discussion on list files and there uses.

Example(s)


addZIP_IncludeReadOnly

Allows the inclusion of files based on the existence of the read-only attribute The default is to include a file regardless of the read-only attribute.

Syntax

INT16 addZIP_IncludeReadOnly(INT16 iFlag)

Parameter

iFlag	has to be one of the following: azNEVER - a file must not have the read-only attribute set to be included; azALWAYS - a file must have the read-only attribute set to be included; azYES - a file will be included regardless of the read-only attribute.

Returns

This function returns the same value that was passed as a parameter, if correct. If the function was called with an illegal value, this function returns the original value.

Example(s)


addZIP_IncludeSystem

Allows the inclusion of files based on the existence of the system attribute The default is to exclude a file if it has the system attribute set.

Syntax

INT16 addZIP_IncludeSystem(INT16 iFlag)

Parameter

iFlag	has to be one of the following: azNEVER - a file must not have the system attribute set to be included; azALWAYS - a file must have the system attribute set to be included; azYES - a file will be included regardless of the system attribute.

Returns

This function returns the same value that was passed as a parameter, if correct. If the function was called with an illegal value, this function returns the original value.

Example(s)


addZIP_Initialise

This function initialises the addZIP Compression Library and must be the first function called.

Syntax

void addZIP_Initialise(void)

Parameters

None

Returns

This function does not return a value.

Remarks

If this function is omitted, the performance of the library may be erratic.

Example(s)


addZIP_InMemory

Allows data to be compressed in memory.

Syntax

INT16 addZIP_FromMemory(LPSTR_T pszInBuffer, UINT32_T ulInLen, LPSTR_T pszOutBuffer, UINT32_T ulOutLen)

Parameter

pszInBuffer	points to the buffer to compress

ulInLen	the size of pszInBuffer

pszOutBuffer	points to the buffer to hold the compressed data

ulOutLen	the size of pszOutBuffer

Returns

The return value will be the compressed size of pszInBuffer (including header information). If zero is returned, an error has occurred. This error can be retrieved using addZIP_GetLastError().

Notes

•	Unlike the other functions in the addZIP library, this function executes immediately.

•	pszOutBuffer should be of sufficient size to hold pszInBuffer plus 20 bytes.

Example(s)


addZIP_InstallCallback

Allows the developer to specify an application-defined function that will be called regularly during the processing of addZIP(). The callback function can then process the passed message information as necessary.

Syntax

INT16 addZIP_InstallCallback(CALLBACKFN cbFunction)

Parameter

cbFunction	specifies the name of the callback function

Returns

This function returns a non-zero number on success, 0 on failure.

Remarks

Please refer to the How do I get feedback from the libraries? for further information on using callback functions and message reference.

Example(s)

#include "addzip.h"

INT16 CALLBACK mycallback(INT16 iLibrary, INT16 iMessage, char *szInfo) {

switch (iMessage) {

case default:

// default handling here

case AM_SEARCHING:

...

case AM_ZIPPING:

// update user interface here

...

}

return 1;

}

int main() {

if (addZIP_InstallCallback((CALLBACKFN)mycallback) == 0) {

// error processing

}

if (addZIP_ArchiveName("full.zip") == 0) {

// error processing

}

if (addZIP_Include("c:\\*.*") == 0) {

// error processing

addZIP_SaveStructure(azSTRUCTURE_ABSOLUTE);

addZIP();

}


addZIP_InstallCallbackEx

Allows the developer to specify an application-defined function that will be called regularly during the processing of addZIP(). The callback function can then process the passed message information as necessary. Unlike addZIP_InstallCallback, the developer may pass a known value into the callback function.

Syntax

INT16 addZIP_InstallCallbackEx(CALLBACKFN cbFunction, UINT32 lParam)

Parameter

cbFunction	specifies a pointer to the application-defined callback function

lParam	specifies a 32-bit, application-defined value to be passed to the callback function

Returns

This function returns a non-zero number on success, 0 on failure.

Remarks

Please refer to the How do I get feedback from the libraries? for further information on using callback functions and message reference.

Example(s)

#include "addzip.h"

INT16 CALLBACK mycallback(INT16 iLibrary, INT16 iMessage, char *szInfo, UINT32 lParam) {

switch (iMessage) {

case default:

// default handling here

case AM_SEARCHING:

...

case AM_ZIPPING:

// update user interface here

...

}

return 1;

}

int main() {

UINT32 my_value = 10;

if (addZIP_InstallCallback((CALLBACKFN)mycallback, my_value) == 0) {

// error processing

}

if (addZIP_ArchiveName("full.zip") == 0) {

// error processing

}

if (addZIP_Include("c:\\*.*") == 0) {

// error processing

addZIP_SaveStructure(azSTRUCTURE_ABSOLUTE);

addZIP();

}


addZIP_Move

The addZIP_Move function allows the user to specify the deletion of files after compression - in effect moving them into the archive.

Syntax

INT16 addZIP_Move(INT16 iFlag)

Parameters

iFlag	set this value to TRUE to move files into the archive

Returns

This function returns a non-zero value if set to move files, 0 if files will not be deleted

Notes

•	Files are only moved after all files have been compressed.

•	Read-only files will not be deleted.

Example(s)


addZIP_Overwrite

This function allows the developer to change how addZIP deals with files that already exist within the .ZIP archive. The default is to prompt the user to choose between overwriting the existing file or skipping the file.

Syntax

INT16 addZIP_Overwrite(INT16 fExist)

Parameters

fExist	one of azOVERWRITE_QUERY, azOVERWRITE_ALL or azOVERWRITE_NONE. The constants are self-explanatory. The default is azOVERWRITE_QUERY.

Returns

These functions returns a non-zero value on success. A return value of zero indicates an incorrect constant was given.

Remarks

If a file exists in the archive with the same name as the one being added, the default action is to display a dialog box allowing the user to choose which file to keep. If the user selects YES (or YES TO ALL) the existing file will be overwritten with the new file; if NO (or NO TO ALL) is selected the existing file is kept. Files are compared using full path information if it exists, so ctl3d.dll, system\ctl3d.dll and windows\system\ctl3d.dll are all unique files.

Example(s)


addZIP_Recurse

The addZIP_Recurse function allows the developer to specify whether any directories found should be recursed into. The default is to

not recurse into any directories i.e. take only files from the specified (or current directory) only.

Syntax

INT16 addZIP_Recurse(INT16 fAccept)

Parameters

fAccept	Set this value to TRUE to specify recursion. The default is FALSE.

Returns

This functions returns a non-zero value if recursion will be used in the next call to addZIP. A return value of zero indicates that recursion is off.

Remarks

Whilst very powerful, recursion has to be used carefully. Bear in mind that when recursion is on, addZIP will check every directory under the starting directory, all the directories under those found and so on. This can lead to a large number of files being selected and added to the archive. Also always save the directory structure when using recursion, failure to do so will result in files of the same name being excluded.

Example(s)


addZIP_Register

This function registers the addZIP Compression Libraries, allowing the use of your own passwords in the addZIP_Encrypt and addUNZIP_Decrypt functions.

Syntax

INT16 addZIP_Register(LPCSTR lpszName, UINT32 lPassword)

Parameters

lpszName	the registered user name

lPassword	the provided registration number

Returns

This function returns a non-zero value if it is a valid registered user name and a valid registration number. A return value of zero indicates that registration has failed. If this is the case, please make sure you entered the function parameters as provided.

Remarks

Examples


addZIP_SaveAttributes

Allows the specified file attributes to be saved along with the compressed file.The default is to save the archive and read-only attributes.

Syntax

INT16 addZIP_SaveAttributes(INT16 iAttributes)

Parameter

iAttributes	specifies the attributes to be saved. This can be any combination of  azATTR_READONLY, azATTR_HIDDEN, azATTR_SYSTEM and azATTR_ARCHIVE. For convenience there also flags to specify no attributes are saved (azATTR_NONE) and to save all attributes (azATTR_ALL).

Returns

The return value represents the attributes that will be saved during the processing of addZIP (i.e. it should return the same value that was passed as a parameter).

Remarks

Example(s)


addZIP_SaveRelativeTo

The addZIP_SaveRelativeTo allows the specification of a directory that file paths should be saved relative to when using azSTRUCTURE_RELATIVE with addZIP_SaveStructure.

Syntax

INT16 addZIP_SaveRelativeTo(LPCSTR lpszPath)

Parameters

lpszPath	points to a NULL terminated string to be used as the base path when saving relative paths

Returns

This function returns a non-zero value if successful, zero if an error occurs.

Remarks

This function only has an effect if relative paths are being stored.

Example(s)

If you wanted to save all the DLLs in the WINDOWS\SYSTEM directory and store paths relative to the WINDOWS directory, you would use the following sequence of function calls

addZIP_Include("c:\windows\system\*.dll")

addZIP_SaveStructure(azSTRUCTURE_RELATIVE)

addZIP_SaveRelativeTo("c:\windows")

Without the addZIP_SaveRelativeTo function all paths would be saved relative to c:\windows\system i.e. no paths would be saved.


addZIP_SaveStructure

The addZIP_SaveStructure function registers how the files are stored in a .ZIP archive. Files may be stored with full path information (the default), with relative path information (relative to the starting directory) and with no path information.

Syntax

INT16 addZIP_SaveStructure(INT16 fHow)

Parameters

fHow 	either azSTRUCTURE_ABSOLUTE, azSTRUCTURE_RELATIVE or azSTRUCTURE_NONE

Returns

This function return the constant representing the structure option to be used. In most cases this should be the same as what the function was called with.

Remarks

Example(s)


addZIP_SetArchiveDate

Allows the last accessed date of the .ZIP archive to be specified.The default is to set the last accessed date to the current system date.

Syntax

INT16 addZIP_SetArchiveDate(INT16 iDate)

Parameter

iDate	specifies the date to be used. This must be one of DATE_TODAY (the current system date), DATE_ORIGINAL (the original last accessed date), DATE_OLDEST (the date of the oldest file in the archive) or DATE_NEWEST (the date of the newest file in the archive.

Returns

The return value represents the date value that will be used (i.e. it should return the same value that was passed as a parameter).

Remarks

Example(s)


addZIP_SetCompressionLevel

The addZIP_SetCompressionLevel function can be used to vary the speed and compression of the addZIP Compression Libraries. The speed and amount of compression are inversely linked, so specifying azCOMPRESSION_NONE is the quickest but there is no compression, whilst azCOMPRESSION_MAXIMUM is the slowest but will achieve the maximum possible level of compression. The default value is azCOMPRESSION_NORMAL which gives medium speed with medium compression.

Syntax

INT16 addZIP_SetCompressionLevel(INT16 fLevel)

Parameters

fLevel	the required compression level (azCOMPRESSION_NONE, azCOMPRESSION_MINIMUM, azCOMPRESSION_NORMAL or azCOMPRESSION_MAXIMUM).

Returns

This function returns a value representing the compression level in use.

Notes

•	This function is equivalent to PKZIP's -e

Example(s)

To change the compression to maximum and catch any errors, use code similar to the following

if (addZIP_SetCompressionLevel(azCOMPRESSION_MAXIMUM) <> azCOMPRESSION_MAXIMUM) then

...(put error code here)...

end


addZIP_SetParentWindowHandle

This function is required so that any dialog boxes displayed by the addZIP Compression libraries are modal to the calling application.

Syntax

INT16 addZIP_SetParentWindowHandle(HWND hwnd)

Parameters

hwnd	the handle of the parent application

Returns

These functions return a non-zero value on success. A return value of zero indicates that hwnd does not exist.

Remarks

Although not strictly required, you are advised to always include this function call in your application.

Example(s)


addZIP_SetTempDrive

This function allows specification of an alternate drive (and directory if necessary) where addZIP can store temporary files.

Syntax

INT16 addZIP_SetTempDrive(LPCSTR lpsz)

Parameters

lpsz	the drive on which to store temporary files

Returns

These functions return a non-zero value on success. A return value of zero indicates that an error has occurred.

Remarks

When creating (or adding to) a .ZIP archive, a temporary file is used to hold the compressed files in the first instance. When compression is complete, the file is then renamed/copied to the location as specified in addZIP_ArchiveName. In many occasions the default drive for temporary files may not have enough space to hold the temporary archive, addZIP_SetTempDrive can be used to point to a drive that has sufficient space.

Example(s)


addZIP_SetWindowHandle

These functions are required if you want feedback from addZIP() and addUNZIP(). The handle passed via this function must be the window handle (hwnd) of an edit/text box.

Syntax

INT16 addZIP_SetWindowHandle(HWND hwnd)

Parameters

hwnd	the handle of the edit/text box used for passing messages

Returns

These functions return a non-zero value on success. A return value of zero indicates that the edit/text box does not exist.

Remarks

Example(s)


addZIP_SFXAutoExecute

The addZIP_SFXAutoExecute allows the specification of a file that will be executed immediately after a self-extracting archive has finished de-compressing the files

Syntax

INT16 addZIP_SFXAutoExecute(LPSTR szCommand, LPSTR szParameters)

Parameters

szCommand	this is the name of the file that will be executed after de-compression has finished

szParameters	the parameters passed to szCommand

Returns

This function returns a non-zero value if successful, 0 otherwise.

Notes

•	This function is only effective when creating self-extracting (SFX) archives

•	szCommand will be executed in the current directory

Example(s)

.


addZIP_SFXAutoPasswordPrompt

The addZIP_SFXAutoPasswordPrompt allows for the customisation of the self-extracting (SFX) archive created.

Syntax

INT16 addZIP_SFXAutoPasswordPrompt(INT16 bFlag)

Parameters

bFlag	set this value to TRUE is you want the user to be prompted for a password when executing the self-extracting archive.

Returns

This function returns a non-zero value if a password will be prompted, 0 otherwise.

Notes

•	The password prompt will be shown regardless of whether the archive contains encrypted compressed files

Example(s)


addZIP_Span

This function informs the library to span multiple diskettes if necessary.

Syntax

INT16 addZIP_Span(INT16 bFlag)

Parameters

bFlag	set this value to TRUE is you want to enable disk spanning

Returns

This function returns 0 if disk spanning is disabled, otherwise a non-zero value indicates that disk spanning is enabled.

Notes

•	Disk spanning will automatically overwrite any existing archive with the same name.

•	Spanned archives can be created on removable disks, ram drives (move the archive when prompted for a new disk) or on a hard drive (see addZIP_SpanCreateImages)

•	The size of the archives can be controlled using addZIP_SpanSizes

Example(s)


addZIP_SpanCreateImages

The addZIP_SpanCreateImages allows the user to create images of a spanned archive on a hard disk or other media.

Syntax

INT16 addZIP_SpanCreateImages(INT16 bFlag)

Parameters

bFlag	set this value to TRUE is you want to create spanned archive images

Returns

This function returns a non-zero value if creating images, 0 otherwise.

Notes

•	You must use the addZIP_Span and addZIP_SpanSizes functions as well

•	Each image will be stored under consecutively numbered subdirectories starting with 001, then 002 etc.

•	When creating the removable media, you must set the volume labels to contain the number of the disk e.g azback#001 for the first disk.

Example(s)


addZIP_SpanSizes

The addZIP_SpanSizes function allows the user to specify the sizes of the first and subsequent component parts of a multi-disk archive.

Syntax

INT16 addZIP_SpanSizes(UINT32  ulFirst, UINT32 ulOther)

Parameters

ulFirst	the size (in bytes) of the first part of the archive(or 0 for fill the disk)

ulOther	the size (in bytes) of the remaining component parts  (or 0 to fill the disk)

Returns

This function returns a non-zero value if disk sizes have been set correctly, 0 if there is an error.

Notes

•	You must use the addZIP_Span function

•	The smallest user-specified component part of a multi-disk archive is 20K.

Example(s)


addZIP_Store

This function allows the developer to specify a set of file extensions that will not be compressed.

Syntax

INT16 addZIP_Store(LPCSTR lpstr)

Parameters

lpstr	a pipe-delimited list of file extensions

Returns

This function returns a non-zero value on success. A return value of zero indicates an out of memory error.

Remarks

The default value is ARC|ARJ|LZH|Z|ZIP|ZOO. Files with these extensions are typically compressed files, further compression would be minimal, therefore these files will be stored without compression. This is strictly a speed optimisation. You may choose to override these extensions by specifying a zero-length string, or by specifying COMPRESSION_MAXIMUM in a call to addZIP_SetCompressionLevel.

Example(s)


addZIP_ToMemory

Allows data to be compressed directly into memory rather than to file.

Syntax

INT16 addZIP_ToMemory(LPSTR_T pszBuffer, UINT32_T ulBufferLen)

Parameter

pszBuffer	points to a buffer to hold the compressed data

ulBufferLen	the length of pszBuffer

Returns

The return value will be non-zero if the function call was successful. If zero, pszBuffer is null and/or ulBufferLen is 0.

Remarks

This function can be combined with addZIP_FromMemory for complete in-memory compression.

Example(s)


addZIP_Update

Allows an existing .ZIP archive to be updated - that is, only files that either i) do not currently exist, or ii) currently exist in the archive but are newer, will be compressed,

Syntax

INT16 addZIP_Update(INT16 iFlag)

Parameter

iFlag	set to TRUE if you want to updated the archive.

Returns

The return value will be non-zero if the archive will be updated on the next call to addZIP(). A value of zero indicates that addZIP() will process all files.

Remarks

The .ZIP archive (specified with addZIP_ArchiveName) must exist for this function to be valid.

Example(s)


addZIP_UseLFN

This function may be used to allow both 16- and 32-bit libraries to use long filenames when running on Windows 95 (NT?). The default value for the 16-bit library is FALSE (use short names), and TRUE for the 32-bit library (use long names).

Syntax

INT16 addZIP_UseLFN(INT16 fFlag)

Parameters

fFlag	TRUE to use long filenames when running under Windows 95. FALSE to use MS-DOS short names.

Returns

This function return a non-zero value on success.

Remarks

Example(s)


addZIP_View

This function allows the developer to display the contents of a .ZIP archive. Please see How do I view the contents of an archive? for more information.

Syntax

INT16 addZIP_View(INT16 bFlag)

Parameters

bFlag	set this value to true if you want to view the contents of the .ZIP archive.

Returns

This function returns a non-zero value on success.

Remarks

The addZIP version of _View will not handle archives split over multiple diskettes. Please use addUNZIP_View.

Example(s)


addUNZIP Function Reference

addUNZIP

addUNZIP_Abort *

addUNZIP_ArchiveName

addUNZIP_Decrypt

addUNZIP_DisplayComment

addUNZIP_Exclude

addUNZIP_ExcludeListFile

addUNZIP_ExtractTo

addUNZIP_GetLastError

addUNZIP_GetLastWarning

addUNZIP_GetVersion

addUNZIP_Freshen

addUNZIP_FromMemory (new)

addUNZIP_Include

addUNZIP_IncludeListFile

addUNZIP_Initialise

addUNZIP_InMemory (new)

addUNZIP_InstallCallback

addUNZIP_InstallCallbackEx

addUNZIP_Overwrite

addUNZIP_Register

addUNZIP_RestoreAttributes

addUNZIP_RestoreStructure

addUNZIP_SetParentWindowHandle

addUNZIP_SetWindowHandle

addUNZIP_Test

addUNZIP_ToMemory

addUNZIP_Update

addUNZIP_View


addUNZIP

The addUNZIP() function begins the decompression process.

Syntax

INT32 addUNZIP()

Parameters

None.

Returns

This function returns the number of files processed. If -1 is returned, there is no .ZIP archive name specified. 0 indicates no files have been processed.

Remarks

This functions should not be called without first specifying the name of the .ZIP archive (see addUNZIP_ArchiveName)

Example(s)


addUNZIP_Abort

The addUNZIP_Abort function allows you to abort the decompression process started by a call to addUNZIP().

Syntax

INT16 addUNZIP_Abort(INT16 bFlag)

Parameters

bFlag	pass a TRUE value if you wish to abort the current decompression process

Return

The return value from this function is 0 if the process will be aborted, non-zero otherwise.

Notes

•	this function should only be used when no callback function has been defined

•	the addUNZIP() function may not return immediatly after calling this function


addUNZIP_ArchiveName

This function specifies the name of the .ZIP archive to work with.

Syntax

INT16 addUNZIP_ArchiveName(LPCSTR lpsz)

Parameters

lpsz	the name of the .ZIP archive

Returns

The return value is non-zero if no error occurs. If it is zero, an error has occurred (probably out of memory).

Notes

•	This function is always required.

Example(s)


addUNZIP_Decrypt

This function instructs addUNZIP() to decrypt any encrypted files with the specified password. The default is not to decrypt encypted files.

Syntax

INT16 addZIP_Decrypt(LPCSTR lpsz)

Parameters

lpsz	the password with which to decrypt the files

Returns

The return value is non-zero if successful. A return value of zero indicates lack of sufficient memory.

Remarks

With the unregistered version of the addZIP Compression Libraries, lpsz is ignored, and the files can only be decrypted with the password Unregistered. Registered users will be provided with a registration code that will allow decryption with their own passwords.

Example(s)


addUNZIP_DisplayComment

This function will cause the archive comment to be displayed in a dialogue box at the start of the processing of the call to addUNZIP.

Syntax

INT16 addUNZIP_DisplayComment(INT16 bFlag)

Parameters

bFlag	set this value to TRUE to have the comment displayed

Returns

This function returns a non-zero value if the comment will be displayed. A return value of 0 means that the comment will not be displayed.

Remarks

Any archive comment will be passed as information (i.e. like the errors etc) during the normal processing irrespective of any call to this function.

Example(s)


addUNZIP_Exclude

This function allows for the exclusion of specified files. Any files matching those specified will be excluded from any processing. The default for this function is to exclude no files.

Syntax

INT16 addUNZIP_Exclude(LPCSTR lpsz)

Parameters

lpsz	the pipe-delimited (|) list of files to exclude.

Returns

These functions return a non-zero value on success. A return value of zero indicates that lpsz is NULL or there is not enough memory.

Remarks

As in all file functions that accept file specifications (except addZIP_ArchiveName), wildcard characters can be specified. For large numbers of file specifications, you may want to consider using a list file (see How do I use list files?).

Example(s)


addUNZIP_ExcludeListFile

This function allows the developer to specify the name of an existing file that contains a list of file specifications to exclude. The default is to not use a list file.

Syntax

INT16 addUNZIP_ExcludeListFile(LPCSTR lpsz)

Parameters

lpsz	the name of the existing file

Returns

These functions return a non-zero value on success. A return value of zero indicates that lpsz doesn't exist, wasn't found or is spelt incorrectly.

Remarks

Please see How do I use list files? for a discussion on list files and there uses.

Example(s)


addUNZIP_ExtractTo

This function sets the drive and directory where the files are to be extracted to. This will be the root directory for any restored directory structure. The default is to extract to the current directory.

Syntax

INT16 addUNZIP_ExtractTo(LPCSTR lpstr)

Parameters

lpstr	the name of the drive:directory to extract to

Returns

This function returns a non-zero value on success. A 0 indicates lack of memory (or lpstr is NULL).

Remarks

If the directory doesn't exist it will created in the same way as any stored directories (if addUNZIP_RestoreStructure is called).

Example(s)


addUNZIP_Freshen

Allows an existing .ZIP archive to be used to freshen the files stored on the destination drive/directory - that is, only files that currently exist on the destination drive/directory and in the archive will be decompressed, and only if the current ones are older than the archive ones.

Syntax

INT16 addUNZIP_Freshen(INT16 iFlag)

Parameter

iFlag	set to TRUE if you want to freshen the destination drive/directory

Returns

The return value will be non-zero if the drive/directory will be freshened on the next call to addUNZIP(). A value of zero indicates that addUNZIP() will process all files.

Remarks

Example(s)


addUNZIP_FromMemory

This function will allow the user to decompress a string originally compressed using addZIP_ToMemory

Syntax

INT16_T addUNZIP_FromMemory(LPSTR_T lpsz, UINT32_T lLength)

Parameters

lpsz	the compressed buffer

lLength	the length of the buffer

Returns

This function returns a non-zero value if the next call to addUNZIP will cause the file contents to be decompressed from the buffer. A zero value indicates that an error has occured.

Notes

•	This function will typically be used in conjunction with addUNZIP_ToMemory to accomplish in-memory compression and decompression.

Example(s)


addUNZIP_GetLastError

This function can be used to retrieve the last error code generated by the last call to addUNZIP().

Syntax

INT16 addUNZIP_GetLastError()

Parameters

None

Returns

This function will return a non-zero value if an error occurred during the last call to addUNZIP(). A value of 0 indicates that no error occurred.

Remarks

This function is useful for developers where the language can call functions in DLLs but cannot provide an interface for retrieving feedback information from the DLL.

Example(s)


addUNZIP_GetLastWarning

This function can be used to retrieve the last warning code generated by the last call to addUNZIP().

Syntax

INT16 addZIP_GetLastWarning(void)

Parameters

None

Returns

This function will return a non-zero value if a warning occurred during the last call to addUNZIP(). A value of 0 indicates that no warning occurred.

Remarks

This function is useful for developers where the language can call functions in DLLs but cannot provide an interface for retrieving feedback information from the DLL.

Example(s)


addUNZIP_GetVersion

The addUNZIP_GetVersion function retrieves the current version number of the addUNZIP Compression Library.

Syntax

void addUNZIP_GetVersion(UINT16 *iMajor, UINT16 *iMinor)

Parameters

iMajor	points to an unsigned 16-bit integer that will receive the major version number

iMinor	points to an unsigned 16-bit integer that will receive the minor revision number

Returns

This function has no return value.

Remarks

Example(s)


addUNZIP_Include

This function allows the developer to specify exactly which files to include during processing. The default is to include all (*.*) files.

Syntax

INT16 addUNZIP_Include(LPCSTR lpsz)

Parameters

lpsz	a delimited list file specifications (e.g. *.ini|*.grp)

Returns

This function returns a non-zero value on success. A return value of zero indicates that lpsz is NULL or there is not enough memory.

Remarks

As in all functions that accept file specifications (except addZIP_ArchiveName), wildcard characters can be specified. For large numbers of file specifications, you may want to consider using a list file (see How do I use list files?).

Example(s)


addUNZIP_IncludeListFile

This function allows the developer to specify the name of an existing file that contains a list of file specifications to include. The default is not to use a list file.

Syntax

INT16 addUNZIP_IncludeListFile(LPCSTR lpsz)

Parameters

lpsz	the name of the existing file

Returns

These functions return a non-zero value on success. A return value of zero indicates lpsz doesn't exist, wasn't found or is spelt incorrectly.

Remarks

Please see How do I use list files? for a discussion on list files and there uses.

Example(s)


addUNZIP_Initialise

This function initialises the addUNZIP Compression Library and must be the first function called.

Syntax

void addUNZIP_Initialise(void)

Parameters

None

Returns

This function does not return a value.

Remarks

If this function is omitted, the performance of the library may be erratic.

Example(s)


addUNZIP_InMemory

Allows data to be decompressed in memory.

Syntax

INT16_T addUNZIP_FromMemory(LPSTR_T pszInBuffer, UINT32_T ulInLen, LPSTR_T pszOutBuffer, UINT32_T ulOutLen)

Parameter

pszInBuffer	points to the buffer to decompress

ulInLen	the size of pszInBuffer

pszOutBuffer	points to the buffer to hold the decompressed data

ulOutLen	the size of pszOutBuffer

Returns

The return value will be the decompressed size of pszInBuffer. If zero is returned, an error has occurred. This error can be retrieved using addUNZIP_GetLastError().

Notes

•	Unlike the other functions in the addUNZIP library, this function executes immediately.

•	pszOutBuffer should be of sufficient size to hold the decompressed version of pszInBuffer

Example(s)


addUNZIP_InstallCallback

Allows the developer to specify an application-defined function that will be called regularly during the processing of addUNZIP(). The callback function can then process the passed message information as necessary.

Syntax

INT16 addUNZIP_InstallCallback(CALLBACKFN cbFunction)

Parameter

cbFunction	specifies the name of the callback function

Returns

This function returns a non-zero number on success, 0 on failure.

Remarks

Please refer to the How do I get feedback from the libraries? for further information on using callback functions.

Example(s)

#include "addunzip.h"

INT16 CALLBACK mycallback(INT16 iLibrary, INT16 iMessage, char *szInfo) {

switch (iMessage) {

case default:

// default handling here

case AM_UNZIPPING:

// update user interface here

...

}

return 1;

}

int main() {

if (addUNZIP_InstallCallback((CALLBACKFN)mycallback) == 0) {

// error processing

}

if (addUNZIP_ArchiveName("full.zip") == 0) {

// error processing

}

if (addUNZIP_Include("c:\\*.*") == 0) {

// error processing

}

addUNZIP_RestoreStructure(TRUE);

addZIP();

}


addUNZIP_InstallCallbackEx

Allows the developer to specify an application-defined function that will be called regularly during the processing of addUNZIP(). The callback function can then process the passed message information as necessary. Unlike addUNZIP_InstallCallback, the developer may pass a known value into the callback function.

Syntax

INT16 addUNZIP_InstallCallbackEx(CALLBACKFN cbFunction, UINT32 lParam)

Parameter

cbFunction	specifies a pointer to the application-defined callback function

lParam	specifies a 32-bit, application-defined value to be passed to the callback function

Returns

This function returns a non-zero number on success, 0 on failure.

Remarks

Please refer to the How do I get feedback from the libraries? for further information on using callback functions and message reference.

Example(s)

#include "addunzip.h"

INT16 CALLBACK mycallback(INT16 iLibrary, INT16 iMessage, char *szInfo, UINT32 lParam) {

switch (iMessage) {

case default:

// default handling here

case AM_UNZIPPING:

// update user interface here

...

}

return 1;

}

int main() {

UINT32 my_value = 10;

if (addUNZIP_InstallCallback((CALLBACKFN)mycallback, my_value) == 0) {

// error processing

}

if (addUNZIP_ArchiveName("full.zip") == 0) {

// error processing

}

if (addUNZIP_Include("c:\\*.*") == 0) {

// error processing

}

addUNZIP_RestoreStructure(TRUE);

addZIP();

}


addUNZIP_Overwrite

This function allows the developer to change how addUNZIP deals with files that already exist in the directory to extract to. The default is to prompt the user to choose between overwriting the existing file or skipping the file.

Syntax

INT16 addUNZIP_Overwrite(INT16 fExist)

Parameters

fExist	one of OVERWRITE_QUERY, OVERWRITE_ALL or OVERWRITE_NONE. The constants are self-explanatory. The default is OVERWRITE_QUERY.

Returns

These functions returns a non-zero value on success. A return value of zero indicates an incorrect constant was given.

Remarks

If a file exists in the archive with the same name as the one being added, the default action is to display a dialog box allowing the user to choose which file to keep. If the user selects YES (or YES TO ALL) the existing file will be overwritten with the new file; if NO (or NO TO ALL) is selected the existing file is kept.Files are compared using full path information if it exists, so ctl3d.dll, system\ctl3d.dll and windows\system\ctl3d.dll are unique files.

Example(s)


addUNZIP_Register

This function register the addZIP Compression Libraries, allowing the use of your own passwords in the addUNZIP_Decrypt function.

Syntax

INT16 addUNZIP_Register(LPCSTR lpszName, UINT32 lPassword)

Parameters

lpszName	the registered user name

lPassword	the provided registration number

Returns

This function returns a non-zero value on success. A return value of zero indicates that registration has failed. If this is the case, please make sure you entered the function parameters as specified in the registration pack.

Remarks

Example(s)


addUNZIP_RestoreAttributes

Allows the specified file attributes to be de-compressed along with the file.

Syntax

INT16 addUNZIP_RestoreAttributes(INT16 iAttributes)

Parameter

iAttributes	specifies the attributes to be restored. This can be any combination of  azATTR_READONLY, azATTR_HIDDEN, azATTR_SYSTEM and azATTR_ARCHIVE. For convenience there also flags to specify no attributes are restored (azATTR_NONE) and to restore all attributes (azATTR_ALL).

Returns

The return value represents the attributes that will be restored during the processing of addUNZIP (i.e. it should return the same value that was passed as a parameter).

Remarks

Example(s)


addUNZIP_RestoreStructure

This function recreates the directory structure stored in the .ZIP archive. The default is not to restore the directory structure.

Syntax

INT16 addUNZIP_RestoreStructure(INT16 bFlag)

Parameters

bFlag	Set this value to TRUE to restore the stored directory structure.

Returns

This function returns a non-zero value if successful.

Remarks

Example(s)


addUNZIP_SetParentWindowHandle

This function is required so that any dialog boxes displayed by the addZIP Compression libraries are modal to the calling application.

Syntax

INT16 addUNZIP_SetParentWindowHandle(HWND hwnd)

Parameters

hwnd	the handle of the parent application

Returns

These functions return a non-zero value on success. A return value of zero indicates that hwnd does not exist.

Remarks

Although not strictly required, you are advised to always include this function call in your application.

Example(s)


addUNZIP_SetWindowHandle

This function is required if you want feedback from addUNZIP(). The handle passed via this function must be the window handle (hwnd) of an edit/text box.

Syntax

INT16 addUNZIP_SetWindowHandle(HWND hwnd)

Parameters

hwnd	the handle of the edit/text box used for passing messages

Returns

These functions return a non-zero value on success. A return value of zero indicates that the edit/text box does not exist.

Remarks

Example(s)


addUNZIP_Test

This function tests the integrity of a .ZIP archive.

Syntax

INT16 addUNZIP_Test(INT16 bFlag)

Parameters

bFlag	Set this vale to TRUE to test the .ZIP archive.

Returns

This function returns a non-zero value if the archive will be tested (i.e. no extraction) on the next call to addUNZIP(). A zero value indicates that addUNZIP() will extract files.

Remarks

See the topic How do I check the integrity of a .ZIP archive?

Example(s)


addUNZIP_ToMemory

This function will allow the user to extract a file (or portion of a file) to memory. Visual Basic users should note that VB strings may not work when passed to this function. You are advised to use the method shown in the example below.

Syntax

BOOL addUNZIP_ToMemory(LPSTR lpsz, long lLength)

Parameters

lpsz	the allocated buffer to hold the file contents

lLength	the length of the buffer

Returns

This function returns a non-zero value if the next call to addUNZIP will cause the file contents to be extracted to the buffer. A zero value indicates that an error has occured.

Remarks

The user will typically make a call to addUNZIP_Include to limit the extraction to one relevant file. If the uncompressed file is larger than the buffer, then the contents will be truncated at buffer length. The end of the file is indicated by the addition of a NULL (ascii value 0).

Example(s)

Visual Basic

Dim I As Integer

   	Dim J As Long

Dim aString As String

Dim hString As Long

Dim lpString As Long

hString = GlobalAlloc(GPTR, 2000)

lpString = GlobalLock(hString)

I = addUNZIP_ArchiveName("example.zip")

I = addUNZIP_Include("somefile.txt")

I = addUNZIP_ToMemory(lpString, 2000)

J = addUNZIP()

aString = Space$(2000)

lpString = lstrcpy(aString, lpString)

MsgBox aString

lpString = GlobalUnlock(hString)

lpString = GlobalFree(hString)


addUNZIP_Update

Allows an existing .ZIP archive to be used to update the files stored on the destination drive/directory - that is, only files either i) do not exist, or ii) that currently exist on the destination drive/directory and in the archive will be decompressed, and only if the current ones are older than the archive ones.

Syntax

INT16 addUNZIP_Update(INT16 iFlag)

Parameter

iFlag	set to TRUE if you want to update the drive/directory

Returns

The return value will be non-zero if the files will be updated on the next call to addUNZIP(). A value of zero indicates that addUNZIP() will process all files.

Remarks

Example(s)


addUNZIP_View

This function allows the developer to display the contents of a .ZIP archive. Please see How do I view the contents of an archive? for more information.

Syntax

INT16 addUNZIP_View(INT16 bFlag)

Parameters

bFlag	set this value to true if you want to view the contents of the .ZIP archive.

Returns

This function returns a non-zero value on success.

Remarks

•	The addUNZIP_View function can be used to view the contents of a multi-disk archive

Example(s)


ActiveX Controls

From v0.7, the addZIP Compression Libraries includes ActiveX Custom Control versions of the dynamic link libraries. These controls are compatible with all development environments that support ActiveX controls. As well as providing easier access to the powerful functionality of the original libraries, the ActiveX controls bring a customisable user interface, that allows the provision of feedback on the processing of .ZIP archives.

The ActiveX controls must be registered prior to use. This can be achieved by typing the following

regsvr32.exe azip32.ocx

regsvr32.exe aunzip32.ocx

Note that the license file (addZIP.lic) must be in the same directory as the ActiveX controls. DO NOT DISTRIBUTE THE LICENSE FILE WITH YOUR APPLICATIONS.

See also

addZIP Custom Control

addUNZIP Custom Control

Properties

Methods

Events


addZIP Custom Control

Properties     Methods     Events     Example

The addZIP control allows you to create and manipulate .ZIP archives.

Remarks

Use the addZIP control to

•	add files to a .ZIP archive

•	delete files from a .ZIP archive


Properties
Align

Appearance

ArchiveName

BackColor

Build

Caption

CompressionLevel

DragIcon

DragMode

Encrypt

Exclude

ExcludeListFile

Font

ForeColor

Height

HelpContextID

Include

IncludeListFile

Index

Left

LeftColor

Move

Negotiate

Overwrite

Password

Recurse

RightColor

Segments

Span

Style

Tag

TextBackColor

TextForeColor

ToolTipText

Top

Version

Visible

WhatsThisHelpID

Width


Methods
Abort

Clear

Delete

Freshen

Update

View

Zip


Events
Deleted

Deleting

QueryDiskChange

QueryOverwrite

View

ZipError

Zipped

Zipping

ZipWarning


addUNZIP Custom Control

Properties     Methods     Events     Example

The addUNZIP control allows you to view and manipulate .ZIP archives

Remarks

Use the addUNZIP control to

•	view the file information with a .ZIP archive

•	extract files from .ZIP archives

•	test .ZIP archives


Properties
Align

Appearance

ArchiveName

BackColor

Build

Caption

Decrypt

DragIcon

DragMode

Exclude

ExcludeListFile

ExtractTo

Font

ForeColor

Height

HelpContextID

Include

IncludeListFile

Index

Left

LeftColor

Negotiate

Overwrite

Password

RestoreAttributes

RestoreStructure

RightColor

Segments

Style

TabIndex

TabStop

Tag

TextBackColor

TextForeColor

ToolTipText

Top

Version

Visible

WhatsThisHelpID

Width


Methods
Abort

Clear

Freshen

Test

Unzip

Update

View


Events
QueryDiskChange

QueryOverwrite

Tested

Testing

UnzipError

Unzipped

Unzipping

UnzipWarning

View


Properties A to Z

Appearance - addZIP & addUNZIP

ArchiveName - addZIP & addUNZIP

Build - addZIP & addUNZIP

Caption - addZIP & addUNZIP

CompressionLevel - addZIP

Decrypt - addUNZIP

Encrypt - addZIP

Exclude - addZIP & addUNZIP

ExcludeListFile - addZIP & addUNZIP

ExtractTo - addUNZIP

Include - addZIP & addUNZIP

IncludeListFile - addZIP & addUNZIP

LeftColor - addZIP & addUNZIP

Move - addZIP

Overwrite - addZIP & addUNZIP

Password - addZIP & addUNZIP

Recurse - addZIP

RestoreAttributes -addUNZIP

RestoreStructure - addUNZIP

RightColor - addZIP & addUNZIP

Segments - addZIP & addUNZIP

Span - addZIP

Style - addZIP & addUNZIP

TextBackColor - addZIP & addUNZIP

TextForeColor - addZIP & addUNZIP

Version - addZIP & addUNZIP


Appearance property

Returns or sets the appearance of the control.

Syntax

object.Appearance = [appearance]

The Appearance property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

appearance	a expression that specifies whether to draw the control flat of 3-dimensional

ccFlat (0)	Flat. Paints the control without visual effect

cc3D (1)	(Default) 3D. Paint the control with three-dimensional effects

Remarks

Like all the settable properties of the addZIP and addUNZIP controls, you can change this value at design-time and at run-time. This is different to the standard Appearance property which is read-only at run-time.

Example

See also


ArchiveName property

Returns or sets the name of .ZIP archive.

Syntax

object.ArchiveName [= pathame]

The ArchiveName property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

pathname	a string expression that evaluates to .ZIP archive name

Remarks

If your network system supports it, pathname can be a fully qualified network path name such as \\aserver\ashare\adirectory\a.zip.

The extension of the archive will default to .ZIP if not specified.

Example

See also

addZIP_ArchiveName

addUNZIP_ArchiveName


Build property

Returns the build number of the object.

Syntax

object.Build

The Build property syntax has this part

object	an Object Expression that evaluates to an addZIP or addUNZIP object

Remarks

The Build property should be used in conjunction with the Version property to determine the release of the object you are using.

When new versions of the controls are released, the Build number may be lower than previous releases.

Example

I = addZIP.Build

J = addZIP.Version

See also

Version property


Caption property

Returns or sets the text that will be displayed on top of the progress bar. A zero-length string will cause nothing to be displayed.

Syntax

object.Caption = [string]

The Caption property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

string	a string expression that evaluates to the string to display on the progress bar

Remarks

The caption can only be shown on a standard or a gradient style progress bar - it cannot be displayed on a segmented progress bar.

By default, the caption is <P>%, where the <P> is a placeholder for the percentage figure.

Example

addZIP.Style = STYLE_GRADIENT

addZIP.Caption = "<P>% complete"

See also


CompressionLevel Property

Returns or sets the compression level to be used.

Syntax

object.CompressionLevel = [level]

The CompressionLevel property syntax has these parts

object	an Object Expression that evaluates to an addZIP object

level	an expression that evaluates to one of the following

LEVEL_NONE (0)	All files will be stored in the .ZIP archive without compression. This is the fastest level.

LEVEL_MINIMUM (1)	The files will be compressed a minimum level of compression - nut it will be quite quick.

LEVEL_NORMAL (2)	The file will be compressed with average compression.

LEVEL_MAXIMUM (3)	The file will be compressed using the maximum compression - this is the slowest level.

Remarks

Example

addZIP.CompressionLevel = LEVEL_MAXIMUM

See also

addZIP_SetCompressionLevel


Decrypt property

Returns or sets whether encrypted files in the.ZIP archive should be decrypted.

Syntax

object.Decrypt = [boolean]

The Decrypt property syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

boolean	a boolean expression that specifies whether encrypted files in the .ZIP archive should be decrypted with the value stored in the Password property.

Remarks

Encrypted files will be skipped if Decrypt is set to FALSE, or if an invalid password is specified.

Example

addUNZIP.ArchiveName = "secrets.zip"

addUNZIP.Include = "*.*"

addUNZIP.Decrypt = TRUE

addUNZIP.Password = "qwertyuiop"

addUNZIP.Unzip

See also

addUNZIP_Decrypt


Encrypt property

Returns or sets whether files added to a ZIP archive should be encrypted.

Syntax

object.Encrypt = [boolean]

The Encrypt property syntax has these parts

object	an Object Expression that evaluates to an addZIP object

boolean	a boolean expression that specifies files added to the .ZIP archive should be encrypted with the value stored in the Password property.

Remarks

Example

addZIP.ArchiveName = "secrets.zip"

addZIP.Include = "*.*"

addZIP.Encrypt = TRUE

addZIP.Password = "qwertyuiop"

addZIP.Zip

See also

addZIP_Encrypt


Exclude property

Returns or sets the filespecs used to exclude files from processing.

Syntax

object.Exclude = [string]

The Exclude property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

string	a string expression that evaluates to a list of pipe-delimited filespecs

Remarks

With a large number of filespecs, it is easier to use a list file and the ExcludeListFile property

Example

addZIP.ArchiveName = "d:\backup.zip"

addZIP.Include = "c:\*.*"

addZIP.Recurse = TRUE

addZIP.Exclude = "*.exe|*.dll|*.sys|*.drv"

addZIP.Zip

See also

addZIP_Exclude

addUNZIP_Exclude


ExcludeListFile property

Returns or sets the name of a file that contains a list of filespecs

Syntax

object.ExcludeListFile = [pathname]

The ExcludeListFile property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

pathname	a string expression that evaluates to a file containg a list of filespecs

Remarks

With a large number of filespecs, it is much easier to use a list file.

Example

addZIP.ArchiveName = "d:\backup.zip"

addZIP.Include = "c:\*.*"

addZIP.Recurse = TRUE

addZIP.ExcludeListFile = "c:\system.lst"

addZIP.Zip

See also

addZIP_ExcludeListFile

addUNZIP_ExcludeListFile


ExtractTo property

Returns or sets the drive and/or directory where the files will be extracted to.

Syntax

object.ExtractTo = [pathname]

The ExtractTo property syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

pathname	a string expression that evaluates to a drive and/or directory

Remarks

Without using this property, all files will be extracted to the current directory, or to a subdirectory of the current directory if RestoreStructure = TRUE

Example

addUNZIP.ArchiveName = "INI.zip"

addUNZIP.Include = "*.ini"

addUNZIP.ExtractTo = "c:\windows"

addUNZIP.Unzip

See also

addUNZIP_ExtractTo


Include property

Returns or sets the filespecs used to include files from processing.

Syntax

object.Include = [string]

The Include property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

string	a string expression that evaluates to a list of pipe-delimited filespecs

Remarks

With a large number of filespecs, it is easier to use a list file and the IncludeListFile property

Example

addZIP.ArchiveName = "backup.zip"

addZIP.Include = "c:\windows\*.ini|d:\work\*.*"

addZIP.Zip

See also

addZIP_Include

addUNZIP_Include


IncludeListFile property

Returns or sets the name of a file that contains a list of filespecs

Syntax

object.IncludeListFile = [pathname]

The IncludeListFile property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

pathname	a string expression that evaluates to a file containg a list of filespecs

Remarks

With a large number of filespecs, it is much easier to use a list file.

Example

addZIP.ArchiveName = "backup.zip"

addZIP.IncludeListFile = "myfiles.lst"

addZIP.Zip

See also


LeftColor Property

Returns or sets the colour of the progress bar on the left hand side of a gradient style bar. It is unused for both the standard and segmented styles.

Syntax

object.LeftColor = [color]

The LeftColor property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

color	an expression which evaluates to a colour. The default value is green.

Remarks

Example

addZIP.Style = STYLE_GRADIENT

addZIP.LeftColor = RGB(255, 0, 0)

addZIP.RightColor = RGB(0, 255, 0)

See also

RightColor property

Style property


Move Property

Returns or sets whether files will be deleted after they have been compressed to the .ZIP archive.

Syntax

object.Move = [boolean]

The Move property syntax has these parts

object	an Object Expression that evaluates to an addZIP object

boolean	a boolean expression that specifies whther to leave files as they are, or delete them after compression

Remarks

Example

addZIP.ArchiveName = "oldfiles"

addZIP.Include = "c:\dos\*.*"

addZIP.Move = TRUE

addZIP.ZIP

See also

addZIP_Move


Overwrite Property

Returns or sets how clashes of filenames are dealt with.

Syntax

object.Overwrite = [value]

The Overwrite property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

value	an expression that evaluates to one of the following

OVERWRITE_QUERY (10)	A QueryOverwrite event will be fired

OVERWRITE_ALL (11)	All files will be overwritten

OVERWRITE_NONE (12)	No files will be overwritten

Remarks

A filename cannot occur more than once in a .ZIP archive.

Example

addUNZIP.ArchiveName = "restore.zip"

addUNZIP.Include = "*.dll"

addUNZIP.ExtractTo = "c:\windows\system"

addUNZIP.Overwrite = OVERWRITE_NONE

addUNZIP.UNZIP

See also

addZIP_Overwrite

addUNZIP_Overwrite


Password Property

Returns or sets the password used to encrypt (using addZIP) or decrypt (using addUNZIP) files from .ZIP archives.

Syntax

object.Password = [string]

The Password property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

string	a string expression that evaluates to a password

Remarks

You must set the Encrypt property to True, and the Decrypt property to True, when using addZIP and addUNZIP respectively.

Choose your password carefully - .ZIP file encryption is susceptible to brute-force attack when short passwords are used.

Example

addZIP1.Encrypt = True

addZIP1.Password = "an easy to remember password"

See also

addZIP_Encrypt

addUNZIP_Decrypt

How do I encrypt/decrypt files?


Recurse property

Returns or sets whether and directories found should be searched for matching files

Syntax

object.Recurse = [boolean]

The Recurse property syntax has these parts

object	an Object Expression that evaluates to an addZIP object

boolean	a boolean expression that specifies whether any directories found should be searched for mathcing files.

Remarks

Example

This example will recurse through all the directories on the local C:\ drive looking for all the files that match *.bat

addZIP.ArchiveName = "BATCH.ZIP"

addZIP.Include = "*.BAT"

addZIP.Recurse = TRUE

addZIP.Zip

See also

addZIP_Recurse


RestoreAttributes property

Returns or sets the file attributes that will be restored.

Syntax

object.RestoreAttributes = [attributes]

The RestoreAttributes property syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

attributes	a numeric expression that evaluates to the attributes to be restored. This expression can be a combination of the following values

FILE_ATTRIBUTE_ARCHIVE	Applications use this attribute to mark files for backup or removal.

FILE_ATTRIBUTE_HIDDEN	It is not included in an ordinary directory listing.

FILE_ATTRIBUTE_NORMAL	The file has no other attributes set. This is onluy valid when used alone.

FILE_ATTRIBUTE_READONLY	Applications can read the file but cannot write to it or delete it.

FILE_ATTRIBUTE_SYSTEM	The file is part of the operating system, or is used exclusively by it.

Remarks

The attributes can only be restored if they were stored in the .ZIP archive during compression.

Example

addUNZIP.RestoreAttributes = FILE_ATTRIBUTE_HIDDEN | FILE_ARCHIVE_HIDDEN

See also


RestoreStructure property

Returns or sets a value that determines whether stored directories that may have been stored in the .ZIP archive are used in during the decompression. The default is FALSE i.e. to extract the files to the current directory.

Syntax

object.RestoreStructure = [boolean]

The RestoreStructure property syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

boolean	a boolean expression that specifies whether to use the compressed directory structure or not.

Remarks

Example

addUNZIP.ArchiveName = "FullBackup.ZIP"

addUNZIP.Include = "*.*"

addUNZIP.ExtractTo = "c:\"

addUNZIP.Overwrite = OVERWRITE_ALL

addUNZIP.RestoreStructure = TRUE

addUNZIP.UNZIP

See also

addUNZIP_RestoreStructure


RightColor Property

Returns or sets the colour of the progress bar on the right hand side of a gradient style bar. It is unused for both the standard and segmented styles.

Syntax

object.RightColor = [color]

The RightColor property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

color	an expression which evaluates to a colour. The default value is red.

Remarks

Example

addZIP.RightColor = RGB(128, 128, 128)

addZIP.LeftColor = RGB(0, 255, 255)

addZIP.Style = STYLE_GRADIENT

addZIP.ZIP

See also

LeftColor property

Style property


Segments Property

Returns or sets the number of segments to display when the Style property is set to STYLE_GRADIENT.

Syntax

object.Segments = [segments]

The Segments property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

segments	a numeric expression that evaluates to a positive integer

Remarks

The range of valid values for segments ranges from 0 to approximately half the width of the control. With 0 segments, the progress bar will be displayed like a STYLE_STANDARD bar, except for a thin border between the bar and the edge of the control.

The number of segments does not change if the width and/or height of the control changes.

Example

addZIP.Style = STYLE_SEGMENTED

addZIP.Segments = 10

See also

Style property


Span property

Returns or sets whether to create the archive on multiple removable media.

Syntax

object.Span = [boolean]

The Span property syntax has these parts

object	an Object Expression that evaluates to an addZIP object

boolean	a boolean expression that specifies whether to create mutliple archives

Remarks

Example

addZIP.ArchiveName = "a:\backup.zip"

addZIP.Include = "c:\*.*"

addZIP.Recurse = TRUE

addZIP.Span = TRUE

addZIP.Zip

See also

addZIP_Span


Style property

Returns or sets the style of progress bar to be displayed.

Syntax

object.Style = [value]

The Style property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

value	an expression which evaluates to one of the following styles:

STYLE_STANDARD (0)	Displays a solid bar

STYLE_SEGMENTED (1)	Displays a bar with user-defined segments

STYLE_GRADIENT (2)	Displays a bar that is shaded from LeftColor to RightColor

Remarks

Example

addZIP1.Style = GRADIENT

See also

LeftColor property

RightColor property

Segments property


TextBackColor property

Returns or sets the colour of the caption when displayed on top of the background colour.

Syntax

object.TextBackColor = [color]

The TextBackColor property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

color	an expression which evaluates to a colour. The default value is the colour of the highlight.

Remarks

Example

addZIP.TextBackColor = RGB(0, 255, 0)

See also

TextForeColor property


TextForeColor property

Returns or sets the colour of the caption when displayed on top of the foreground colour.

Syntax

object.TextForeColor = [color]

The TextForeColor property syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

color	an expression which evaluates to a colour. The default value is the colour of a button face (COLOR_BTNFACE in the Windows API)

Remarks

Example

addZIP1.TextForeColor = RGB(255, 0, 0)

See also

TextBackColor property


Version property

Returns the current version of the object.

Syntax

object.Version

The Version property syntax has this parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

Remarks

The Version property returns a decimal value.

Example

i = addZIP.Version

j = addZIP.Build

See also

Build property


Methods A to Z

Abort - addZIP & addUNZIP

AboutBox - addZIP & addUNZIP

Clear - addZIP & addUNZIP

Delete - addZIP

Freshen - addZIP & addUNZIP

Test - addUNZIP

Unzip - addUNZIP

Update - addZIP & addUNZIP

View - addZIP & addUNZIP

Zip - addZIP


Abort method

Will cause the current addZIP or addUNZIP process to stop

Syntax

object.Abort

where object is an addZIP or addUNZIP control

Remarks


Clear method

This method will reset the progress bar percentage back to zero.

Syntax

object.Clear

where object is an addZIP or addUNZIP control

Remarks

Because there is no percentage property, this is the only way to reset the progress bar percentage back to 0 after a unzip/zip process.


Delete method

This method is used to remove files from a .ZIP archive.

Syntax

object.Delete

where object is an addZIP control

Remarks

This method returns the number of files that were deleted


Freshen method

addZIP This method is used to refresh the contents of a .ZIP archive. Files will only be added if they currently exist in the archive and the disk files are newer than those in the .ZIP archive.

addUNZIP This method is used to refresh the contents of a drive/directory based on the contents of a .ZIP archive. Files will only be extracted if they already exist on the disk, but the files in the archive are newer. Files that dont already exist, or newer ones that do exist, will be skipped.

Syntax

object.Freshen

where object is an addZIP or addUNZIP control

Remarks

•	This method returns the number of files that were freshened


Test method

The method allows the .ZIP archive to be tested to make sure it is extractable.

Syntax

object.Test

where object is an addUNZIP control

Remarks

•	The process that runs during the testing is exactly the same as the unzip process, except no files are actually decompressed.

•	The events Testing and Tested will repeatedly be fired.

•	This method returns the number of files tested.


Unzip method

This method will extract files from a  .ZIP archive based on the objects properties.

Syntax

object.Unzip

where object is an addUNZIP object

Remarks

•	This method returns the number of files successfully unzipped.

•	The Unzipping and Unzipped events will be fired multiple times.


Update method

addZIP This method will update the current .ZIP archives - new files will be added, and existing files will be overwritten if newer ones exist.

addUNZIP This method will update the current (or specified) directory with new files that do not exist, and existing files will be overwritten if newer ones exist in the archive.

Syntax

object.Update

where object is an addZIP or addUNZIP control.

Remarks

•	This method returns the number of files updated.


View method

Will fire the View event for every file in the .ZIP archive that matches the Include and/or IncludeListFile properties excluding those that match the properties Exclude and/or ExcludeListFile.

Syntax

object.View

where object is an addUNZIP or addZIP control.

Remarks

•	You are advised to use the addUNZIP View method/event rather than the addZIP method/event (which will not handle spanned archives)

•	This method returns the number of files viewed.


Zip method

This method will create (or add to an existing) .ZIP archive, based on the controls properties.

Syntax

object.Zip

where object is an addZIP control

Remarks

•	This method returns the number of files zipped.

•	The Zipping and Zipped events will be called multiple times.


Events A to Z

Deleting - addZIP

Deleted - addZIP

QueryDiskChange - addZIP & addUNZIP

QueryOverwrite - addZIP & addUNZIP

Tested - addUNZIP

Testing - addUNZIP

UnzipError - addUNZIP

Unzipped - addUNZIP

Unzipping - addUNZIP

UnzipWarning - addUNZIP

View - addZIP & addUNZIP

ZipError - addZIP

Zipped - addZIP

Zipping - addZIP

ZipWarning - addZIP


Deleted event

Occurs when a file has been deleted from a .ZIP archive

Syntax

Private Sub object_Deleted(file As String)

The Deleted event syntax has these parts

object	an Object Expression that evaluates to an addZIP control

file	the name of the file that has been deleted

Remarks

•	This event will be fired once for every file deleted


Deleting event

Occurs when a file is about to be deleted from a .ZIP archive

Syntax

Private Sub object_Deleting(file As String)

The Deleted event syntax has these parts

object	an Object Expression that evaluates to an addZIP control

file	the name of the file that is being deleted

Remarks

•	This event will be fired once for every file being deleted


QueryDiskChange event

Occurs when

Syntax

Private Sub object_QueryDiskChange(Number As Integer)

The QueryDiskChange event syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

Number	For addZIP, this is the number of the current disk

For addUNZIP, this is the number of the required disk

Remarks

•	You should prompt the user to change disks in this event.

•	This event will only be fired when creating, or extracting from, spanned archives.

•	If Number is 0, it means that the last disk is requested


QueryOverwrite event

Occurs when

Syntax

Private Sub object_QueryOverwrite(ExistingFile As String, ExistingSize As Long, ExistingDateTime As String, NewFile As String, NewSize As Long, NewDateTime As String, Response As Integer, NewName As String)

The QueryOverwrite event syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

ExistingFile	the name of the existing file

ExistingSize	the size in bytes of the existing file

ExistingDateTime	the date and time stamp of the existing file (in DD Mmmm CCYY hh:mm format)

NewFile	the name of the file that will overwrite ExistingFile (these of course will be the same)

NewSize	the size in bytes of the new file

NewDateTime	the date and time stamp of the new file (in DD Mmmm CCYY hh:mm format)

Response	the value that you must set to one of

AQO_YES (0) the file should be overwritten

AQO_YESTOALL (1) this file and all subsequent ones should be overwritten

AQO_NO (2) the file should not be overwritten

AQO_NOTOALL  (3) this file and all subsequent ones should not be overwritten

NewName	Reserved for future use

Remarks


Tested event

Occurs after a file has been tested

Syntax

Private Sub object_Tested(File As String, OriginalSize As Long, BytesDecompressed As Long, Percentage As Integer,  TotalFiles As Long, ProcessedFiles As Long, TotalBytes As Long, ProcessedBytes As Long)

The Tested event syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

File	the name of the tested file

OriginalSize	the original i.e. uncompressed size of the file

BytesDecompressed	the number of bytes that have been tested (this should be the same as OriginalSize)

Percentage	the percentage completion of the current file (this should be 100)

TotalFiles	the total number of files to test

ProcessedFiles	the number of files that have been processed

TotalBytes	the total number of bytes to test

ProcessedBytes	the number of bytes that have been tested

Remarks


Testing event

Occurs repeatedly during the testing of a files contained in a .ZIP archive

Syntax

Private Sub object_Testing(File As String, OriginalSize As Long, BytesDecompressed As Long, Percentage As Integer,  TotalFiles As Long, ProcessedFiles As Long, TotalBytes As Long, ProcessedBytes As Long)

The Testing event syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

File	the name of the current file being tested

OriginalSize	the original i.e. uncompressed size of the file being tested

BytesDecompressed	the number of bytes of the current file that have been tested

Percentage	the percentage completion of the current file

TotalFiles	the total number of files to test

ProcessedFiles	the number of files that have been processed

TotalBytes	the total number of bytes to test

ProcessedBytes	the number of bytes that have been tested

Remarks

•	This event will be fired multiple times per file


UnzipError event

When an error occurs during the compression, a UnzipError event will occur.

Syntax

Private Sub object_UnzipError(File As String, Number As Integer, Message As String)

The UnzipError event syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

File	the name of the file being processed

Number	the number of the error

Message	reserved for future use

Remarks

Most errors are fatal i.e. processing will stop


Unzipped event

Occurs after a file has been unzipped

Syntax

Private Sub object_Unzipped(File As String, OriginalSize As Long, BytesDecompressed As Long, Percentage As Integer,  TotalFiles As Long, ProcessedFiles As Long, TotalBytes As Long, ProcessedBytes As Long)

The Unzipped event syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

File	the name of the unzipped file

OriginalSize	the original i.e. uncompressed size of the file

BytesDecompressed	the number of bytes of the file that have been unzipped

Percentage	the percentage completion of the current file (should be 100)

TotalFiles	the total number of files to unzip

ProcessedFiles	the number of files that have been processed

TotalBytes	the total number of bytes to unzip

ProcessedBytes	the number of bytes that have been tested

Remarks


Unzipping event

Occurs repeatedly during the unzipping of files

Syntax

Private Sub object_Unzipping(File As String, OriginalSize As Long, BytesDecompressed As Long, Percentage As Integer,  TotalFiles As Long, ProcessedFiles As Long, TotalBytes As Long, ProcessedBytes As Long)

The Unzipping event syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

File	the name of the current file being unzipped

OriginalSize	the original i.e. uncompressed size of the file being unzipped

BytesDecompressed	the number of bytes of the current file that have been unzipped

Percentage	the percentage completion of the current file

TotalFiles	the total number of files to unzip

ProcessedFiles	the number of files that have been processed

TotalBytes	the total number of bytes to unzip

ProcessedBytes	the number of bytes that have been unzipped

Remarks


UnzipWarning event

When an warning occurs during de-compression, a UnzipWarning event will occur.

Syntax

Private Sub object_UnzipWarning(File As String, Number As Integer, Message As String)

The UnzipWarning event syntax has these parts

object	an Object Expression that evaluates to an addUNZIP object

File	the name of the file being processed

Number	the number of the warning

Message	reserved for future use

Remarks

Most warnings are non-fatal i.e. processing will continue.

See also


View event

Provides detailed information on files within a .ZIP archive (called once per file)

Syntax

Private Sub object_View(FilePath As String, FileName As String, OriginalSize As Long, CompressedSize As Long, Ratio As Integer, Date As String, Time As String, Attributes As Integer, CompressionMethod As Integer, IsEncrypted As Boolean,  CRC32 As Long, FileType As Boolean, VersionCreatedBy As Single, VersionNeeded As Single)

The View event syntax has these parts

object	an Object Expression that evaluates to an addZIP or addUNZIP object

FilePath	the stored directory of FileName (where it is included), NULL otherwise

FileName	the name of the file

OriginalSize	the uncompressed size of the file

CompressedSize	the compressed size of the file

Ratio	the percentage compression achieved

Date	the original date stamp of the file (in CCYY-MM-DD format)

Time	the original time stamp of the file (in HH:MM:SS format)

Attributes	the original attributes of the file (if stored)

CompressionMethod	an value that represents one of the following compression methods

azCM_NONE (0x00) - the file is stored without compression

azCM_SHRUNK (0x0a) - the file was compressed with an older version of PKZIP

azCM_REDUCED_1 (0x14) - the file was compressed with an older version of PKZIP

azCM_REDUCED_2 (0x1e) - the file was compressed with an older version of PKZIP

azCM_REDUCED_3 (0x28) - the file was compressed with an older version of PKZIP

azCM_REDUCED_4 (0x32) - the file was compressed with an older version of PKZIP

azCM_IMPLODED (0x3c) - the file was compressed with an older version of PKZIP

azCM_TOKENISED (0x46) - the file was compressed with an older version of PKZIP

azCM_DEFLATED_NORMAL (0x50) - the file was compressed with addZIP (or compatible program)

azCM_DEFLATED_MAXIMUM (0x51) - the file was compressed with addZIP (or compatible program)

azCM_DEFLATED_FAST (0x52) - the file was compressed with addZIP (or compatible program)

azCM_DEFLATED_SUPERFAST (0x53) - the file was compressed with addZIP (or compatible program)

azCM_UNKNOWN (0xff) - the file is compressed with an unknown compression method. You will not be able to extract this file with the current version of the libraries.

IsEncrypted	true if file is encrypted, false otherwise

CRC32	the Circular Redundancy Check value

FileType	true if the file is a binary file, false if the file is a test file

VersionCreatedBy	the version of PKZIP that created the .ZIP archive

VersionNeeded	the minimum version of PKUNZIP required to unzip this file

Remarks


Zipped event

Occurs when a file has been compressed

Syntax

Private Sub object_Zipped(File As String, OriginalSize As Long, CompressedSize As Long, Percentage As Integer, TotalFiles As Integer, ProcessedFiles As Integer, TotalBytes As Long, ProcessedBytes As Long)

The Zipped event syntax has these parts

object	an Object Expression that evaluates to an addZIP object

File	the name of the zipped file

OriginalSize	the original i.e. uncompressed size of the file

CompressedSize	   the number of bytes that the file has been compressed to

Percentage	the percentage compression achieved

TotalFiles	the total number of files to compress

ProcessedFiles	the number of files that have been compressed

TotalBytes	the total number of bytes to compress

ProcessedBytes	the number of bytes that have been compressed

Remarks


Zipping event

Occurs during the compression of a file

Syntax

Private Sub object_Zipping(File As String, OriginalSize As Long, CompressedSize As Long, Percentage As Integer, TotalFiles As Integer, ProcessedFiles As Integer, TotalBytes As Long, ProcessedBytes As Long)

The Zipping event syntax has these parts

object	an Object Expression that evaluates to an addZIP object

File	the name of the file being compressed

OriginalSize	the original i.e. uncompressed size of the file

BytesRead	   the number of bytes read from the file

Percentage	the percentage of the file compressed so far

TotalFiles	the total number of files to compress

ProcessedFiles	the number of files that have been compressed

TotalBytes	the total number of bytes to compress

ProcessedBytes	the number of bytes that have been compressed

Remarks


ZipError event

When an error occurs during the compression, a ZipError event will occur.

Syntax

Private Sub object_ZipError(File As String, Number As Integer, Message As String)

The ZipError event syntax has these parts

object	an Object Expression that evaluates to an addZIP object

File	the name of the file being processed

Number	the number of the error

Message	reserved for future use

Remarks

Most errors are fatal i.e. processing will stop


ZipWarning event

When an warning occurs during the compression, a ZipWarning event will occur.

Syntax

Private Sub object_ZipWarning(File As String, Number As Integer, Message As String)

The ZipWarning event syntax has these parts

object	an Object Expression that evaluates to an addZIP object

File	the name of the file being processed

Number	the number of the warning

Message	reserved for future use

Remarks

Most warnings are non-fatal i.e. processing will continue.

See also


Warnings and errors

All warnings and error codes will be passed as notification messages as defined under How do I get feedback from the addZIP libraries? I have tried to keep the codes the same as those generated by PKZIP/PKUNZIP - registered users of PKZIP should refer to the documentation provided with that excellent software if my descriptions are unclear. I have also provided GetLastError and GetLastWarning functions to enable the developer to retrieve feedback indirectly (please refer to the function definitions for more information).

addZIP() Errors

1	cannot create .ZIP archive

2	.ZIP archive is corrupted, or file is not a .ZIP archive

4	out of memory

5	internal error - please contact the author

12	no files found, nothing to do

13	cannot locate list file/.ZIP archive or it is empty

14	the disk is full

15	the .ZIP archive is read-only, couldnt gain write access

16	illegal combination of function calls

17	too many files

18	couldnt open file, another user has it locked open

27	non-removable drive specified for disk-spanning

50	.ZIP archive left as

255	user aborted processing

addZIP() Warnings

2	cannot open specified file for compressing

3	cannot delete specified file - user does not have correct permissions

50	file left as specified/would be truncated if FIXED

addUNZIP() Errors

1,2,3	.ZIP archive is corrupted, or file is not a .ZIP archive

4	out of memory

9	cannot locate .ZIP archive or it is empty/cannot find list file

10	cannot open .ZIP archive

11	no files found, nothing to do

50	the disk is full

51	unexpected end of file

101	multi-disk archive (not supported)

255	user aborted processing

addUNZIP() Warnings

1,3	file has a bad table and cannot be extracted

4	.ZIP archive contains an error (needs PKZIPFIXing)

5	out of memory

8	cannot open .ZIP archive

9	cannot create file being extracted

10	invalid filename

11	unknown compression method

12	file is encrypted (and no password has been given)

13	file has an inconsistent local header

14	file is encrypted and incorrect password has been given

15	file has an incorrect CRC value

19	file is invalid and cannot be extracted

21,23	file has a bad table and cannot be extracted

24	a later version of extract software is required

25	file contains a comment that is too big - comment will be truncated

26	.ZIP archive has at least one error


License

Unregistered users should read the general and shareware licenses, registered users should read the general license and the relevant user license. By using the software, you indicate your agreement to the relevant license terms.

General license

The following apply to all users.

·	The addZIP Compression Libraries remain the property of the author at all times. By purchasing the software, you are purchasing a license to use the software not own it.

·	You may not reverse engineer, change or otherwise alter any part of the software (excluding the examples) without prior written permission from the author.

·	You may not produce and distribute in any way, a derived software product that may, directly or indirectly, compete with this software without prior written permission from the author.

·	This software is provided as-is, and no warranty of any kind (including, but not limited to, warranty for a particular purpose) is expressed or implied. The author will not be liable for any damage, data loss etc. caused by this program.

Shareware license

If you are not a registered user, the following apply to you in addition to the terms of the general license.

·	This is not free software. You may evaluate this software for a period of 30 days, after which you must register or delete the software from your hard disk. Use of this software beyond the 30 day evaluation period is expressly prohibited and violates national and international copyright law.

·	You must not distribute (free or otherwise) any software which uses the addZIP Compression Libraries without first registering this software.

·	You must not distribute any self-extracting archives built with the addZIP Compression Libraries.

Private user license

If you are registered for private use only, the following apply as additions to the general license.

·	The software is for your own personal use and may be used on one PC only.

·	You must not disclose, distribute or make known to any other user your registration number.

·	You may not distribute (free or otherwise) any software which uses the addZIP Compression Libraries without first upgrading to a Developer license.

·	You may upgrade to a developer/open license by paying for the difference between your current license and the developer/open license.

Developer/Open license

If you are registered for developer use, the following apply as additions to the general license.

·	You may use this software on one PC only (unless an open license has been purchased).

·	You must not disclose, distribute or make known to any other user your registration number.

·	You may distribute any software which uses the addZIP Compression Libraries as long as it does not contravene any part of this license.

·	You inform the author of any (commercial or otherwise) distributed software (if possible).

·	You may upgrade your developer license by paying the difference between your current license and the open license.


Registration

Please read the following carefully - especially note the text displayed in red.

When registering please provide the following information (where applicable); name, company, address, email address and registered user name. I would also be interested in what development environment(s) you are using and on what platform(s).

Your registration begins immediately, your registration number will be sent at a later date. (I am working hard on the next release of the libraries so there may be a short delay - please contact me if this is a problem). Irrespective of which registration method you use, please email me with your registered user name - failure to do so will delay the delivery of your registration code.

Registration brings the following benefits

·	free upgrades to all later versions of the libraries

·	a registration number that allows files within an archive to be encrypted/decrypted with your own password and customises any SFX archives built.

·	the right to distribute programs which make use of the addZIP Compression Libraries (developer and open licensees only)

·	the right to distribute self-extracting archives (when available)

There are three levels of registration

·	private user license. This is for the individual programmer who would like to use this software in his/her own programs but will not be distributing those same programs. The cost of this license is 30 UK pounds (50 US dollars).

·	developer license. This is for the individual programmer who will distribute programs that incorporate the addZIP libraries. The cost of this license is 50 UK pounds (80 US dollars).

·	open license. This is for companies where the addZIP libraries will be used by more than one programmer. There is no limit on the number of users. The cost of this license is 100 UK pounds (160 US dollars).

(N.B. To upgrade a license means only paying the difference between your current license and the new license required.)

Please select your preferred method of registration

Sterling cheque drawn on a UK bank

Non-sterling cheque drawn on a non-UK bank

Credit card via the Internet

Credit card via telephone

Credit card via fax

Credit card via email

Bank transfer

Money

When registering please provide the following information (where applicable); name, company, address, email address and registered user name. Your registration begins immediately, your registration number will be sent at a later date. (I am working hard on the next release of the libraries so there may be a short delay - please contact me if this is a problem). Irrespective of which registration method you use, please email me with your registered user name - failure to do so may delay the delivery of your registration code.


Sterling cheque drawn on a UK bank

The preferred method of registration is a sterling cheque which must be drawn on a UK bank. Non-UK residents can obtain such a cheque (for a small charge) from any branch of Thomas Cook travel agents. Cheques should be made payable to Stephen Darlington and sent to the address in Contacting the author.


Non-sterling cheque drawn on a non-UK bank

Whilst a sterling cheque is preferable, foreign cheques are also accepted. However to cover the cost of getting these cheques cashed please add 10% to the cost of the license. Make all cheques payable to Stephen Darlington and sent to the address in Contacting the author.


Credit card via the Internet

There are two registration points on the Internet - PsL and ShareIt! Both registration services offer secure registration and can be reached through the addZIP web site.

ShareIt! can be reached at http://www.shareit.com/programs/102600.htm or alternatively from the ShareIt! homepage with product code 102600. The site is available in both English and German.

PsL can be reached at https://www.pslweb.com/cgi-win/psl_ords.exe/ITEM15056 or alteratively from the the PsL homepage with product code 102600.

Both registration services support secure transactions.

NOTE: 10% surcharge will be added to the cost of registration for all credit card purchases (to offset charges from the registration services)


Credit card via telephone

US/Canadian users are advised to use the PsL registration service. European users are advised to use the Germany-based ShareIt! registration service. Other users can use either of the two services.

ShareIt! can be contacted on +49-221-2407279 (or in the US on 1-800-903-4152). The product code 102600 must be mentioned when ordering.

PsL can be reached on 800-242-4775 or 713-524-6394 - please ask for extension 15056.

NOTE: 10% surcharge will be added to the cost of registration for all credit card purchases (to offset charges from the registration services)


Credit card via fax

US/Canadian users are advised to use the PsL registration service. European users are advised to use the Germany-based ShareIt! registration service. Other users can use either of the two services.

ShareIt! can be faxed on +49-221-2407278. The product code 102600 must be mentioned when ordering.

PsL can be faxed on 713-524-6398 - please state the number 15056 clearly.

NOTE: 10% surcharge will be added to the cost of registration for all credit card purchases (to offset charges from the registration services)


Credit card via email


Bank transfer

Your bank will require the following information

Bank : 	Nationwide, 63 High Street, Sutton, Surrey SM11HR, UK

Sort code : 	07-01-16

A/c # : 	26285805

A/c name : 	Stephen Joseph Darlington

Please note that my bank charges me for bank transfers - please add 20 UK pounds to cover the cost of these fees.


Money

Money may be sent through the post, but always send money via registered post. All denominations are accepted but please contact me first.


Distribution

You are actively encouraged to distribute this software amongst your friends and colleagues, upload it your favourite BBS, shareware library and ftp/WWW sites, and include it in diskette and CD-ROM software collections, provided the following conditions are met

•	you distribute the exact, unmodified archive

•	you do not charge for this software (apart from a modest handling fee when applicable)

•	you make it clear that this software is marketed as shareware (on a try before you buy basis)

•	you inform the author of your actions

If you are unsure about this distribution policy, or wish to discuss any distribution channel not specifically mentioned, please feel free to contact the author.


Contacting the author

Please contact the author with your suggestions, bug reports etc. via one of the following contact points:

E-mail:	sdarlington@bigfoot.com

Telephone: 	UK 0181-407-1684 (evening only, answerphone during the day)

Fax: 	UK 0181-668-7472

Address:	Stephen Darlington

50 Haydn Avenue

Purley

Surrey

CR8 4AE

United Kingdom


Acknowledgements

All product names mentioned in the addZIP Compression Libraries Help are trademarks or registered trademarks of their registered owners.

This software would not be where it is today without the help of far to many people to mention them all. However the following are given special thanks

PKWARE, Inc. - for producing PKZIP - the best example of why shareware works

Steve Fulton - for providing a US contact point (and for some ALARMing insights)

Greg DeBacker - for his helpful patience in solving some difficult bugs

The African Chief - for supplying the code that enabled azip16.dll to work in Windows NT

Brad Clarke - for the Delphi translations of the sample programs

Info-ZIP - for producing the best 'internal documentation' of PKZIP and PKUNZIP. Although I have used very little code from the Info-ZIP libraries, I have borrowed many of their ideas, so I think it only fair to state the following

addZIP Compression Libraries incorporates compression code by the Info-ZIP group. There are no extra charges or costs due to the use of this code, and the original compression sources are freely available from CompuServe in the IBMPRO forum and by anonymous ftp from the Internet site ftp.uu.net:/pub/archiving/zip. I will also, upon request, mail you the full sources on a 3.5" MSDOS-format diskette for the cost of mailing.  Send 2 UK pounds to the address in Contacting the Author.


Questionnaire

I would be very grateful if you could email me the answers to the following questions

1) How did you find out about the libraries?

2) Where did you get this copy of the libraries?

3) What do like most about the libraries?

4) What do you dislike about the libraries?

5) What features would you like to see implemented in a future release?

6) What development environment are you using?

7) What platform are you developing on?


Release History

v0.71 - 1st January 1999

•	Documented all memory compression/decompression functions

•	Fixed problems with using UNC paths on Windows 95, 98 and NT

•	Fixed incompatibilties between static libraries azip32.lib and aunzip32.lib

•	Corrected filename matching during unzipping to allow single file extraction (previously all files had to be extracted).

•	Removed resources from static libraries

•	Changed base address of 32-bit DLLs and ActiveX libraries to avoid conflicts

•	Fixed missed events in ActiveX controls

•	Fixed problems with creating spanned .ZIP archives in a subdirectory

•	Added ShareIt! registration information

•	Removed CompuServe registration information

v0.7 - 1st September 1998

•	First official release of the addZIP Custom Controls

•	Removed addINMEMORY libraries - these are no longer distributed or supported. The equivalent functionality is available within the addZIP and addUNZIP libraries.

•	Corrected archive so that a single disk spanned archive is recognised by PKUNZIP as a normal .ZIP file

•	Fixed directory deleting bug that only shows up in Windows NT

•	Fixed bug that meant that partially extracted files were created if processing is halted due to Abort command or error condition

•	AM_UNZIPPED message now sent after file attributes/date and time have been correctly set

v0.69d - 1st March 1998

•	Added ability to store empty directories as entries in the ZIP archive (see addZIP_IncludeEmptyDirectoryEntries)

•	Added extended callback functions to allow passing of an application defined value (see addZIP_InstallCallbackEx and addUNZIP_InstallCallbackEx)

•	Fixed problem with files left open when addZIP_Abort or addUNZIP_Abort was called

•	Fixed SFX so that encrypted archives can be decrypted

•	Fixed addZIP_Update so that ZIP archive will be created if it doesnt previously exist

v0.69c - 1st February 1998

•	Fixed addZIP_ClearAttributes function that didnt work

•	Change in functionality. When unzipping, if you include a file-spec without a path, that file-spec will ignore any stored path information when matching. If a path is included, that path will be used in the matching process.

•	Fixed AM_UNZIPPING and AM_UNZIPPED parameters

v0.69b - 10th January 1998

•	Added correct 16-bit compression library that was missing from the previous release.

v0.69a - 1st January 1998

•	Traded DLL size for an increase in zipping/unzipping speed

•	Added more information to the AM_ZIPPING/AM_ZIPPED and AM_UNZIPPING/AM_UNZIPPED messages

•	Removed afx32.dll's dependency on bc453rtl.dll

•	Fixed non-deletion of directories

•	Fixed pattern matching routine

•	Fixed disk labelling problem with AZIP16.DLL and Windows 95/Windows NT

•	Fixed minor bugs

v0.69 - 11th November 1997

•	Included addZIP_Move function

•	Included addZIP_SFXAutoExecute and addZIP_SFXAutoPasswordPrompt

•	Included addZIP_SpanSizes and addZIP_SpandCreateImages

•	Completely redesigned the addZIP home page

•	Added How do I report a bug? to helpfile

v0.66 - 7th October 1997

•	Corrected problem with loading azip32.dll under Windows 95

v0.65 update- 30th August 1997

•	Included rebuilt import libraries for Visual C++

v0.65 - 1st August 1997

•	Included self-extracting archive creation function (for testing purposes).

•	Documented addZIP_GetVersion and addUNZIP_GetVersion.

•	Included addZIP_Abort and addUNZIP_Abort functions.

•	Corrected azip16.dll so that it now runs on Windows NT.

•	Updated help file and VB samples.

•	Minor bug fixes

v0.61 - 16th June 1997

•	Corrected bug that appeared when running azip16.dll under Windows NT.

•	Added addZIP_GetVersion and addUNZIP_GetVersion (to be fully documented in version 0.7).

•	Corrected minor errors in help file.

v0.6 - 3rd June 1997

•	Included callback functionality.

•	Extended the filtering functions to include file attributes and last accessed date and time..

•	Added addZIP_Initialise and addUNZIP_Initialise functions.

•	Re-structured notification messages.


Coming Soon
In the pipeline for future versions of the addZIP Compression Libraries are

•	Improved ActiveX custom controls. All the missing functionality missing from the controls will be added in a future release.

•	Extended SFX options. As well as a DOS 32-bit SFX option, there will also be a Windows SFX option.

•	Improved speed. Whilst the libraries are under development, speed has taken a back seat. Look for improved speed in future releases

•	Enhanced compression. I am considering the feasibility of adding a further compression method to that already implemented. This will increase the compression achievable, but will not be compatible with PKZIP.

•	Enhanced encryption. Given that the native encryption is relatively weak, I am proposing to include a much stronger encryption method (probably Blowfish) alongside the default. Like the enhanced compression (see above), this will not be compatible with PKZIP.


Whats New?
Version 0.71 adds

•	documented memory compression functions (to replace the separate memory compression library)

•	UNC bug fixes

•	new registration incentive

Now available

•	Online ShareIt! registration

•	the addZIP homepage

http://welcome.to/addZIP


Read Me First

These libraries are distributed using the shareware distribution model. This allows you to test the full functionality of my software prior to purchasing a license. As an incentive for you to register, and to inhibit the illegal use of this software, a registration reminder message may appear during the use of the software. This will appear in two different ways. If you are using the ActiveX components, this message will appear everytime you load your software that uses my components. If you are using the DLL or LIB components, this message will appear every 10th call (on average) to the main addZIP() and addUNZIP() functions. Neither of these messages will inhibit your evaluation of the libraries.

On purchasing a license to use the addZIP Compression Libraries, you will be provided with a registration code that will prevent the reminder messages from appearing.