INSTALLSHIELD internal library function 21 version detection function
The following functions allow you to access version information existing in the Windows 95 and later files. To use these functions, you need to know the background information about the version resource. Check the Microsoft Windows Programmer's Reference, Volume 4: Resource Manual to better understand the version resource. Function Description Assume that you are fully familiar with the concept of version resources.
The following functions get a specific file version, find a file and get its version, or find an existing file and try to install an updated version of the file. The function can work in a compressed file or an uncompressed file.
Vercompare
Two strings containing version information.
VERFINDFILEVERSION
Find the specified file and retrieve it from its version and location.
VergetFileVersion
Retrieve a version of the specified file.
VersearchandupdateFile
Use an updated version to replace an existing file. If the specified file does not exist, the updated version is installed.
Verupdatefile
Use an updated version to replace an existing file. If the specified file does not exist, no updated version is installed.
21.1 Vercompare
Syntax: Vercompare (SzversionInfo1, SzversionInfo2, Ncompareflag);
Description: The Vercompare function compares two strings that contain version information.
parameter:
SzversionInfo1
The first version string is specified in the following format:
Main version number. Supreme version number
If SzversionInfo1 is 2.1.2.0, the main version number is 2.0, the secondary version is 2.0.
SzversionInfo2
Specify a second version string in the same format.
Ncompareflag
Pass the predefined constant Version to specify a comparison of the version number. This parameter does not allow other values.
return value:
Equals (2): Indicates that two strings have equal values.
Greater_than (0): Indicates that the value of the first string contains greater than the second.
Less_than (1): Indicates that the first string contains less than the second.
21.2 VerfindFileVersion
Syntax: VerfileName, Svpath, SvVersionNumber;
Description: The VerfindFileVersion function looks up a specified file and retrieves file versions and locations. VERFINDFILEVERSION uses the following finding algorithm to find files:
First, it looks for Windows folders.
Next, the Windows system folder.
Next, the folder specified by the system variable targetdir.
Next, the folder specified by the environment variable Path.
Finally, setup.exe runs the folder where the location is located.
For information on the Windows system folder, check the documentation of the InstallShield system variable Winsysdir.
parameter:
SZFileName
Specifies the non-qualified name of the file to get its version. Do not specify a drive indicator or path in this parameter location.
svpath
Returns the full path of the folder where the file is located (including the drive indicator).
SvversionNumber
Returns the file version number of the following format:
Main version number. Supreme version number
If SzversionNumber returns 2.1.2.0, the primary version number is 2.1, the secondary version number is 2.0.
return value:
0: Indicates that the function successfully returns version information.
FILE_NO_VERSION (-8): Indicates that the file is found but does not contain version information.
FILE_NOT_FOUND (-2): Indicates that the file has not been found.
annotation:
• When using VerfindFileVersion, you may need to set a value for Targetdir, not letting InstallShield automatically set it. Because the function is looking for a file in the TargetDir folder, you may need to set the system variable to make sure that VerfindFileVersion will find the file. If you want to do this, use Varsave to save this value before the value of Targetdir is temporarily set to another folder. 21.3 VergetFileVersion
Syntax: VergetFileVersion (SZFileName, SvversionNumber);
Description: The VergetFileVersion function retrieves the numeric version of the specified file.
parameter:
SZFileName
Specify the full qualification of the files to be retrieved.
SvversionNumber
String of the following format Returns the file numeric version number information:
Main version number. Supreme version number
If SzversionNumber returns 2.1.2.0, the primary version number is 2.1, the secondary version number is 2.0.
return value:
0: Indicates that the function successfully returns version information.
FILE_NOT_FOUND (-2): Indicates that the specified file has not been found.
FILE_NO_VERSION (-8): Indicates that the file is found but does not contain version information.
annotation:
· It is worth noting that although the INSTALLSHIELD file version information appears in a string format, the version information of one of the files indicated is numeric version information. A string of a file is not available and returned by the installshield function. Moreover, you must notice that when the Windows Explorer shows the properties of a file, it displays the string version information, which may be different from the file value version of the information. For this reason, the value returned by VergetFilever in the parameter svversionNumber may not match the version information displayed by the Windows Explorer.
· More situations about file versions, you can query Windows SDK or Win32 SDK.
21.4 VersearchandupdateFile
Syntax: VersearchandUpdatefile (SZFileName, NupdateFlag, SvinStalledFile);
Description: The VersearchandUpdateFile function looks up the specified file and install an updated version of the file when necessary. If the function found the file, it compares the version number of the existing file and the version number of the new file. If the existing file is old, it is replaced by the new file. The new file must be in the directory specified by the system variable Srcdir. If the function does not find an existing file, it copies the new file to the target system. Microsoft Windows determines where the file is installed according to the file type. For example, .dlls and system drives are installed in the Windows system folder. For information on the Windows system folder, review the documentation of the InstallShiLD system variable Winsysdir.
VersearchandUpdateFile uses the following finding algorithm to find existing files:
See the Find Algorithm in VerfindFileVersion.
parameter:
SZFileName
Specifies the unlimited name of the file to be installed. Do not specify a drive indicator or path in this parameter location.
NupdateFlag
Indicates whether the file is to be unconditional update or only if the file version found on the target system is updated than your existing file version. One of the following predefined constants in this parameter location:
Ver_update_cond: It is only updated when the existing file is an old version.
Ver_Update_always: Even if the existing file is an updated version, you have to update it.
SvinstalledFile
Returns the full qualification of the file installed by the function. If the file you want to replace is being used, the file is installed to the same directory with a slight difference name. The file is renamed with the first character of its extension. For example, if you install the file shell.dll and the file is locked, the file is copied to Shell. ~ LL. The file name returns from the variable. return value:
File_InStalled (0): The function is successfully installed.
FILE_IS_LOCKED (-4): Indicates that the file is being used by Windows and cannot be replaced. The new file is copied to the same directory with a new name.
FILE_NO_VERSION (-8): Indicates that the file is found, but it does not contain version information. File updates are not executed.
FILE_RD_ONLY (-5): Indicates that the existing file is written. The script must reset the read-only flag of the target file before installing, and then try to install the file.
FILE_SRC_OLD (-7): Indicates that the file to be installed has the same date or earlier than the previously existing files.
OUT_OF_DISK_SPACE (-6): Indicates that the function is not created because the disk space is insufficient on the target drive. File updates are not executed.
VER_DLL_NOT_FOUND (-3): Indicates that Ver.dll is not found. File updates are not executed.
Other_failure (-1): Indicates an uncertain error that occurs. File updates are not executed.
annotation:
· When using VersearChandUpdateFile, you may need to set values for srcdir and / or targetdir instead of letting InstallShield automatically. Because the function looks for files in the Srcdir and Targetdir folders, you may need to temporarily reset the value of these system variables to ensure that VersearchandUpdateFile will find files. If you need this, use Varsave to save their values using Varsave before setting SRCDIR and TargetDir. After calling the VersearchandUpdateFile function, use VARRESTORE to reset SRCDIR and Targetdir.
· For file transfer, the possible replacement function of VersearchandUpdateFile is XcopyFile, which can make version detection, tag lock. DLL and .exe file to be updated after the system is restarted, and increment the shared .dll and .exe file registry access counter.
21.5 VerupdateFile
Syntax: VerupdateFile (SZFileName, NuPDateFlag, SvinstalledFilePath);
Note: The VerupDateFile function uses a version information of a specified file to determine if the file is to be installed on the target system. VerupdateFile gets the file name in the parameter szfilename location. If you don't specify a full qualification in SZFileName, VerupdateFile uses the following finding algorithm to find the file (target file):
See the Find Algorithm for VERFINDFILEVERSION.
VerupdateFile then compares the version of the files of the same name in SRCDIR and the version of the target file (if there is). If the version number of the source file is updated than the version number of the target file, the target file is replaced with the source file. If the target file does not exist, installshield copies the source file to the target file.
When the parameter NUPDATEFLAG position is a SharedFile or LockedFile option, and when it is updated .dll or .exe file is being used by the system, the rename copy of the source file is transmitted to the target system and the system variable Batch_install is set to True. Then, the lock file is updated when the reoccialog or SDFINISHREBOOT is called and the system is restarted. For more information on updating lock files, please check RebootDialog and SDFINISHREBOOT. The system variable BATCH_INSTALL can be tested to determine if a lock-locked .dll or .exe file is encountered. You can't use SharedFile and LockedFile options at the same time, you have to use one or another. parameter:
SZFileName
Specifies the full qualification or non-qualified name of the file to be updated. If the name is unlimited (i.e., if it does not include a drive indicator or path), INSTALLSHIELD finds the Windows or Win95 directory, the system directory, the directory specified by the environment variable Path, and then the directory of the InstallShield executable. Match files. VerupdateFile takes the SZFileName's file name section and uses it to identify the file as a source file in SRCDIR.
NupdateFlag
Indicates whether the file is to be unconditional update or only when the file version found on the target system is updated earlier than your source file version. One of the following predefined constants in this parameter location is passed. You can use a bit or operator (|) to combine one of the constants SharedFile and other constants. You cannot combine SharedFile and LockedFile.
LockedFile: The VerupDateFile flag Windows or system is restarted to be updated .dll and .exe file. A locked file is a file that is being used by an application or system when InstallShield is trying to access or update. Likedfile options work like SharedFile, except for LockedFile does not create a registry expression or modify the registry access counter. You cannot use the lockedfile option when you use the sharedfile option. There are some non-shared files that do not register their feet and access counters for their script. These documents are never installed unless it is used by the application itself. LockedFile allows VerupDateFile to handle non-shared lock files.
SharedFile: You can combine the processing of sharing and locking files by updating all files with VerupdateFile to sharing, and logging Windows or system restarts.
When the file is present in the target directory and it has a access counter greater than 0, the SharedFile option causes VerupDateFile to handle all files for shared files and add a registry access counter. If the shared file does not exist in the target directory and it does not have access the counter, INSTALLSHIELD creates the counter and set it to 1. If the shared file already exists in the target directory but does not access the counter, INSTALLSHIELD creates the counter and initializes it into 2 as a preventive measures to prevent accidental deletion during the installation process.
Selfregister
When you use the "non-batch method" to install the self-registration file, you will be submitted immediately.
When you have called Enable (SelfregisterBatch), queue from the registration file waiting for registration.
When using the "Batch Method" to install the self-registration file, the file is registered once the DO (SelfRegistrationProcess) is called.
Always use the Selfregister and constant sharedfiles with a bit or operator combination.
Ver_Update_always: The version number is not considered when updating the file.
Ver_update_cond: It is only updated when the file is replaced is an older version.
SvinStalledFilePath returns the fully qualified name of the installed file. If the file you want to replace is being used, the file is installed to the same directory with a change name. InstallShield uses a ~ characters to replace the first character of the file extension.
For example, if you update the file shell.dll and the target file is locked, the source file is copied to the target directory with shell. ~ LL. The file name returns from the parameter svinstalledFilePath.
If the SharedFile option is used to use the parameter NUPDATEFLAG and the Lock file is updated correctly when Windows or system is restarted, the file is removed when the update is updated ~ The rename version is deleted.
return value:
FILE_INSTALLED (0): Indicates that the function is successfully installed. This constant is equal to 0. All other returns are less than 0.
FILE_IS_LOCKED (-4): Indicates that the existing file is being used by Windows and cannot be replaced. The new file is copied in a new name to the same directory, as described above.
FILE_NO_VERSION (-8): Indicates that the file is found, but it does not contain version information. Do not perform file updates.
FILE_RD_ONLY (-5): Indicates that the existing file is written. You must reset the read-only bit of the destination file before installing, and then try to install the file.
FILE_SRC_EQUAL (-9): Indicates that the files you are installing have the same version. If the Ver_Update_cond flag is set, no file update is executed.
FILE_SRC_OLD (-7): Indicates that the file you want to install is better than the existing file. If the Ver_Update_cond flag is set, no file update is executed.
OUT_OF_DISK_SPACE (-6): Indicates that the function failed to create a file because the disk space on the target drive is insufficient. Do not perform file updates.
-51: A self-registration file failed to successfully register.
Other_failure (-1): Indicates that there is an uncertain error. Do not perform file updates.
annotation:
• Before calling any functions that use the SharedFile option, you must use InstallationInfo to set the application information, and you must use the DeinstallStart function to set the uninstall information.
• When using verupdatefile, you may need to set a value for srcdir instead of letting INSTALLSHIELD set it. Because the function is looking for files in the Srcdir folder, you may need to temporarily set the system variable to ensure that verupdatefile will find the file. If you want to do this, use Varsave to save this value before you temporarily set the value of srcdir as another folder. After calling the VerupDateFile function, use Varrestore to reset the SRCDIR.
· For file transfer, the possible replacement function of VersearchandUpdateFile is XcopyFile, which can make version detection, tag lock. DLL and .exe file to be updated after the system is restarted, and increment the shared .dll and .exe file registry access counter.
