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.
See Also
MessageBox, DirectXSetupSetCallback, Customizing Setup With the DirectSetup Callback Function