PreUpgradeInitialize function

Artikel
06/19/2017

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 follows
```
typedef 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

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)

Freigeben über