Chip 1998 March

home *** CD-ROM | disk | FTP | other *** search

/ Chip 1998 March / Chip_1998-03_cd.bin / zkuste / delphi / komprese / zip / DELZIP12.ZIP / DOC.ZIP / USAGE.TXT < prev next >

Wrap

Text File | 1997-09-28 | 19KB | 367 lines

TZipMaster VCL by Eric W. Engler. v1.20 A Delphi/C++ Builder wrapper for my freeware ZIP and UNZIP DLLs. A VCL wrapper for my freeware ZIP and UNZIP DLLs. At run time, the DLL's: ZIPDLL.DLL and UNZDLL.DLL must be present on the hard disk - in C:\WINDOWS\SYSTEM or else in your application directory, or a directory in the PATH. These DLLs are based on the InfoZip Official Freeware Zip/Unzip source code, but they are NOT equivalent to InfoZip's DLLs. I have modified the InfoZip source code to enhance their ease-of-use, power, and flexibility for use with Delphi and C++ Builder. Please do NOT contact InfoZip for issues regarding this port. To obtain the official InfoZip source code, consult their Web site: http://www.cdrom.com/pub/infozip/ The five main methods that can be invoked are: add - add one or more files to a ZIP archive delete - delete one or more files from ZIP archive extract - expand one or more files from a ZIP archive list - transfer "table of contents" of ZIP archive to a StringList copyfile - copies a file "add" and "list" will also work on self-extracting ZIP archives having a file extension of ".EXE". Various properties exist to control the actions of the methods. Filespecs are specified in the FSpecArgs TStringList property, so you can easily combine many different filespecs into one Add, Delete, or Extract operation. For example: 1. Add entries directly to the FSpecArgs property: ZipMaster1.FSpecArgs.Add('C:\AUTOEXEC.BAT'); ZipMaster1.FSpecArgs.Add('C:\DELPHI\BIN\DELPHI.EXE'); ZipMaster1.FSpecArgs.Add('C:\WINDOWS\*.INI'); 2. Take the filespecs from a StringList, just assign them all over to ZipMaster1. ZipMaster1.FSpecArgs.Assign(StringList1); 3. Take the filespecs from a ListBox, just assign them all over to ZipMaster1. ZipMaster1.FSpecArgs.Assign(ListBox1.Items); You can specify either the MS-DOS backslash path symbol, or the one normally used by PKZIP (the Unix path separator: /). They are treated exactly the same. All of your FSpecArgs accept MS-DOS wildcards. Add, Delete, and Extract are the only methods that use FSpecArgs. The List method doesn't - it just lists all files. Following is a list of all TZipMaster properties, events and methods: Properties ========== Verbose Boolean If True, ask for the maximum amount of "possibly important" information from the DLLs. The informational messages are delivered to your program via the OnMessage event, and the ErrCode and Message properties. This is primarily used to determine how much info you want to show your "end-users" - developers can use the Trace property to get additional infomation. Trace Boolean Similar to Verbose, except that this one is aimed at developers. It lets you trace the execution of the C code in the DLLs. Helps you locate possible bugs in the DLLs, and helps you understand why something is happening a certain way. ErrCode Integer Holds a copy of the last error code sent to your program by from DLL. 0=no error. See the OnMessage event. Most messages from the DLLs will have an ErrCode of 0. Message String Holds a copy of the last message sent to your program by the DLL. See the OnMessage event. ZipContents TList Read-only TList that contains the directory of the archive specified in the ZipFileName property. Every entry in the list points to a ZipDirEntry record. This is automatically filled with data whenever an assignment is made to ZipFileName, and can be manually filled by calling the List method. For your convenience, this VCL hides the TList memory allocation issues from you. Automatic updates to this list occur whenever this VCL changes the ZIP file. Event OnDirUpdate is triggered for you each time this list is updated - that is your queue to refresh your directory display. --------------------------------------------------------------------- Each entry in the ZipContents TList is a ZipDirEntry record: ZipDirEntry = packed Record Version : WORD; Flag : WORD; CompressionMethod : WORD; DateTime : Longint; { Time: Word; Date: Word; } CRC32 : Longint; CompressedSize : Longint; UncompressedSize : Longint; FileNameLength : WORD; ExtraFieldLength : WORD; FileName : String; end; To get compression ratio: (code from Almer Tigelaar, tigelaar@tref.nl) var ratio: Integer; begin with ZipDirEntry1 do ratio:=Round((1-(CompressedSize/UnCompressedSize))*100); --------------------------------------------------------------------- Cancel Boolean If you set this to True, it will abort any Add or Extract processing now underway. There may be a slight delay before the abort will take place. Note that a ZIP file can be corrupted if an Add operation is aborted. ZipBusy Boolean If True, a ZIP operation is underway - you must delay your next Add/Delete operation until this is False. You won't need to be concerned about this in most applications. This can be used to syncronize Zip operations in a multi-threaded program. UnzBusy Boolean If True, an UNZIP operation is underway - you must delay your next Extract operation until this is False. You won't need to be concerned about this in most applications. This can be used to syncronize UnZip operations in a multi-threaded program. AddCompLevel Integer Compression Level. Range 0 - 9, where 9 is the tightest compression. 2 or 3 is a good trade-off if you need more speed. Level 0 will just store files without compression. I recommend leaving this at 9 in most cases. AddOptions Set This property is used to modify the default action of the Add method. This is a SET of options. If you want an option to be True, you need to add it to the set. This is consistant with the way Delphi deals with "options" properties in general. AddDirNames If True, saves the pathname with each fname. Drive IDs are never stored in ZIP file directories. NOTE: the root directory name is never stored in a pathname; in other words, the first character of a pathname stored in the zip file's directory will never be a slash. AddForceDOS If True, force all filenames that go into the ZIP file to meet the DOS 8x3 restriction. If false, long filenames are supported. WARNING: name conflicts can occur if 2 long filenames reduce to the same 8x3 filename! AddZipTime If True, set ZIP timestamp to that of the newest file in the archive. AddRecurseDirs If True, subdirectories below EACH given fspec will be included in the fspec. Defaults to False. This is potentially dangerous if the user does this from the root directory (his hard drive may fill up with a huge zip file)! AddHiddenFiles If True, files with their Hidden or System attributes set will be included in the Add operation. NOTE: You can not have more than one of the following three options set to "True". If all three are False, then you get a standard "add": all files in the fspecs will be added to the archive regardless of their date/time stamp. This is also the default. AddMove If True, after adding to archive, delete orig file. Potentially dangerous. Use with caution! NOTE: Freshen and Update can only work on pre-existing archives. Update can add new files to the archive, but can't create a new archive. AddFreshen If True, add newer files to archive (only for files that are already in the archive). AddUpdate If True, add newer files to archive (but, any file in an fspec that isn't already in the archive will also be added). ExtrBaseDir String This base directory applies only to "Extract" operations. The UNZIP DLL will "CD" to this directory before extracting any files. If you don't specify a value for this property, then the directory of the ZipFile itself will be the base directory for extractions. ExtrOptions set This property is used to modify the default action of the Extract method. This is a SET of options. If you want an option to be True, you need to add it to the set. ExtrDirNames If True, extracts and recreates the relative pathname that may have been stored with each file. Empty dirs stored in the archive (if any) will also be recreated. ExtrOverWrite If True, overwrite any pre-existing files during Extraction. ExtrFreshen If True, extract newer files from archive (only for files that already exist). Won't extract any file that isn't already present. ExtrUpdate If True, extract newer files from archive (but, also extract files that don't already exist). FSpecArgs TStrings Stringlist containing all the filespecs used as arguments for Add, Delete, or Extract methods. Every entry can contain MS-DOS wildcards. If you give filenames without pathnames, or if you use relative pathnames with filenames, then the base drive/directory is assumed to be that of the Zipfile. ZipFileName String Pathname of a ZIP archive file. If the file doesn't already exist, you will only be able to use the Add method. I recommend using a fully qualified pathname in this property, unless your program can always ensure that a known directory will be the "current" directory. Count Integer Number of files now in the Zip file. Updated automatically, or manually via the List method. SuccessCnt Integer Number of files that were successfully operated on (within the current ZIP file). You can read this after every Add, Delete, and Extract operation. ZipVers Integer The version number of the ZIPDLL.DLL. For example, 110 = version 1.10. UnzVers Integer The version number of the UNZDLL.DLL. For example, 110 = version 1.10. Events ====== OnDirUpdate Occurs immed. after this VCL refreshes it's TZipContents TList. This is your queue to update the screen with the new contents. OnProgress Occurs during compression and decompression. Intended for "status bar" or "progress bar" updates. Criteria for this event: - starting to process a new file (gives you the filename and total uncompressed filesize) - every 32K bytes while processing - completed processing on a batch of files See Demo1 to learn how to use this event. OnMessage Occurs when the DLL sends your program a message. The Message argument passed by this event will contain the message. If an error code accompanies the message, it will be in the ErrCode argument. The Verbose and Trace properties have a direct influence on how many OnMessage events you'll get. See Also: Message and ErrCode properties. Methods ======= Add Adds all files specified in the FSpecArgs property into the archive specified by the ZipFileName property. Files that are already compressed will not be compressed again, but will be stored "as is" in the archive. This applies to .GIF, .ZIP, .LZH, etc. files. Note that .JPG files WILL be compressed, since they can still be squeezed down in size by a notable margin. Extract Extracts all files specified in the FSpecArgs property from the archive specified by the ZipFilename property. If you don't specify any FSpecArgs, then all files will be extracted. Delete Deletes all files specified in the FSpecArgs property from the archive specified by the ZipFilename property. List Refreshes the contents of the archive into the ZipContents TList property. This is a manual "refresh" of the "Table of Contents". CopyFile This copies any file to any other file. Useful in many application programs, so it was included here as a method. This returns 0 on success, or else one of these errors: -1 error in open of outfile -2 read or write error during copy -3 error in open of infile -4 error setting date/time of outfile Can be used to make a backup copy of the ZipFile before an Add operation. Sample Usage: with ZipMaster1 do begin ret=CopyFile(ZipFileName, 'C:\TMP$$.ZIP'); if ret < 0 then ShowMessage('Error making backup'); end; IMPORTANT note regarding CopyFile: The destination must include a filename (you can't copy fname.txt to C:\). Also, Wildcards are not allowed in either source or dest. -------------------------------------------------------------------- DLL Loading and Unloading This table show you which DLL is needed for each method: Add requires ZIPDLL.DLL Delete requires ZIPDLL.DLL Extract requires UNZDLL.DLL List none (internal code in this VCL) CopyFile none (internal code in this VCL) The following 4 methods give you explicit control over loading and unloading of the DLLs. For simplicity, you can do the loads in your form's OnCreate event handler, and do the unloads in your form's OnDestroy event handler. Load_Zip_Dll -- Loads ZIPDLL.DLL, if not already loaded Load_Unz_Dll -- Loads UNZDLL.DLL, if not already loaded Unload_Zip_Dll -- Unloads ZIPDLL.DLL Unload_Unz_Dll -- Unloads UNZDLL.DLL For compatibility with older programs, and because I'm a nice guy, I'll handle the loads and unloads automatically if your program doesn't do it. This can, however, incur a perfomance penalty because it will reload the needed DLL for each operation. Advanced developers will want to carefully consider their load and unload strategy so they minimize the number of loads, and keep the DLLs out of memory when they're not needed. There is a traditional speed vs. memory trade-off.