XbZ_UnCompress()
Previous  Top  Next

XbZ_UnCompress() - Un-Compress (Inflate) a string.

Syntax

XbZ_UnCompress(@cData,  
               @nSize,  
              [@nError]) --> cUnCompressed  

Parameters

<@cData>  
<@cData> contains a string that should be compressed (with the Deflate method). This parameter must be passed by reference, even though it will not be modified.  

<@nSize>  
<@nSize> contains the Size of the un-compressed (original) Data. This parameter must be passed by reference, even though it will not be modified.  

<@nError>  
After XbZ_UnCompress() returns, the optional Parameter <@nError> will contain any kind of Un-Compression Error that might be raised by the ZLib uncompress() function. This parameter is optional, but must be passed by reference if it should be updated.  
 
Possible values are the following Define Constants from the XbZLib.ch file:  
 
Define
Value
Description
XBZ_OK
0
Adding/Updating of (File) Entry was successful.
XBZ_DATA_ERROR
-3
(ZLib Error Code) Corrupted Data/Buffer.
XBZ_MEM_ERROR
-4
(ZLib Error Code) Not enough Memory.
XBZ_BUF_ERROR
-5
(ZLib Error Code) Output Buffer too small.
 

Returns

This function returns an Inflated (Un-Compressed) version of <@cData> or possibly a string that only contains spaces, if an error occurred.  

Description

This is basically an Xbase++ Wrapper Function for the ZLib Function: uncompress(). It returns the uncompressed (inflated) <@cData> as a string, and updates <@nError> with any possible Error Return Code of the ZLib Function. This function is also used for un-compressing the Data of Zip File Entries by the :Extract() and :Test() methods.  
 
NOTE: Even if the Data was correctly inflated, the ZLib Function: uncompress() function might still return an XBZ_DATA_ERROR! In such a case, it is usually sufficient to check if the CRC is correct, to be sure that the Data was correctly inflated and the Error can be ignored. This kind of Error is usually only raised with Zip File Entries that were not compressed/deflated by XbZLib, but by other applications, like PkZip 2.04g, PkZip 2.50, WinZip, or PowerArchiver.  

Example

Open a Zip File named "MyArchive", find a File named "MyOldFile" in it, un-compress it and save it as a new File named "MyNewFile", and close the Zip File:  

LOCAL nError  := XbZ_OK  
LOCAL oZip    := XbZLibZip():New('MyArchive.zip')  
LOCAL oCDRec  := oZip:FindEntry('MyOldFile')  
LOCAL cData   := oZip:GetData(oCDRec)  
LOCAL nLength := oCDRec:UnCompSize  
LOCAL cBuffer := XbZ_UnCompress(@cData, @nLength, @nError)  
oZip:Close()  
if nError == XbZ_OK  
   if (nHandle := FCreate('MyNewFile')) > 0  
      FWrite(nHandle, cBuffer) ; FClose(nHandle)  
   else  
      QOut('MyNewFile could not be created!')  
      QOut('Error: ' + alltrim(str(FError())) + ' - ' + ;  
                   DosErrorMessage(FError()))  
   endif  
else  
   QOut('MyOldFile could not be un-compressed!')  
   QOut('Error: ' + alltrim(str(nError)))  
endif