Vfpcompression Update - Fixes, Unc Pathing, and Callbacks
Vfpcompression Update - Fixes, Unc Pathing, and Callbacks
This update contains numerous fixes (unfortunately I didn't keep track, I just fixed anything and
everything anyone mentioned to me). The library now allows the use of UNC paths, and it also
contains a new callback/event feature that allows a user-defined function/procedure/method to be
hooked into the Zip and Unzip routines. In so doing the developer can monitor open, close, and
even the number of bytes being read or written as the zip functions are called (see ZipCallback in
the documentation below).
Here's the customary download link, some sample code for using the new callback feature and the
library in general, and the library documentation...
*****************************
FUNCTION MyCallback()
*****************************
*!* Variables below are created on the fly
*!* by the FLL when the ZipCallback feature is used
*!* Depends on the value of nZipEvent
?cZipObjectName && Name of Zip, File, or Folder being processed
*!* Events that fire MyCallback
*!* 0 = Open Zip
*!* 1 = Start Zip/Unzip of File
*!* 2 = Read/Write File (nZipBytes will contain value of bytes read for event)
*!* 3 - End Zip/Unzip of File
*!* 4 - Folder Opened
*!* 5 - Close Zip
?nZipEvent
*!* Number of Bytes read (Event 3)
?nZipBytes
ENDFUNC
*!* Example 1
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFileQuick("C:\MyFile.txt")
?ZipFileQuick("C:\MyFile.txt", "MyPassword")
SET LIBRARY TO
*!* Example 2
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFolderQuick("C:\MyFolder")
?ZipFolderQuick("C:\MyFolder2", .T., "MyPassword")
?ZipFolderQuick("C:\MyFolder2", .F., "MyPassword")
SET LIBRARY TO
*!* Example 3
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?UnzipQuick("C:\MyFile.zip", "C:\")
?UnzipQuick("C:\MyFolder.zip", "C:\", .T.)
?UnzipQuick("C:\MyFolder.zip", "C:\", .F., "MyPassword")
SET LIBRARY TO
*!* Example 4
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("MyZipFile.zip", "C:\", .F.)
?ZipFile("C:\SomeFile.txt", .F.)
?ZipFile("C:\AnotherFile.txt", .F., "MyPassword")
?ZipClose()
SET LIBRARY TO
*!* Example 5
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?UnzipQuick("C:\MyZipFile.zip","C:\",.F.)
?UnzipQuick("C:\MyZipFile.zip","C:\",.F., "MyPassword")
SET LIBRARY TO
*!* Example 6
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("C:\MyZipFile.zip")
*!* ?ZipOpen("MyZipFile.zip", "C:\", .F.)
?ZipFolder("C:\MyFolder\", .F.) && trailing backslash is optional
?ZipFolder("C:\AnotherFolder", .F., "MyPassword")
?ZipClose()
SET LIBRARY TO
*!* Example 7
SET LIBRARY TO LOCFILE("vfpcompression.fll")
CLEAR
lcOriginal = REPLICATE("Visual FoxPro Rocks!",100)
?"Original Length: " + TRANSFORM(LEN(lcOriginal))
?
lcCompressed = ZipString(lcOriginal)
?"Compressed: " + lcCompressed
?"Compressed Length: " + TRANSFORM(LEN(lcCompressed))
?
?"Length Savings: " + TRANSFORM(LEN(lcOriginal) - LEN(lcCompressed)) + " bytes"
?
lcUncompressed = UnzipString(lcCompressed)
*!* ?"Uncompressed: " + lcUncompressed
?"Uncompressed Length: " + TRANSFORM(LEN(lcUncompressed))
?"Equals Original: " + IIF(lcUncompressed == lcOriginal, "YES", "NO")
IF !(lcUncompressed == lcOriginal)
EXIT
ENDIF
SET LIBRARY TO
*!* Example 8
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("MyZip.zip", "C:\", .F.)
?ZipFile("C:\MyFile1.txt", .F., "MyPassword1") && passwords for files can be different
?ZipFile("C:\MyFile2.txt", .F., "MyPassword2") && passwords for files can be different
?ZipFile("C:\MyFile3.txt", .F.) && And some files can not be given a password
*!* could zip other files and folders here before close
?ZipClose()
SET LIBRARY TO
Function ZipString()
Parameters:
nLevel - The compression level to use which is 1 through 9 (1 is the fastest, while 9 is the best
compression). The default value for this parameter is 6.
Return Value:
Remarks:
This function is particularly useful in a client-server application given that strings of data (such as
memo fields, character fields, and xml) can be compressed before sending them across the network
and then extracted at the other end (using UnzipString).
Function ZipFileQuick()
Parameters:
cFileName - The fully qualified file name (full path) of the file you wish to have compressed.
cPassword - The password you wish to protect the zipped file with.
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
Remarks:
The zip file that this function creates will have the same file name as cFileName, with the extension
as ".zip".
Function ZipFolderQuick()
Parameters:
cFolderName - The full path to the folder you wish to have zipped.
cPassword - The password you wish to protect the zipped files with.
lIgnorePath - If you wish to ignore the relative path of the file into the zip file that is being created
you would pass .T. for this parameter. The default value for this parameter is .F. which means that
the relative path will be respected.
Return Value:
Remarks:
The zipfile that this function creates will have the same file name as cFolderName, with the
extension as ".zip".
Function ZipOpen()
Signature: ZipOpen(cZipFileName[,cFolderName[,lAppend]])
Parameters:
cZipFileName - The file name or full path of the zip file you wish to create.
cFolderName - The full path of the folder in which you want cZipFileName created.
lAppend - If the zip file you are compressing to exists you can choose to append to it by passing .T.
to this parameter. Defaults to .F..
Return Value:
ZipOpen() is used in conjunction with the matching ZipClose(). The usual series of function calls
would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using
ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.
Function ZipClose()
Signature: ZipClose()
Parameters: None
Return Value:
Remarks:
ZipClose() must be called after issuing a ZipOpen(). The usual series of function calls would consist
of creating/opening the zip file using ZipOpen, zipping files and/or folders using
ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.
Function ZipFile()
Signature: ZipFile(cFileName[,lIgnorePath[,cPassword]])
Parameters:
cFileName - The file name or full path of the file you wish to compress.
lIgnorePath - If you wish to ignore the relative path of the file into the zip file that is being created
you would pass .T. for this parameter. The default value for this parameter is .F. which means that
the relative path will be respected.
cPassword - The password you wish to protect the zipped file with.
Return Value:
Remarks:
ZipFile() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls would
consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using
ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.
The cPassword is usually the same for all files within a zip, however it does not
need to be the same. Different passwords can be specified for different files and
you can even selectively password protect files within the zip.
Function ZipFileRelative()
Parameters:
cFileName - The file name or full path of the file you wish to compress.
cRelativePath - The relative path you wish to have saved in the zip for this file. This allows you to
set up the structure (relative paths) in the zip different from the actual relative paths of the files you
are compressing.
cPassword - The password you wish to protect the zipped file with.
Return Value:
Remarks:
ZipFileRelative() is used between calls to ZipOpen() and ZipClose(). The usual series of function
calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using
ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.
The cPassword is usually the same for all files within a zip, however it does not need to be the
same. Different passwords can be specified for different files and you can even selectively
password protect files within the zip.
Function ZipFolder()
Parameters:
lIgnorePaths - If you wish to ignore the relative path of the folder into the zip file that is being
created you would pass .T. for this parameter. The default value for this parameter is .F. which
means that paths will be respected.
cPassword - The password you wish to protect the zipped file with.
Return Value:
Remarks:
ZipFolder() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls
would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using
ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.
Function UnzipString()
Signature: UnzipString(cString)
Parameters:
Return Value:
Remarks:
The string to be extracted must have been compressed with the ZipString() function or other
compression function that is compatible with the compress or compress2 functions in zlib.
Function UnzipQuick()
Parameters:
cZipFileName - The fully qualified file name (full path) of the zip file you wish to have extracted.
cOutputFolderName - The full path to the folder you wish to extract the contents of the zip to.
lIgnorePaths - If you wish to ignore the relative paths that are contained in the zip file you would
pass .T. for this parameter. The default value for this parameter is .F. which means that the relative
paths will be respected.
Return Value:
The file and folders in the zip file will be extracted into the same folder as the cZipFileName resides
in.
Function UnzipOpen()
Signature: UnzipOpen(cZipFileName)
Parameters:
cZipFileName - The file name or full path of the zip file you wish to uncompress.
Return Value:
Remarks:
UnzipOpen() is used in conjunction with the matching UnzipClose(). The usual series of function
calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders
using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.
Function UnzipClose()
Signature: UnzipClose()
Parameters: None
Return Value:
Remarks:
UnzipClose() must be called after issuing an UnzipOpen(). The usual series of function calls would
consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using
Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.
Function Unzip()
Parameters:
lIgnorePaths - If you wish to ignore the relative paths that are contained in the zip file you would
pass .T. for this parameter. The default value for this parameter is .F. which means that the relative
paths will be respected.
Return Value:
Remarks:
Unzip() is used between calls to UnzipOpen() and UnzipClose() to uncompress the entire zip file.
The files and folders contained in the zip file will be extracted to the same folder as the zip file
resides in unless a call to UnzipSetFolder() has been previously issued. The usual series of function
calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders
using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.
Function UnzipTo()
Parameters:
cOutputFolderName - The folder into which the zip file contents should be extracted.
lIgnorePaths - If you wish to ignore the relative paths that are contained in the zip file you would
pass .T. for this parameter. The default value for this parameter is .F. which means that the relative
paths will be respected.
Return Value:
Remarks:
UnzipTo() is used between calls to UnzipOpen() and UnzipClose(). The functionality of this is similar
to calling UnzipSetFolder() and then Unzip(). The usual series of function calls would consist of
opening the zip file using UnzipOpen, uncompressing files and/or folders using
Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.
Function UnzipFile()
cOutputFolderName - The folder into which the current file (cotained in the zip) should be extracted.
lIgnorePaths - If you wish to ignore the relative path of the current file you would pass .T. for this
parameter. The default value for this parameter is .F. which means that the relative path will be
respected.
Return Value:
Remarks:
UnzipFile() is used between calls to UnzipOpen() and UnzipClose() to extract the currently selected
file contained in the zip file. UnzipFile() is used in conjunction with the UnzipGotoTopFile,
UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions. You can think of
the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile,
UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer
and the UnzipFile function is used to extract the file that the record pointer is currently on.
The cPassword is usually the same for all files within a zip, however it does not need to be the
same. Just keep in mind that passwords can be specified for different files within a zip and when
you are unzipping such an archive you will need to change the cPassword accordingly.
Function UnzipByIndex()
Parameters:
cOutputFolderName - The folder into which the zip file contents should be extracted.
lIgnorePaths - If you wish to ignore the relative path for this file that is contained in the zip file you
would pass .T. for this parameter. The default value for this parameter is .F. which means that the
relative path will be respected.
Return Value:
Remarks:
UnzipByIndex() is used between calls to UnzipOpen() and UnzipClose() to extract a file by the
position (index) it holds in the zip file. UnzipByIndex() is used in conjunction with the UnzipFileCount
function. You can think of the contents of a zip file as records in a table. In this sense
UnzipFileCount would give you the record count for the table and the UnzipByIndex function be
used to extract a particular file by record number.
The cPassword is usually the same for all files within a zip, however it does not need to be the
same. Just keep in mind that passwords can be specified for different files within a zip and when
you are unzipping such an archive you will need to change the cPassword accordingly.
Function UnzipFileCount()
Signature: UnzipFileCount()
Parameters: None
Return Value:
Remarks:
UnzipFileCount() is used between calls to UnzipOpen() and UnzipClose() to retrieve the number of
files that are contained in the zip file. It does not actually extract anything. UnzipFileCount() is used
in conjunction with the UnzipByIndex function. You can think of the contents of a zip file as records
in a table. In this sense UnzipFileCount would give you the record count for the table and the
UnzipByIndex function be used to extract a particular file by record number.
Function UnzipSetFolder()
Signature: UnzipSetFolder(cOutputFolderName)
Parameters:
cOutputFolderName - The folder into which the zip file contents should be extracted.
Return Value:
Remarks:
UnzipSetFolder() is used between calls to UnzipOpen() and UnzipClose() to set the output folder for
extracted zip contents. It does not actually extract anything. The usual series of function calls would
consist of opening the zip file using UnzipOpen, calling UnzipSetFolder to set the output folder,
uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing
the zip file using UnzipClose.
Function UnzipGotoTopFile()
Signature: UnzipGotoTopFile([cExtension])
Parameters:
cExtension - The file extension to use as a filter for file type. All other file types will be ignored and
only the first file of the type specified will be selected in the zip file.
Return Value:
Remarks:
Function UnzipGotoNextFile()
Signature: UnzipGotoNextFile([cExtension])
Parameters:
cExtension - The file extension to use as a filter for file type. All other file types will be ignored and
only the next file of the type specified will be selected in the zip file.
Return Value:
Remarks:
Parameters:
cFileName - The file name of the file you wish to select in the zip file contents. You can specify a
relative path as well to narrow down the search.
lIgnoreFilePath - If you wish to just find a file of a particular name in the zip file you can pass .T. for
this parameter and the relative path of the file will be ignored. The first matching file of the name
specified in cFileName will be selected in the zip contents.
Return Value:
Remarks:
Function UnzipGotoFileByIndex()
Signature: UnzipGotoFileByIndex([nIndex])
Parameters:
Return Value:
Remarks:
Parameters:
cArrayName - Name of the VFP array to be created with file information in it.
nIndex - The index number of the file you want to return information about.
Return Value:
Creates an array with 13 rows (elements) in it. The rows contain various pieces of information
regarding the file that is held in the zip file at nIndex. The following table describes the contents and
data type of each row in the array:
Remarks:
The array that is created will have whatever name was specified by cArrayName. Should the array
already exist it will release it and recreate it. UnzipAFileInfoByIndex() is used between calls to
UnzipOpen() and UnzipClose() to show information about a particular file. The file is referred to by
the position it physically holds in the contents of the open zip file. You can think of the contents of a
zip file as records in a table. In this sense the UnzipAFileInfoByIndex function is used to refer to and
retrieve information about a particular record number in the zip file.
Function UnzipAFileInfo()
Signature: UnzipAFileInfo(cArrayName)
Parameters:
cArrayName - Name of the VFP array to be created with file information in it.
Return Value:
Creates an array with 13 rows (elements) in it. The rows contain various pieces of information
regarding the currently selected file in the zip. The following table describes the contents and data
type of each row in the array:
Remarks:
The array that is created will have whatever name was specified by cArrayName. Should the array
already exist it will release it and recreate it. UnzipAFileInfo() is used between calls to UnzipOpen()
and UnzipClose() to show information about a particular file. Use the UnzipAFileInfo function in
conjunction with UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and
UnzipGotoFileByIndex functions to return information regarding a particular file contained in the
open zip file. You can think of the contents of a zip file as records in a table. In this sense the
UnzipAFileInfo function is used to refer to and retrieve information about the record that the record
pointer is currently on within the zip file.
Function ZipCallback()
Signature: ZipCallback(cFunction)
Parameters:
cFunction - A string denoting a function, procedure, or method that you want fired whenever a zip
event occurs, such as "MyCallback()".
Events:
When one of the following zip events occurs the function/procedure/method specified by the
cFunction parameter will be called. cZipObjectName, nZipEvent, and nZipBytes are private
variables created on-the-fly by the FLL. They will contain the values specified in the table below.
Remarks:
Event handling is started as soon as you call ZipCallback and pass it the name of a function,
procedure, or object method. ZipCallback provides a way for you to hook into the internal events
happening inside of the VFPCompression FLL. nZipBytes reports the number of bytes currently
being read during zip (2048 bytes at a time) or written during unzip (4096 bytes at a time) of an
individual file. In order to turn off event handling simply call the ZipCallback with an empty length
string, such as ZipCallback("").