This topic applies to applications written in C++. For information on distributing an application written in Visual Basic, see Installing DirectX for Visual Basic Applications.

When the application-defined callback function DirectXSetupCallbackFunction is called by the DirectXSetup function, it is passed a parameter that contains the reason that the callback function was invoked. If the reason is DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE, the pInfo parameter points to a DSETUP_CB_UPGRADEINFO structure containing flags that summarize the DirectXSetup function recommendations on how to perform the upgrade of DirectX components and drivers. The structure member containing the flags is called UpgradeFlags.

The flags fall into the following categories:

Primary Upgrade Flags

These flags are mutually exclusive. One of them is always present in the UpgradeFlags structure member. You can extract it by performing a bitwise AND operation with DSETUP_CB_UPGRADE_TYPE_MASK.

DSETUP_CB_UPGRADE_FORCE

DSETUP_CB_UPGRADE_KEEP

DSETUP_CB_UPGRADE_SAFE

DSETUP_CB_UPGRADE_UNKNOWN

Secondary Upgrade Flags

Any or all of these flags can be present.

DSETUP_CB_UPGRADE_CANTBACKUP

DSETUP_CB_UPGRADE_HASWARNINGS

Device Active Flag

This flag is present if the device whose driver is being upgraded is active. It can be combined with any of the others.

DSETUP_CB_UPGRADE_DEVICE_ACTIVE

Device Class Flags

These flags are mutually exclusive. One of them is always present.

DSETUP_CB_UPGRADE_DISPLAY

DSETUP_CB_UPGRADE_MEDIA

In summary: every time the Reason parameter has the value DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE, the UpgradeFlags member of the structure pointed to by pInfo contains one Primary Upgrade Flag, zero or more Secondary Upgrade Flags, zero or one Device Active Flag, and one Device Class Flag.

If the UpgradeFlags member is set to DSETUP_CB_UPGRADE_KEEP, the DirectX component or device driver cannot be upgraded without causing Windows to cease functioning properly. The DirectXSetup function does not perform an upgrade on the component or driver.

A value of DSETUP_CB_UPGRADE_FORCE in UpgradeFlags means that the component or driver must be upgraded for Windows to function properly. The DirectXSetup function upgrades the driver or component. It is possible that the upgrade might adversely affect some programs on the system. When the DirectXSetup function detects this condition, the UpgradeFlags member is set to (DSETUP_CB_UPGRADE_FORCE | DSETUP_CB_UPGRADE_HAS_WARNINGS). When this occurs, the DirectXSetup function performs the upgrade but issues a warning to the user.

Components and drivers are considered safe for upgrade if they do not adversely affect the operation of Windows when they are installed. In this case, the UpgradeFlags member is set to DSETUP_CB_UPGRADE_SAFE. It is possible that the upgrade can be safe for Windows, but still cause problems for programs installed on the system. When DirectXSetup detects this condition, the UpgradeFlags member contains the value (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS). If this condition occurs, the default action for the DirectXSetup function is not to perform the upgrade.