| #include <ver.h> |
| DWORD VerInstallFile(flags, lpszSrcFilename, lpszDestFilename, lpszSrcDir, lpszDestDir, lpszCurDir, lpszTmpFile, lpwTmpFileLen) | |||||
| UINT flags; | /* source-file flags, */ | ||||
| LPCSTR lpszSrcFilename; | /* address of source filename | */ | |||
| LPCSTR lpszDestFilename; | /* address of destination filename | */ | |||
| LPCSTR lpszSrcDir; | /* address of buffer for source dir. name | */ | |||
| LPCSTR lpszDestDir; | /* address of buffer for dest. dir. name | */ | |||
| LPCSTR lpszCurDir; | /* address of buffer for preexisting dir. | */ | |||
| LPSTR lpszTmpFile; | /* address of buffer for temp. filename | */ | |||
| UINT FAR* lpwTmpFileLen; | /* address of buffer for temp. file size | */ | |||
The VerInstallFile function attempts to install a file based on information returned from the VerFindFile function. VerInstallFile decompresses the file with the LZCopy function and checks for errors, such as outdated files.
flags
Contains a bitmask of flags. This parameter can be a combination of the following values:
| Value | Meaning |
| VIFF_FORCEINSTALL | Installs the file regardless of mismatched version numbers. The function will check only for physical errors during installation. |
| If flags includes VIFF_FORCEINSTALL and lpszTmpFileLen is not a pointer to zero, VerInstallFile will skip all version checks of the temporary file and the destination file and rename the temporary file to the name specified by lpszSrcFilename, as long as the temporary file exists in the destination directory, the destination file is not in use, and the user has privileges to delete the destination file and rename the temporary file. The return value from VerInstallFile should be checked for any errors. | |
| VIFF_DONTDELETEOLD | Installs the file without deleting the previously installed file, if the previously installed file is not in the destination directory. If the previously installed file is in the destination directory, VerInstallFile replaces it with the new file upon successful installation. |
All other values are reserved for future use.
lpszSrcFilename
Points to the name of the file to be installed. This is the filename in the directory pointed to by lpszSrcDir; the filename should include only the filename and extension, not a path. VerInstallFile opens the source file by using the LZOpenFile function. This means it can handle both files as specified and files that have been compressed and renamed by using the /r option with COMPRESS.EXE.
lpszDestFilename
Points to the name VerInstallFile will give the new file upon installation. This filename may be different than the filename in the directory pointed to by lpszSrcFilename. The new name should include only the filename and extension, not a path.
lpszSrcDir
Points to a buffer that contains the directory name where the new file is found.
lpszDestDir
Points to a buffer that contains the directory name where the new file should be installed. The VerFindFile function returns this value in the lpszDestDir parameter.
lpszCurDir
Points to a buffer that contains the directory name where the preexisting version of this file is found. VerFindFile returns this value in the lpszCurDir parameter. If the filename specified in lpszDestFilename already exists in the lpszCurDir directory and flags does not include VIFF_DONTDELETEOLD, the existing file will be deleted. If lpszCurDir is a pointer to NULL, a previous version of the file does not exist on the system.
lpszTmpFile
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.
lpwTmpFileLen
Points to the length of the buffer pointed to by lpszTmpFile. On return, lpwTmpFileLen contains the size, in bytes, of the data returned in lpszTmpFile, including the terminating null character. If the buffer is too small to contain all the data, lpwTmpFileLen will be greater than the actual size of the buffer.
If flags includes VIFF_FORCEINSTALL and lpwTmpFileLen is not a pointer to zero, VerInstallFile will rename the temporary file to the name specified by lpszSrcFilename.
The return value is a bitmask that indicates exceptions, if the function is successful. This value 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. Applications should always check whether this bit is set and delete the temporary file, if required. |
| 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 that 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 a 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. The installation program should reset the read-only bit in the destination file before proceeding with the installation. |
| VIF_FILEINUSE | Indicates that the preexisting file is in use by Windows and cannot be deleted. |
| VIF_OUTOFSPACE | Indicates that the function cannot create the temporary file due to insufficient disk space on the destination drive. |
| VIF_ACCESSVIOLATION | Indicates that a create, delete, or rename operation failed due to an access violation. |
| VIF_SHARINGVIOLATION | Indicates that a 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 ver-sion 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, that the file does not exist, or that the file is a compressed file that has been corrupted. To distinguish these conditions, use LZOpenFile to determine whether the file exists. (Do not use the OpenFile function, because it does not correctly translate filenames of compressed files.) Note that VIF_CANNOTREADSRC does not cause either the VIF_ACCESSVIOLATION or VIF_SHARINGVIOLATION bit to be set. |
| 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 lpszTmpFile buffer was too small to contain the name of the temporary source file. On return, lpwTmpFileLen contains the size of the buffer required to hold the filename. |
All other values are reserved for future use.
VerInstallFile is designed for use in an installation program. This function copies a file (specified by lpszSrcFilename) from the installation disk to a temporary file in the destination directory. If necessary, VerInstallFile expands the file by using the functions in LZEXPAND.DLL.
If a preexisting copy of the file exists in the destination directory, VerInstallFile compares the version information of the temporary file to that of the preexisting file. If the preexisting file is more recent than the new version, or if the files' attributes are significantly different, VerInstallFile returns one or more error values. For example, files with different languages would cause VerInstallFile to return VIF_DIFFLANG.
VerInstallFile leaves the temporary file in the destination directory. If all of the errors are recoverable, the installation program can override them by calling VerInstallFile again with the VIFF_FORCEINSTALL flag. In this case, lpszSrcFilename should point to the name of the temporary file. Then, VerInstallFile deletes the preexisting file and renames the temporary file to the name specified by lpszSrcFilename. If the VIF_TEMPFILE bit indicates that a temporary file exists and the application does not force the installation by using the VIFF_FORCEINSTALL flag, the application must delete the temporary file.
If an installation program attempts to force installation after a nonrecoverable error, such as VIF_CANNOTREADSRC, VerInstallFile will not install the file.