DirectXSetupCallbackFunction

DirectXSetupCallbackFunction is a placeholder name for a callback function supplied by the setup program. The callback function reports the status of the current installation process. It also can provide information for use by the MessageBox function.

DWORD DirectXSetupCallbackFunction(
  DWORD  Reason,   // reason for the callback
  DWORD  MsgType,  // same as MessageBox
  char *szMessage, // message string
  char *szName,    // depends on Reason
  void *pInfo      // upgrade information
);

Parameters

Reason

Reason for the callback. It can be one of the following values.

DSETUP_CB_MSG_BEGIN_INSTALL
	DirectXSetup is about to begin installing DirectX components and device drivers.
DSETUP_CB_MSG_BEGIN_INSTALL_DRIVERS
	DirectXSetup is about to begin installing device drivers.
DSETUP_CB_MSG_BEGIN_INSTALL_RUNTIME
	DirectXSetup is about to begin installing DirectX components.
DSETUP_CB_MSG_BEGIN_RESTORE_DRIVERS
	DirectXSetup is about to begin restoring previous drivers.
DSETUP_CB_MSG_CANTINSTALL_BETA
	A pre-release beta version of Windows 95 was detected. The DirectX component or device driver can't be installed.
DSETUP_CB_MSG_CANTINSTALL_NOTWIN32
	The operating system detected is not Windows 95 or Windows NT®. DirectX is not compatible with Windows 3.x.
DSETUP_CB_MSG_CANTINSTALL_NT
	The DirectX component or device driver can't be installed on versions of Windows NT prior to version 4.0.
DSETUP_CB_MSG_CANTINSTALL_UNKNOWNOS
	The operating system is unknown. The DirectX component or device driver can't be installed.
DSETUP_CB_MSG_CANTINSTALL_WRONGLANGUAGE
	The DirectX component or device driver is not localized to the language being used by Windows.
DSETUP_CB_MSG_CANTINSTALL_WRONGPLATFORM
	The DirectX component or device driver is for another type of computer.
DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE
	Driver is being considered for upgrade. Verification from user is recommended.
DSETUP_CB_MSG_INTERNAL_ERROR
	An internal error has occurred. Setup of the DirectX component or device driver has failed.
DSETUP_CB_MSG_NOMESSAGE
	No message to be displayed. The callback function should return.
DSETUP_CB_MSG_NOTPREINSTALLEDONNT
	The DirectX component or device driver can't be installed on the version of Windows NT in use.
DSETUP_CB_MSG_PREINSTALL_NT
	DirectX is already installed on the version of Windows NT in use.
DSETUP_CB_MSG_SETUP_INIT_FAILED
	Setup of the DirectX component or device driver has failed.

MsgType

Contains flags that control the display of a message box. These flags can be passed to the MessageBox function. An exception is when MsgType is equal to zero. In that case, the setup program can display status information but should not wait for input from the user.

szMessage

A localized character string containing error or status messages that can be displayed in a message box created with the MessageBox function.

szName

The value of szName is NULL unless the Reason parameter is DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE. In that case, szName contains the name of driver to be upgraded.

pInfo

Pointer to a structure containing upgrade information. When Reason is DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE, the setup program is in the process of upgrading a driver and asking the user whether the upgrade should take place. This structure contains information about the upgrade in its UpgradeType member, which can have the following values.

DSETUP_CB_UPGRADE_CANTBACKUP
	The old system components can't be backed up. Upgrade can be performed, but the components or drivers can't be restored later.
DSETUP_CB_UPGRADE_DEVICE_ACTIVE
	The device is currently in use.
DSETUP_CB_UPGRADE_DEVICE_DISPLAY
	The device driver being upgraded is for a display device.
DSETUP_CB_UPGRADE_DEVICE_MEDIA
	The device driver being upgraded is for a media device.
DSETUP_CB_UPGRADE_FORCE
	Windows may not function correctly if the component is not upgraded. The upgrade will be performed.
DSETUP_CB_UPGRADE_HASWARNINGS
	DirectXSetup can upgrade the driver for this device, but doing so may affect one or more programs on the system. szMessage contains the names of which programs may be affected. Upgrade not recommended.
DSETUP_CB_UPGRADE_KEEP
	The system may fail if this device driver is upgraded. Upgrade not allowed.
DSETUP_CB_UPGRADE_SAFE
	DirectXSetup can safely upgrade this device driver. Upgrade recommended. A safe upgrade will not adversely affect the operation of Windows. Some hardware-dependent programs may be adversely affected.
DSETUP_CB_UPGRADE_UNKNOWN
	DirectXSetup does not recognize the existing driver for this device. This value will occur frequently. Upgrading may adversely affect the use of the device. It is strongly recommended that the upgrade not be performed.
DSETUP_CB_UPGRADE_UNNECESSARY
	The existing device driver is newer than the driver being installed. An upgrade is not recommended.

Return Values

The return value should be the same as the MessageBox function, with one exception. If this function returns zero, the DirectXSetup function will act as if no callback function was present. That is, it will perform the default action for upgrade of the DirectX component or driver.

Remarks

The name of the DirectXSetupCallbackFunction is supplied by the setup program. The DirectXSetupSetCallback function is used to pass the address of the callback function to DirectSetup.

If MsgType is equal to zero, the setup program may display status information, but it should not wait for user input. This is useful for displaying ongoing status information.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in dsetup.h.
  Import Library: User-defined.

DirectXSetupCallbackFunction

Parameters

Return Values

Remarks

QuickInfo

See Also