DWORD VerInstallFile(dwFlags, szSrcFileName, szDestFileName, szSrcDir, szDestDir, szCurDir, szTmpFile, lpdwTmpFileLen) | |||
DWORD dwFlags; | |||
LPSTR szSrcFileName; | |||
LPSTR szDestFileName; | |||
LPSTR szSrcDir; | |||
LPSTR szDestDir; | |||
LPSTR szCurDir; | |||
LPSTR szTmpFile; | |||
LPDWORD lpdwTmpFileLen; |
The VerInstallFile function attempts to install a file based on information returned from the VerFindFile function. VerInstallFile uncompresses the file, if necessary, assigns a unique filename, and checks for errors, such as outdated files.
dwFlags
Contains a bitmask of flags. dwFlags may be the following:
Value | Meaning |
VIFF_FORCEINSTALL | ||
Installs the file regardless of mismatched version numbers. The function will only check 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 for future use by Microsoft.
szSrcFileName
Points to the name of the file to be installed. This is the filename in the szSrcDir directory; the filename should 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 than 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 directory name where the new file is found.
szDestDir
Points to a buffer that contains the directory name where the new file should be installed. VerFindFile returns this value in its szDestDir parameter.
szCurDir
Points to a buffer that contains the directory name 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 must be at least _MAX_PATH bytes long.
lpdwTmpFileLen
Points to the length of the szTmpFile buffer. On return, lpdwTmpFileLen contains the size, in bytes, of the data returned in szTmpFile, including the terminating zero byte. If the buffer is too small to contain all the data, lpdwTmpFileLen will be greater than the actual size of the buffer.
The return value is a bitmask that indicates exceptions. It may be one or more of the following:
Value | Meaning |
VIF_TEMPFILE | Indicates that the temporary copy of the new file is in the destination directory. The cause of failure is reflected in other flags. |
VIF_MISMATCH | Indicates that 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. |
VIF_SRCOLD | Indicates that the file to install is older than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag. |
VIF_DIFFLANG | Indicates that 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. |
VIF_DIFFCODEPG | Indicates that the new file requires a code page which cannot be displayed by the currently running version of Windows. This error can be overridden by calling VerInstallFile with the VIFF_FORCEINSTALL flag. |
VIF_DIFFTYPE | Indicates that the new file has different type, subtype, or operating system than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag. |
VIF_WRITEPROT | Indicates that the preexisting file is write-protected. This error can be overridden by calling VerInstallFile again the VIFF_FORCEINSTALL flag. |
VIF_FILEINUSE | Indicates that the preexisting file is in use by Windows and cannot be deleted. |
VIF_OUTOFSPACE | Indicates the function cannot create the temporary file due to insufficient disk space on the destination drive. |
VIF_ACCESSVIOLATION | Indicates that a read, create, delete or rename operation failed due to an access violation. |
VIF_SHARINGVIOLATION | Indicates that a read, create, delete or rename operation failed due to a sharing violation. |
VIF_CANNOTCREATE | Indicates that the function cannot create the temporary file. The specific error may be described by another flag. |
VIF_CANNOTDELETE | Indicates that 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_CANNOTRENAME | Indicates that the function cannot rename the temporary file, but already deleted the destination file. |
VIF_OUTOFMEMORY | Indicates that 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 | Indicates that the function cannot read the source file. This could mean that the path was not specified properly. |
VIF_CANNOTREADDST | Indicates that the function cannot read the destination (existing) files. This prevents the function from examining the file's attributes. |
VIF_BUFFTOOSMALL | Indicates that the szTmpFile buffer was too small to contain the name of the temporary source file. On return, lpdwTmpFileLen contains the size of the buffer required to hold the filename. |
All other values are reserved for future use by Microsoft.
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, i.e. 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 to the original filename.
VerFindFile