PreUpgradeInitialize 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 PreUpgradeInitialize function. PreUpgradeInitialize supplies the DLL with information about the upgrade environment. The PreUpgradeInitialize function also supplies NetSetup with vendor information and can cause NetSetup to display a message that prompts the user to abort the upgrade of the operating system.
Syntax
LONG __stdcall PreUpgradeInitialize(
_In_ LPCTSTR swWorkingDir,
_In_ NetUpgradeInfo *pNetUpgradeInfo,
_Out_ VENDORINFO *pviVendorInfo,
_Out_ DWORD *pdwFlags,
_Out_ NetUpgradeData *pNetUpgradeData
);
Parameters
swWorkingDir [in]
Complete path of the directory in which the network migration DLL must store temporary files. The DLL will be able to access this directory when the DLL runs in the GUI-mode phase of the upgrade.pNetUpgradeInfo [in]
Source and target operating systems involved in the upgrade. This information is formatted as a NetUpgradeInfo structure, which is defined as followstypedef struct NetUpgradeInfo { ProductInfo From; ProductInfo To; };The members of the NetUpgradeInfo structure contain the following data:
From
Operating system from which the component is being upgraded. This information is formatted as a ProductInfo structure, which is defined as follows:typedef struct ProductInfo { PRODUCTTYPE ProductType; DWORD dwBuildNumber; };The members of the ProductInfo structure contain the following data:
ProductType
Operating system from which the component is being upgraded as one of the following:
NT_SERVER
Microsoft Windows NT Server
NT_WORKSTATION
Microsoft Windows NT Workstation
UNKNOWN
Unknown product type
dwBuildNumber
Build number of the operating system from which the component is being upgraded as either of the following:
1057
Microsoft Windows NT version 3.51
1381
Microsoft Windows NT version 4.0
To
Operating system to which the component is being upgraded. This information is formatted as a ProductInfo structure, which is defined as follows:
typedef struct ProductInfo {
PRODUCTTYPE ProductType;
DWORD dwBuildNumber;
};
The members of the ProductInfo structure contain the following data:
ProductType
Operating system to which the component is being upgraded as one of the following:
NT_SERVER
Microsoft Windows NT Server
NT_WORKSTATION
Microsoft Windows NT Workstation
UNKNOWN
Unknown product type
dwBuildNumber
Build number of the operating system to which the component is being upgraded as either of the following:
2195
Microsoft Windows 2000
2416 or later
Microsoft Windows XP
pviVendorInfo [out]
Information about the vendor 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
Vendor's telephone number for technical support.
szSupportUrl
URL for the vendor's web site that provides technical support.
szInstructionsToUser
Additional instructions that pertain to the upgrade DLL.
pdwFlags [out]
Specifies zero or requests NetSetup to take a specified action:
| Value | Request |
|---|---|
Zero |
None |
NUA_REQUEST_ABORT_UPGRADE |
Display a message box that prompts the user to quit the upgrade of the operating system. |
pNetUpgradeData [out]
Services that NetSetup should not delete before upgrading the operating system. This information is formatted as a NetUpgradeDataTag structure, which is defined as follows:
typedef struct NetUpgradeDataTag{
LPTSTR mszServicesNotToBeDeleted;
} NetUpgradeData;
The member of the NetUpgradeDataTag structure contains the following data:
- mszServicesNotToBeDeleted
A MULTI_SZ value that specifies a list of services. Each entry in this list specifies a service that should not be deleted by NetSetup during the upgrade process. All other services (those not listed in mszServicesNotToBeDeleted) will be deleted and then reinstalled by NetSetup during the upgrade process.
Return value
The PreUpgradeInitialize function can return either:
| Return code | Description |
|---|---|
| ERROR_SUCCESS | Migration DLL found one or more installed components. |
| ERROR_XXX | A Win32 error code that causes NetSetup to display an error message, clean up the network migration DLL files, and prompt the user to quit the upgrade of the operating system. |
Remarks
NetSetup calls a network migration DLL's PreUpgradeInitialize function once during the Winnt32 phase of the operating system upgrade. NetSetup calls PreUpgradeInitialize before calling the DLL's DoPreUpgradeProcessing function.
PreUpgradeInitialize supplies the network migration DLL with information about the source operating system and the target operating system. Specifically, the PreUpgradeInitialize function specifies the product type (Microsoft Windows NT Workstation or Microsoft Windows NT Server) and build number of:
The operating system being upgraded
The operating system being installed
The PreUpgradeInitialize function passes a pointer ( pviVendorInfo) to NetSetup that points to vendor information formatted as a VENDORINFO structure. NetSetup displays this information if PreUpgradeInitialize returns a Win32 error code.
If an error occurs, PreUpgradeInitialize returns a Win32 error code. NetSetup reports the error to the user, cleans up the upgrade DLL files, and asks the user to quit or continue the installation of the operating system.
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