DoPreUpgradeProcessing function
This function is obsolete for Microsoft Windows XP (SP1 and later), Microsoft Windows Server 2003, and later operating systems.
A network migration DLL must supply a DoPreUpgradeProcessing function. The DoPreUpgradeProcessing function assists in migrating a network component's preupgrade parameter values to upgraded operating system.
Syntax
LONG __stdcall DoPreUpgradeProcessing(
_In_ HWND hParentWindow,
_In_ HKEY hkeyParams,
_In_ LPCTSTR szPreNT5InfId,
_In_ LPCTSTR szPreNT5Instance,
_In_ LPCTSTR szNT5InfId,
_In_ LPCTSTR szSectionName,
_Out_ VENDORINFO *pviVendorInfo,
_Out_ DWORD *pdwFlags,
_In_ LPVOID pvReserved
);
Parameters
hParentWindow [in]
Handle to the parent window for any user interface displayed by the network migration DLL. If hParentWindow is NULL, then NetSetup is running in unattended mode and the DLL cannot display a user interface.hkeyParams [in]
Handle to the registry key that contains the preupgrade parameters of the network component being upgraded. For example, if TCP/IP is the component being upgraded, this function returns a handle to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Service\Tcpip.szPreNT5InfId [in]
Pnonupgrade ID for the network component to be upgraded. szPreNT5InfId is the component's ID in the component's Microsoft Windows NT version 3.1 or Windows NT version 4.0 INF file.szPreNT5Instance [in]
Component's service (device driver) name. For a component that is a not network adapter, szPreNT5Instance is the component's service (device driver) name. For a network adapter, szPreNT5Instance is the adapter's service name followed by an instance number as the suffix. Multiple instances of the same adapter are differentiated by unique instance numbers. For example, a value of adapter1 specifies the adapter driver's service name (adapter) and the instance (1) of the adapter.szNT5InfId [in]
Windows 2000 or later hw-id (also known as the device, hardware, or component ID) for the network component to be upgraded. The hw-id is specified in the Models section of the component's INF file for Windows 2000 or later operating systems.szSectionName [in]
Name of the network component's OEM-section in the AnswerFile. The szSectionName parameter has the following format:params.post-upgrade-ID.OemSection
where
post-upgrade ID is the Windows 2000 or later hw-id of the network component to be upgraded.
The network migration DLL writes component-specific information to this section.
pviVendorInfo [out]
Vendor-specific information, formatted as a VENDORINFO structure, which is defined as follows:
typedef struct {
WCHAR szCompanyName[256];
WCHAR szSupportNumber[256];
WCHAR szSupportUrl[256];
WCHAR szInstructionsToUser[1024];
} VENDORINFO;
The members of the VENDORINFO structure contain the following data:
szCompanyName
Name of the vendor.
szSupportNumber
Telephone number for technical support.
szSupportUrl
URL for a Web site that provides technical support.
szInstructionsToUser
Additional instructions that pertain to the network migration DLL.
pdwFlags [out]
Specifies zero or requests NetSetup to take a specified action:
| Value | Request |
|---|---|
Zero |
None |
NUA_LOAD_POST_UPGRADE |
Call the upgrade DLL during GUI mode setup |
NUA_REQUEST_ABORT_UPGRADE |
Display a message box that prompts the user to either quit or continue the upgrade |
pvReserved [in]
Reserved.
Return value
The DoPreUpgradeProcessing function can return either:
| Return code | Description |
|---|---|
| ERROR_SUCCESS | DoPreUpgradeProcessing succeeded. |
| ERROR_ XXX | A Win32 error code that specifies the cause of the failure, and which causes NetSetup to display an error message, clean up the network migration DLL files, and prompt the user to abort the upgrade of the operating system. |
Remarks
After calling a network migration DLL's PreUpgradeInitialize function during the Winnt32 phase of the network upgrade process, NetSetup calls DoPreUpgradeProcessing once for each network component that is being upgraded. DoPreUpgradeProcessing is called before the operating system is installed on the system that is being upgraded.
The DoPreUpgradeProcessing function can perform any of the following actions:
Read a network component's preupgrade parameter values from the registry.
Display a user interface, if not running in unattended mode, to obtain user input.
Write the network component's preupgrade parameters, along with other component-specific information, to the AnswerFile (winnt.sif).
NetSetup uses the AnswerFile during the operating system upgrade to migrate network components to the upgraded operating system.
Migrate binary data associated with the network component by making appropriate entries in the AnswerFile.
The DoPreUpgradeProcessing function uses the szPreNT5Instance and szNT5InfId parameters supplied by NetSetup to identify the component that is being upgraded.
The DoPreUpgradeProcessing function typically obtains a network component's preupgrade parameter values by reading them from the registry. The DoPreUpgradeProcessing function finds these values under the key for which hkeyParams is the handle.
If the migration DLL is not running in unattended mode, it can display a user interface on the preupgrade system under the parent window specified by hParentWindow. Through this interface, a user can specify component-specific parameters that the network migration DLL will migrate to the upgraded component.
The DoPreUpgradeProcessing function typically writes a network component's preupgrade parameter values to the AnswerFile.
The DoPreUpgradeProcessing function calls NetUpgradeAddSection to add an OEM-section for the component, as well as other component-specific sections, to the AnswerFile. DoPreUpgradeProcessing must use the OEM-section name ( szSectionName) specified by NetSetup. DoPreUpgradeProcessing calls NetUpgradeAddLineToSection as many times as required to add entries to sections in the AnswerFile. The information written by the network migration DLL to the AnswerFile must be readable by the SetupXxx functions of the upgraded operating system. For more information about the SetupXxx functions, see the Microsoft Windows SDK documentation.
If a network migration DLL will be loaded during the GUI-mode phase of the network upgrade process, DoPreUpgradeProcessing must set the NUA_LOAD_POST_UPGRADE flag. This flag causes NetSetup to load the migration DLL during the GUI-mode phase.
The DoPreUpgradeProcessing function can set the NUA_REQUEST_ABORT_UPGRADE flag to cause NetSetup to display a message box that prompts the user to stop the upgrade. The user can override this request and continue the upgrade. Typically, DoPreUpgradeProcessing sets this flag to request termination of the upgrade in response to a nonerror condition.
If an error condition occurs, DoPreUpgradeProcessing should return a Win32 error code that specifies the cause of the failure. This causes NetSetup to display an error message and clean up the network migration DLL files.
The DoPreUpgradeProcessing function passes a pointer ( pviVendorInfo) to NetSetup that points to vendor information formatted as a VENDORINFO structure. NetSetup displays this information if DoPostUpgradeProcessing returns a Win32 error code.
Requirements
Target platform |
Desktop |
Version |
Obsolete for Microsoft Windows XP with SP1 and later service packs, Microsoft Windows Server 2003, and later operating systems. |
Header |
Oemupgex.h (include OemUpGex.h) |
See also