QueryVersion

[This is preliminary documentation and subject to change.]

Setup uses QueryVersion to determine if further processing of the DLL is necessary.

LONG
CALLBACK 
QueryVersion(
    OUT LPCSTR *ProductID,
    OUT LPUINT DllVersion,
    OUT LPINT *CodePageArray,    OPTIONAL
    OUT LPCSTR *ExeNamesBuf,    OPTIONAL
    LPVOID Reserved
    );

Parameters

*ProductID

Points to a string that identifies the DLL and its target application. To ensure uniqueness, the string must contain the name of the manufacturer, the product name, and the version number of the application the DLL will migrate. The length of the string must not exceed MAX_PATH bytes (as defined within your migration DLL). Setup ignores excess characters. The ProductID string is also used for error messages generated during DLL processing.

Note Your migration DLL is responsible for allocating and freeing the ProductID string buffer.

DllVersion

Points to a non-zero unsigned integer that specifies the version number of your migration DLL. Setup looks for duplications by comparing ProductID strings from other migration DLLs. If two or more DLLs have identical ProductID strings, Setup uses the DLL with the highest DllVersion number and ignores the other duplicates.

Note DllVersion is not intended to be the DLL binary version number.

CodePageArray

Points to an array of integers containing all the code pages supported by the migration DLL. The last element of the array must be -1. If your migration DLL does not support the system code page, Setup skips your migration DLL and your application will not migrate to the new operating system.

If this pointer is NULL, Setup processes all the required functions in the DLL regardless of the installed Windows 95 and Windows 98 code pages. Set this pointer to NULL if the DLL has no language dependencies.

Note Your DLL is responsible for the allocating and freeing memory used by this array.

ExeNamesBuf

Points to a multi-sz string buffer containing a list of file names (not paths) that your migration DLL wants Setup to locate. Setup locates all instances of the listed files and returns the list of full file paths to your migration DLL via the MIGRATE.INF file. Paths to files located on network, substituted, or compressed drives will not be returned to the DLL because Setup does not search those drives. Other directories on the computer not related to the active Windows 95 or Windows 98 installation may also be excluded.

Set this parameter to NULL if you do not want Setup to search for any particular files.

Note Your migration DLL is responsible for allocating and freeing the ExeNamesBuf string buffer.

Reserved

Reserved for future use.

Return Values

ERROR_SUCCESS if your migration DLL found one or more installed components for its target application. This guarantees that Setup will call your migration DLL for later processing.

ERROR_NOT_INSTALLED if your migration DLL initializes properly but did not find any of its components installed on the active Windows 95 or Windows 98 installation. Note that Setup will not call your DLL again if it returns ERROR_NOT_INSTALLED.

Your migration DLL must also return ERROR_SUCCESS if it does not attempt to detect installed components in QueryVersion.

All other return values (Win32 error values) are considered initialization errors. Setup will report the error to the user, clean up your migration DLL files, and ask the user to continue or cancel the Windows NT installation process.

An exception generated by a migration DLL causes Setup to report RPC error messages. Setup will provide more information in SETUPERR.LOG.

Remarks

Setup uses QueryVersion to determine if further processing of the DLL is necessary. During this call, your migration DLL (located on a floppy, compact disc, or network share) must provide Setup with the ProductID, DllVersion, CodePageArray, and ExeNamesBuf information. At this point, your migration DLL cannot make any changes to the system.

Your migration DLL should try to determine if the target application is installed on the computer, and then return the appropriate result from QueryVersion. The system unloads the migration DLL after QueryVersion returns. Setup copies it to the local hard disk and calls Initialize9x only if QueryVersion returns ERROR_SUCCESS.

During the call to QueryVersion, Setup finds all occurrences of files listed in the ExeNamesBuf string (if not NULL) and writes their locations to the [Migration Paths] section of MIGRATE.INF. These paths are then available to the other functions in your migration DLL.

Setup detects duplicate migration DLLs by comparing the ProductID strings of supplied DLLs. It only processes the DLL with the highest DllVersion number. The user is not notified of duplicates found.

Important DllVersion number zero (0) is reserved for Windows NT Setup-provided migration DLLs. DLLs not supplied by Microsoft Windows NT with the Windows NT 5.0 compact disc must not use this value.