Blog Entry Updated (09/30/2006 7:00 PM): Corrected the signature and documentation for the UnzipQuick function. Added links that were missing.
Blog Entry Updated (09/30/2006 9:00 PM): Corrected documentation regarding ignore path(s) parameters - Thanks Sergey Berezniker.
Blog Entry Updated (10/01/2006 9:36 PM): Added documentation regarding new UnzipAFileInfo and UnzipAFileInfoByIndex functions - Thanks Bo Durban.
Blog Entry Updated (10/02/2006 12:27 AM): Corrected the signature for UnzipAFileInfo function. - Thanks Malcolm Greene.
Blog Entry Updated (10/15/2006 7:25 AM): Modified Example #6 to show alternate syntax.
VFPCompression Library
I debuted the VFPCompression FLL in my previous blog entry and here I am going to provide an updated copy of it along with the documentation. One of the things that I added to this FLL that might be of particular interest is the ability to compress and uncompress strings (think xml, client-server, and/or memo files near 2GB range). This FLL was made possible by the Zlib compression Library and code found in an article out on Code Project. This FLL is provided freely to be used and abused in whatever manner you see fit, including in commercial applications. The only restriction I place on it is that you don't sue me or SweetPotato Software, Inc. for damages related to the use or abuse of this FLL. :)
Possible future features
- Progress callback - would report percentage complete to a user-defined VFP function
- Status callback - would report status of zip/unzip to a user-defined VFP function
- Cancel function - would allow developer to cancel zip/unzip at any point during a zip/unzip operation
- Self-extracting Zip - fully support the self-extracting zip format
- Encryption - Allow encrypted zips to be created and extracted
- Password Protect - support password protection for zip files
- Disk Spanning - support the ability to span multiple disks or otherwise split zip files into smaller portions (create and extract)
What you can do (if you want)
I would appreciate feedback regarding this FLL and bug reports when problems are encountered. I think that's a fair trade if you've found this FLL useful and it will help me improve it for the benefit of the entire VFP Community. Also, if you have any suggestions for improving this FLL (such as new features) please don't hesitate to post a comment here in this blog or send me an email.
That having been said, here is the updated download, sample VFP code, and the documentation for the FLL...
VFP Compression Update:
VFPCompression FLL Download (33 KB approx.)
VFP Compression Sample Code:
*!* Example 1
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFileQuick("C:\MyFile.txt")
SET LIBRARY TO
*!* Example 2
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFolderQuick("C:\MyFolder")
SET LIBRARY TO
*!* Example 3
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?UnzipQuick("C:\MyFile.zip", "C:\")
?UnzipQuick("C:\MyFolder.zip", "C:\")
SET LIBRARY TO
*!* Example 4
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("C:\MyZipFile.zip", "C:\", .F.)
?ZipFile("C:\SomeFile.txt", .F.)
?ZipClose()
SET LIBRARY TO
*!* Example 5
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?UnzipQuick("C:\MyZipFile.zip","C:\",.F.)
SET LIBRARY TO
*!* Example 6
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("C:\MyZipFile.zip")
*!* ?ZipOpen("MyZipFile.zip", "C:\", .F.)
?ZipFolder("C:\MyFolder", .F.)
?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
VFP Compression Documenation:
Function ZipString()
Signature: ZipString(cString[, nLevel])
Parameters:
cString - The character string you wish to compress
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:
Character Data - the compressed version of cString.
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()
Signature: ZipFileQuick(cFileName)
Parameters:
cFileName - The fully qualified file name (full path) of the file you wish to have compressed.
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()
Signature: ZipFileQuick(cFolderName)
Parameters:
cFolderName - The full path to the folder you wish to have zipped.
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
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:
Logical - returns .T. if successful or .F. if the operation has failed.
Remarks:
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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])
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.
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
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.
Function ZipFileRelative()
Signature: ZipFileRelative(cFileName[,cRelativePath])
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.
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
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.
Function ZipFolder()
Signature: ZipFolder(cFolderName[,lIgnorePaths])
Parameters:
cFolderName - The full path to the folder you wish to compress.
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.
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
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:
cString - The compressed string you wish to uncompress.
Return Value:
Character Data - the extracted version of cString.
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()
Signature: UnzipQuick(cZipFileName, cOutputFolderName[, lIgnorePaths])
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:
Logical - returns .T. if successful or .F. if the operation has failed.
Remarks:
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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()
Signature: Unzip()
Parameters: None
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
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()
Signature: UnzipTo(cOutputFolderName[, lIgnorePaths])
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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()
Signature: UnzipFile(cOutputFolderName[, lIgnorePaths])
Parameters:
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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.
Function UnzipByIndex()
Signature: UnzipByIndex(nIndex[, cOutputFolderName[,lIgnorePaths]])
Parameters:
nIndex - The index number of the file to be extracted.
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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.
Function UnzipFileCount()
Signature: UnzipFileCount()
Parameters: None
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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:
Logical - returns .T. if successful or .F. if the operation has failed.
Remarks:
UnzipGotoTopFile() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file. UnzipGotoTopFile() is used in conjunction with the UnzipFile function to extract a particular file from the zip. By using the cExtension optional parameter you can select the first record of a particular file type. 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.
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:
Logical - returns .T. if successful or .F. if the operation has failed.
Remarks:
UnzipGotoNextFile() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file. UnzipGotoNextFile() is used in conjunction with the UnzipFile function to extract a particular file from the zip. By using the cExtension optional parameter you can select the next record of a particular file type. 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.
Function UnzipGotoFileByName()
Signature: UnzipGotoFileByName(cFileName[, lIgnoreFilePath])
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:
Logical - returns .T. if successful or .F. if the operation has failed.
Remarks:
UnzipGotoFileByName() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file by file name and/or relative path. UnzipGotoFileByName() is used in conjunction with the UnzipFile function to extract a particular file from the open zip file. 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.
Function UnzipGotoFileByIndex()
Signature: UnzipGotoFileByIndex([nIndex])
Parameters:
nIndex - The index number of the file to be selected.
Return Value:
Logical - returns .T. if successful or .F. if the operation has failed.
Remarks:
UnzipGotoFileByIndex() is used between calls to UnzipOpen() and UnzipClose() to select a particular file by the position it physically holds in the contents of the open zip file. UnzipGotoFileByIndex() is used in conjunction with the UnzipFile function to extract a particular file from the zip file contents. 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.
Function UnzipAFileInfoByIndex()
Signature: UnzipAFileInfoByIndex(cArrayName, nIndex)
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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:
| Row |
Array Content |
Data Type |
| 1 |
File Name |
Character |
| 2 |
Comment |
Character |
| 3 |
Version |
Numeric |
| 4 |
Version Needed |
Numeric |
| 5 |
Flags |
Numeric |
| 6 |
Compression Method |
Numeric |
| 7 |
DOS Date |
Datetime |
| 8 |
CRC |
Numeric |
| 9 |
Compressed Size |
Numeric |
| 10 |
Uncompressed Size |
Numeric |
| 11 |
Internal Attribute |
Numeric |
| 12 |
External Attribute |
Numeric |
| 13 |
Folder |
Logical |
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:
Logical - returns .T. if successful or .F. if the operation has failed.
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:
| Row |
Array Content |
Data Type |
| 1 |
File Name |
Character |
| 2 |
Comment |
Character |
| 3 |
Version |
Numeric |
| 4 |
Version Needed |
Numeric |
| 5 |
Flags |
Numeric |
| 6 |
Compression Method |
Numeric |
| 7 |
DOS Date |
Datetime |
| 8 |
CRC |
Numeric |
| 9 |
Compressed Size |
Numeric |
| 10 |
Uncompressed Size |
Numeric |
| 11 |
Internal Attribute |
Numeric |
| 12 |
External Attribute |
Numeric |
| 13 |
Folder |
Logical |
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.