ID Number: Q75472
3.00
WINDOWS
Summary:
LZEXPAND.DLL is a dynamic-link library that provides functions to
read, expand, and copy both regular files and files compressed by the
Lempel-Ziv encoding program COMPRESS.EXE, provided with the Windows
version 3.0 Software Development Kit (SDK). This article documents
the services provided by LZEXPAND.DLL.
Note: This information applies ONLY to Windows version 3.0. The
services provided in the next version of Windows will have a different
interface.
More Information:
The LZInit, LZOpen, and LZClose functions perform necessary
housekeeping (and open and close files). The LZRead and LZSeek
functions can operate on both compressed and normal files. The
LZCopy function copies files and decompresses them if necessary.
The LZSeek, LZRead, and LZClose functions can determine if the
parameter passed in is a regular MS-DOS file handle or a
compressed-file-information structure identifier, and will act
appropriately. The LZOpenFile, LZSeek, LZRead, and LZClose
functions can be called as replacements for the OpenFile,
_llseek, _lread, and _lclose functions, respectively, without
regard to the compression state of the files.
A detailed explanation of the purpose, syntax, and parameters of each
LZEXPAND.DLL function is listed below:
LZCopy
------
Syntax: LONG LZCopy(doshSource, doshDest)
This function copies the source file to the destination file.
If the source file is compressed, it is decompressed as it is
copied.
Parameter Type/Description
--------- ----------------
doshSource int Specifies the MS-DOS file handle of the
source file. The source file may be either
compressed or uncompressed.
doshDest int Specifies the MS-DOS file handle of the
destination file. The destination file will be
an uncompressed file.
Return The return value is the number of bytes written to the
Value: destination file, or it is one of the LZERROR codes listed
below.
Code Description
---- -----------
LZERROR_BADINHANDLE (-1) Invalid input handle
LZERROR_BADOUTHANDLE (-2) Invalid output handle
LZERROR_READ (-3) Bad compressed file format
LZERROR_WRITE (-4) Out of space for output file
LZERROR_GLOBALLOC (-5) Insufficient memory for buffers
LZERROR_GLOBLOCK (-6) Bad global handle
Comment: The doshSource and doshDest parameters should be MS-DOS file
handles returned either by the Windows OpenFile function,
or by the MS-DOS open file functions (open, _dos_open, or
_lopen). If the files are opened with the LZOpenFile
function, the files will be copied properly; however, the
LZOpenFile call will allocate an unused
compressed-file-information structure for the compressed
source file.
Using the LZCopy function is the fastest way to copy a file
using LZEXPAND.
LZOpenFile
----------
Syntax: int LZOpenFile(lpFileName, lpReOpenBuf, wStyle)
This function opens a file using the OpenFile function. If
the file is opened in read-only mode and it is compressed,
the LZOpenFile function also calls the LZInit function to
allocate and initialize a compressed-file-information data
structure.
Parameter Type/Description
--------- ----------------
lpFileName LPSTR Points to a null-terminated character
string that names the file to open. The string
must contain characters from the ANSI
character set.
lpReOpenBuff LPOFSTRUCT Points to the OFSTRUCT data
structure to be used by the OpenFile
function (for more information, see pages 4-322
to 4-325 of the "Microsoft Windows Software
Development Kit Reference, volume 1").
wStyle WORD Specifies action to be taken by the
OpenFile function.
Return If the file is opened in any mode other than read-only
Value: or if the file is not compressed, the LZOpenFile function
returns the return value from the OpenFile function, an
MS-DOS file handle. If the file was opened in read-only mode
and it is compressed, the LZOpenFile function returns an
identifier for the compressed-file-information data structure
created by the LZInit function. If the file cannot be
opened, -1 is returned. If the file can be opened, however
the compressed-file-information data structure cannot be
allocated, then the file is closed, and -1 is returned.
Comment: Files that are compressed with COMPRESS.EXE have a special
header. The LZOpenFile function uses this header to
determine if the file is compressed.
LZInit
------
Syntax: int LZInit(doshSource)
This function allocates and initializes a compressed-file-
information data structure if it is passed a file handle for
a compressed file.
Parameter Type/Description
--------- ----------------
doshSource int Specifies the MS-DOS file handle returned
by the OpenFile, _lopen, or open
functions. The file should have been opened
read-only.
Return If the file is compressed, an identifier for a compressed
Value: file information structure is returned. If the file is not
compressed, the MS-DOS file handle is returned. If a read
error occurs while initializing the data structure, or if
there is insufficient heap space to allocate the structure,
-1 is returned.
Comment: Storage for the compressed file information structure is
allocated from the global heap.
LZSeek
------
Syntax: LONG LZSeek(hLZFile, lOffset, iOrigin)
This function repositions the pointer in a previously opened
file.
Parameter Type/Description
--------- ----------------
hLZFile int Specifies the MS-DOS file handle or the
identifier for compressed-file-information
data structure. It is best to open the file by
calling the LZOpenFile function, which calls
the LZInit function. However, the normal
Windows OpenFile function can be used instead,
followed by a call to the LZInit function to
allocate and initialize the data structures used
by the expansion algorithm.
lOffset LONG Specifies the number of bytes the
pointer is to be moved.
iOrigin int Specifies the seek origin as used by
the _llseek function.
Return The return value is the new position in the file or -1
Value: if the seek is unsuccessful.
Comment: If the file is not compressed, the LZSeek function calls
the _llseek function with the MS-DOS file handle. If the
file is compressed, the _llseek function is emulated on the
expanded image of the file.
LZRead
------
Syntax: int LZRead(hLZFile, lpBuffer, wBytes)
If the file specified by hLZFile is not compressed, the
LZRead function calls the _lread function to read the file.
If the file is compressed, the file is read, decompressed, and
copied into lpBuffer until either the EOF is reached or wBytes
bytes have been written to lpBuffer.
Parameter Type/Description
--------- ----------------
hLZFile int Specifies the MS-DOS file handle or the
identifier for compressed-file-information
data structure for file to be read. It is best
to open the file by calling the LZOpenFile
function, which calls the LZInit function.
However, the normal Windows OpenFile function
can be used instead, followed by a call to the
LZInit function to allocate and initialize the
data structures used by the expansion algorithm.
lpBuffer LPSTR Pointer to the buffer that is to
receive the data read from the file.
wBytes WORD Specifies number of bytes to be read
from file.
Return The return value specifies the number of bytes written
Value: to lpBuffer. It is less than wBytes only if the EOF has been
reached. If the read fails, the return value is -1.
LZClose
-------
Syntax: VOID LZClose(hLZFile)
This function closes the file specified by the hLZFile
parameter. If the file is compressed, the global heap space
occupied by the compressed file information structure is
freed.
Parameter Type/Description
--------- ----------------
hLZFile int Specifies the MS-DOS file handle or the
identifier for compressed-file-information
data structure for the file to be closed.