VerInstallFile
The VerInstallFile
function attempts to install the specified file based on information returned
from the VerFindFile
function. VerInstallFile decompresses the file, if necessary, assigns a
unique filename, and checks for errors, such as outdated files.
As with the
other file installation functions, VerInstallFile will only work with
Win32 file images. 16-bit Windows file images are not supported.
DWORD VerInstallFile(
|
DWORD uFlags, |
// bit flags that
condition function behavior |
|
LPTSTR szSrcFileName, |
// file to install |
|
LPTSTR szDestFileName, |
// new name of file
to install |
|
LPTSTR szSrcDir, |
// source directory
of file to install |
|
LPTSTR szDestDir, |
// directory in
which to install file |
|
LPTSTR szCurDir, |
// directory where
file is currently installed |
|
LPTSTR szTmpFile, |
// receives name of
temporary copy of file used during installation |
|
PUINT lpuTmpFileLen |
// size of string
in szTmpFile |
|
); |
|
Parameters
uFlags
Contains a
bitmask of flags. This parameter can be one of the following values:
|
Flag |
Description |
|
VIFF_FORCEINSTALL |
Installs
the file regardless of mismatched version numbers. The function checks only
for physical errors during installation. |
|
VIFF_DONTDELETEOLD |
Installs
the file without deleting the previously installed file, if the previously
installed file is not in the destination directory. |
All other
values are reserved.
szSrcFileName
Points to the
name of the file to be installed. This is the filename in the directory pointed
to by the szSrcDir parameter; the filename can include only the filename
and extension, not a path.
szDestFileName
Points to the
name VerInstallFile will give the new file upon installation. This
filename may be different from the filename in the szSrcFileName
directory. The new name should include only the filename and extension, not a
path.
szSrcDir
Points to a
buffer that contains the name of the directory where the new file is found.
szDestDir
Points to a
buffer that contains the name of the directory where the new file should be
installed. VerFindFile
returns this value in its szDestDir parameter.
szCurDir
Points to a
buffer that contains the name of the directory where the preexisting version of
this file is found. VerFindFile returns this value in its szCurDir
parameter.
szTmpFile
Points to a
buffer that should be empty upon the initial call to VerInstallFile. The
function fills the buffer with the name of a temporary copy of the source file.
The buffer should be at least _MAX_PATH characters long, although this is not
required.
lpuTmpFileLen
Points to a
variable that contains the length of the szTmpFile buffer. This pointer
must not be NULL.
When the
function returns, lpuTmpFileLen contains the size, in characters, of the
data returned in szTmpFile, including the terminating null character. If
the buffer is too small to contain all the data, lpuTmpFileLen will be
the size of the buffer required to hold the data.
Return Values
The return
value is a bitmask that indicates exceptions. It can be one or more of the
following values:
|
Value |
Meaning |
|
VIF_TEMPFILE |
The
temporary copy of the new file is in the destination directory. The cause of
failure is reflected in other flags. |
|
VIF_MISMATCH |
The new and
preexisting files differ in one or more attributes. This error can be
overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL
flag set. |
|
VIF_SRCOLD |
The file to
install is older than the preexisting file. This error can be overridden by
calling VerInstallFile again with the VIFF_FORCEINSTALL flag set. |
|
VIF_DIFFLANG |
The new and
preexisting files have different language or code-page values. This error can
be overridden by calling VerInstallFile again with the
VIFF_FORCEINSTALL flag set. |
|
VIF_DIFFCODEPG |
The new
file requires a code page that cannot be displayed by the version of Windows
currently running. This error can be overridden by calling VerInstallFile
with the VIFF_FORCEINSTALL flag set. |
|
VIF_DIFFTYPE |
The new
file has a different type, subtype, or operating system from the preexisting
file. This error can be overridden by calling VerInstallFile again
with the VIFF_FORCEINSTALL flag set. |
|
VIF_WRITEPROT |
The
preexisting file is write protected. This error can be overridden by calling VerInstallFile
again with the VIFF_FORCEINSTALL flag set. |
|
VIF_FILEINUSE |
The
preexisting file is in use by Windows and cannot be deleted. |
|
VIF_OUTOFSPACE |
The
function cannot create the temporary file due to insufficient disk space on
the destination drive. |
|
VIF_ACCESSVIOLATION |
A read,
create, delete, or rename operation failed due to an access violation. |
|
VIF_SHARINGVIOLATION |
A read,
create, delete, or rename operation failed due to a sharing violation. |
|
VIF_CANNOTCREATE |
The
function cannot create the temporary file. The specific error may be
described by another flag. |
|
VIF_CANNOTDELETE |
The
function cannot delete the destination file, or cannot delete the existing
version of the file located in another directory. If the VIF_TEMPFILE bit is
set, the installation failed, and the destination file probably cannot be
deleted. |
|
VIF_CANNOTDELETECUR |
The
existing version of the file could not be deleted and VIFF_DONTDELETEOLD was
not specified. |
|
VIF_CANNOTRENAME |
The
function cannot rename the temporary file, but already deleted the
destination file. |
|
VIF_OUTOFMEMORY |
The
function cannot complete the requested operation due to insufficient memory.
Generally, this means the application ran out of memory attempting to expand
a compressed file. |
|
VIF_CANNOTREADSRC |
The
function cannot read the source file. This could mean that the path was not
specified properly. |
|
VIF_CANNOTREADDST |
The
function cannot read the destination (existing) files. This prevents the
function from examining the file s
attributes. |
|
VIF_BUFFTOOSMALL |
The szTmpFile
buffer was too small to contain the name of the temporary source file. When
the function returns, lpuTmpFileLen contains the size of the buffer
required to hold the filename. |
All other
values are reserved.
Remarks
VerInstallFile copies the file from the source directory to the
destination directory. If szCurDir indicates that a previous version of
the file exists on the system, VerInstallFile compares the files version stamp information. If the previously
installed version of the file is more recent than the new version, or if the
files attributes are significantly different, for example,
if they are in different languages, then VerInstallFile returns with one
or more recoverable error codes.
VerInstallFile leaves the temporary file in the destination
directory. The application can either override the error or delete the
temporary file. If the application overrides the error, VerInstallFile
deletes the previously installed version and renames the temporary file with
the original filename.
See Also