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 works only with Win32 file images. It does not work with 16-bit Windows file images.
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
);
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.
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.
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 the system 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 the system 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.
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.
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winver.h.
Import Library: Use version.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.
File Installation Library Overview, File Installation Library Functions, VerFindFile