| |
Expands the contents of a previously specified file.
Syntax
object.ExpandFile( InputFile,
OutputFile, [CompressionType] )
Parameters
- InputFile
- A string value that specifies the name of the file to be expanded. The file must
exist, and it must be a file that was created by a previous call to
the CompressFile method. An error will be returned if the
file cannot be accessed, if it specifies a character device such as
the console, or the if the data is not in a recognizable
format.
- OutputFile
- A string value that specifies the name of the file that will contain the expanded data.
If the file exists, it must be a regular file that can be opened
for writing by the current process and will be overwritten. If the
file does not exist, it will be created. An error will be returned
if a character device, such as the console, is specified as the
file name.
- CompressionType
- A numeric value which determines the algorithm that was used to
compress the data. One of the following values may be specified. If
this argument is not specified, the Deflate algorithm is used. If
the compression type specified by this argument does not match the
actual compression algorithm used to compress the file, an error
will be returned.
| Value |
Description |
| fileCompressionUnknown |
The method should attempt to determine what compression
algorithm was used when the data was compressed. This is done
by examining the header block of the file and checking for
certain signatures which can identify the algorithm. If the
algorithm cannot be determined, the method will fail. It is
recommended that most applications explicitly specify the
compression algorithm. |
| fileCompressionDeflate |
A compression algorithm that combines LZ77 algorithm for
creating common substrings and Huffman coding to process the
different frequencies of byte sequences in the data stream.
Deflate is widely used by compression software and provides a
good balance between the data compression ratio and system
resources used. This is the default compression method. |
| fileCompressionBzip2 |
A compression algorithm that rearranges blocks of data in
sorted order and then uses Huffman coding to process
different frequencies of data within the block.
Burrows-Wheeler compression provides a better compression
ratio than the Deflate algorithm, however it requires more
resources to perform the compression. |
| fileCompressionLzma |
A compression algorithm that combines the LZ77 algorithm
for dictionary-based compression with range encoding to
efficiently represent repetitive patterns in the data. LZMA
can achieve higher compression ratios than Deflate or the
Burrows-Wheeler algorithms; however, it requires more memory
and CPU resources due to the larger dictionary sizes and more
complex encoding algorithm. |
Return Value
This method returns a value of zero if the file was successfully
decompressed. A non-zero return value specifies an error code which
indicates the reason for the failure.
Remarks
The ExpandFile method expands the contents of a previously
compressed file. Note that this method can only expand files that were
compressed using the control. It cannot expand the contents of a file
stored in an archive format such as PKZip or WinZip.
The value of the CompressionType parameter must match the
value which was used with the CompressFile method. This
method will fail if you specify a different compression algorithm
than what was used to compress the file. Although your application can
use fileCompressionUnknown and attempt to automatically determine
how the file was compressed, this is not always reliable.
If the output file already exists, it will be replaced with the
expanded contents of the input file. If the contents of the file
cannot be expanded for any reason, the output file will be deleted.
If you want to ensure an existing output file will be preserved if an
error occurs, you should create a temporary file and use it as the output
file. If this method succeeds, then you can rename or copy the temporary
file which contains the expanded data.
See Also
CompareFile Method,
CompressFile Method,
DecodeFile Method,
EncodeFile Method
|
|