VB example VB streaming example Visual C++ example Delphi example

Description

The ReadFile method can compress and decompress data from a file to memory, as well as compute an Adler-32 or CRC checksum on a file.

Parameters
 

Parameter	Description
sSourceFilename	The path and filename of the file to read and process data from.
lSourceOffset	The starting offset in the file to begin processing data from. Specify 0 to begin processing data from the beginning of the file.
lSourceSize	The amount of data to process. Specify 0 to process data from the starting offset until the end of the file.
eAction	The type of processing that should be performed. Specify cfpCompress to compress data before writing it to memory. Specify cfpDecompress to decompress data before writing it to memory. Specify cfpCalculateCRC32 or cfpCalculareAdler32 to compute the checksum of the data read from the file.
bEndOfData	Determines whether or not the source data to read is the final (or the only) portion of data to process. Specify True if the source data should be completely compressed, decompressed or computed and written to memory. If the data to process is split apart in various sections of the same file, or in various files, then you can specify False in this parameter until all the source data has been read. You can specify True for the last portion of data (which can be 0 bytes long) so that the library knows it must finish processing the source data and return the last of the processed data immediately. When specifying False, the library will expect you to call the ReadFile method again later with either a new source filename and/or source offset and/or source size.
vaBytesRead	You must provide a variable in this parameter. Right before the ReadFile method completes and returns, the library will write to the variable the amount of bytes read and processed from the source file.

Return value

Returns a byte array variant containing the processed data.

When calling the ReadFile method with the bEndOfData parameter specified as False, the returned byte array variant may not contain any data. This is normal and happens whenever the compressor or decompressor has not received enough source data in order to output a processed block.

When the eAction parameter is specified as cfpCalculateCRC32 or cfpCalculareAdler32, the ReadFile method returns a long integer variant containing the computed checksum value.

Associated properties

Set the CompressionFormat property to specify the format of the data to compress or decompress. This not only determines whether or not the compressed data contains (or should contain) a checksum such as Adler-32 or CRC , but also in most cases implies which compression algorithm will be used by the library.

Associated methods

ToString and FromString

Remarks

When calling the ProcessFile method with the bEndOfData parameter specified as false, you cannot call any other Xceed Streaming Compression control method (of the same instance of the control) until you have completed processing a stream of data by calling the ProcessFile method with the bEndOfData parameter specified as true.

In addition to supporting regular single-file GZip files, the ReadFile and ProcessFile methods also support multi-file GZ archives (not TAR files) which contain multiple header/data/footer sections. Though the GZip format was not designed to append multiple files, such GZ files are circulating.

If dwSourceSize is greater than 0, and dwBytesRead is less than dwSourceSize, this indicates that the end of the compressed data was detected. If bEndOfData isfalse, a final call to the ReadFile or ProcessFile method must be done, without any source and with bEndOfData set to true, in order to complete the process and reset the state. If dwSourceSize is equal to 0 and bEndOfData is false and dwBytesRead is less than the actual number of bytes that are available in the source file at the offset, a final call to the ReadFile or ProcessFile method must be done, without any source and bEndOfData set to true,   in order to complete the process and reset the state. If bEndOfData is true, dwBytesRead will return either the detected end of compressed data or dwSourceSize if the end matched the provided size.

So with any scenario, the offset can be updated using dwBytesRead for any subsequent calls to the ReadFile or ProcessFile methods to either continue decompressing the file (bEndOfData false), or the following file in a multi-file GZ stream (bEndOfData true in the previous call).

Since the Decompress method cannot return the actual number of bytes processed out of the source data, it can decompress the compressed stream found at the specified offset, but you won't be able to update the offset for any subsequent compressed stream in the data. Thus, it is not suggested to try decompressing multi-file GZ data with the Decompress method.

Language-specific remarks

With Visual Basic, it is often necessary to convert the resulting processed data from a byte array variant to a native VB byte array before saving it or transmitting it. VB6 makes it particularly easy to do the conversion: If you have a variant named (for example) ProcessedData, you can convert it to a native VB byte array with the following code:

With Microsoft Access, you can place the processed data in either a Memo field or an OLE Object field. Using an OLE Object field in a table is the easiest: You can directly assign your data to the field and conversion is automatic. To assign the processed data variant to a Memo field, use the "AppendChunk" function in Access.