Search Tips Advanced Search |
| Delphi Graphics and Game Programming Exposed with DirectX 7.0 by John Ayres Wordware Publishing, Inc. ISBN: 1556226373 Pub Date: 12/01/99
Search this book:
Previous | Table of Contents | Next
## APPENDIX Installing DirectX This appendix covers the following topics: • Retrieving the version number of the currently installed DirectX • Installing DirectX components, either in full or in part • Overriding the default behavior of installation to provide custom status messages and feedback Before a game written using the DirectX API can be run on a user’s system, that system must have DirectX installed. Fortunately, Microsoft allows game developers to redistribute the DirectX run-time components and drivers at no charge. Additionally, they’ve included methods that make the installation of DirectX largely automated. In keeping with their naming convention for this technology, setup of DirectX components and drivers is accomplished through the DirectSetup API. In this appendix, we’ll examine how the DirectSetup API allows us to install DirectX with a minimum of hassle. We’ll also examine ways to determine the current version of DirectX already installed, as well as how to override the default behavior of the installation in order to provide our own interface. ### DirectX Redistributables DirectX is available from a number of sources. Many computer manufacturers are shipping machines with DirectX already installed. Indeed, future versions of Windows will include DirectX automatically. The DirectX run-time components are also available both online (at Microsoft’s web site) as well as part of the installation for hundreds of commercial games and applications.
| Tip: You may want to suggest that users download the latest DirectX drivers straight from the Microsoft web site as part of your standard technical support. Users can retrieve the end user DirectX files from http://www.microsoft.com/directx/homeuser/downloads/default.asp at the time of this writing. Microsoft technical support should also be able to help users if they are having trouble installing DirectX drivers.
If DirectX is already installed on a user’s system, it is not necessary to install it again when the user installs your application (unless, of course, the application uses a more current version of DirectX than that currently installed). Thus, if you are certain that your end users already have DirectX installed, there is no need to worry about the techniques described here. Unfortunately, although Microsoft is taking steps to make it simple for users to upgrade their Windows installation, we cannot always assume that users have DirectX installed on their machines. Microsoft allows developers to redistribute the run-time portion of DirectX royalty free with our applications. This distribution is subject to the terms of their end user license agreement, also known as an EULA, which accompanies the DirectX SDK. Therefore, you’ll need to obtain the DirectX SDK in order to get all of the information and rights necessary for redistributing DirectX. For more information on obtaining the latest DirectX SDK and other DirectX run-time components, please visit http://www.microsoft.com/directx/developer/downloads/default.asp.
| EULA: End user license agreement; a legal document that details specific licensing issues concerning software.
The redistributable files themselves are located in the Redist directory of the DirectX SDK. The license agreement for redistributing DirectX run-time components instructs us that we must not modify DirectX in any way, nor change the files that must be redistributed, with one exception. The DirectX redistributable files come in several localized flavors, and we can leave out any specific language for which we will not support. Thus, if we only want to ship the English language version of DirectX, we need only include the ‘eng’ directory under the DirectX\Drivers directory of the redistributable files. This may be desirable, as the size of the entire redistributable file set is over 50 MB. Please see the DirectX SDK EULA.txt file that ships with the DirectX SDK for more details concerning redistribution of DirectX with applications.
| Note: At the time of this writing, the DirectX redistributables cannot be installed under Windows NT. DirectX can only be installed on NT through NT service packs.

### DirectSetup

As mentioned previously, DirectSetup is responsible for installing DirectX components on an end user’s machine. Unlike the other DirectX subsystems, the DirectSetup API is rather small. There are only a few functions included in this API, and full installation of all DirectX run-time components and drivers can be accomplished by calling one simple function. Alternatively, the default behavior of the entire installation process can be overridden and monitored. The DirectSetup API can make installation of DirectX as simple or as complicated as necessary, giving developers plenty of flexibility in their installation programs.

#### Features

DirectSetup provides several techniques by which an application can have a varying degree of control over the installation of DirectX. The following features are of interest to any developer implementing DirectX installation functionality:

  • Quick, painless installation of the entire DirectX system, run-time components only, or drivers only through one simple function call
  • Ability to override the default behavior of DirectX installation to provide custom status reports and installation query messages
  • Testing of the DirectX installation without copying any files into system directories
  • Determination of the version of the currently installed DirectX system

In the following sections we will see how DirectSetup is used to install DirectX components in an automated, default manner as well as techniques to override this default behavior to provide additional feedback.

#### Functional Overview

The purpose of DirectSetup is to install DirectX in a manner such that it does not inadvertently affect the system. Therefore, it takes a very conservative approach, and by default, it will not replace any driver that is questionable or may impact the system in any negative way. In addition, it also backs up any driver that is replaced, so that the user may reverse the installation and restore the original drivers if necessary.

In contrast to other DirectX subsystems, the DirectSetup API is not a collection of COM components, but rather a small handful of functions. Indeed, our discussion of DirectSetup will encompass only three of these functions: DirectXSetupGetVersion, DirectXSetup, and DirectXSetupSetCallback.

The first function, DirectXSetupGetVersion, is rather simple. It merely retrieves the version and revision numbers of the DirectX components currently installed. This function can be used to determine if the current DirectX version is older than the one included with the application, or if DirectX is installed at all.

|  | Tip: You can also determine the version of DirectX currently installed on the user’s machine using techniques from Chapter 4, An Introduction to DirectX.

The second function, DirectXSetup, is perhaps the most important. This function performs the actual installation of all of the DirectX components. Using this function, we can indicate if the entire DirectX system should be installed or only certain parts. Specifically, we can instruct the function to install only run-time components, audio drivers, or display drivers.

The final function, DirectXSetupSetCallback, is used to provide a callback function used by the installation procedure that notifies the application when an installation event occurs. This allows the application to customize the behavior of the installation process and display status messages and message boxes different from the default. This function must be used to install a callback function before the DirectXSetup function is called.

#### Using DirectSetup

In what should be a very familiar theme by now, using DirectSetup involves some very specific steps performed in a specific order. Not surprisingly, some of these steps are optional, some are not. In order to use DirectSetup to install DirectX, the application must perform the following:

  • Locate the DirectX redistributables in the same directory as the setup application
  • Retrieve available drive space
  • Retrieve the current version of DirectX (optional)
  • Set a callback function (optional)
  • Call the DirectXSetup function

Locate the DirectX Redistributables

More a requirement than a step, this is a task the developer must perform when packaging the application files for distribution. In order to use DirectSetup functions, the DirectX redistributable files must be placed somewhere on the distribution media (presumably a CD). Specifically, the dsetup.dll, dsetup16.dll, and dsetup32.dll must be in the same directory as the setup application so they’ll be loaded when the application starts. The other DirectX redistributable files must be located in a directory named DirectX (not case sensitive) which may be located elsewhere, but typically it is more convenient to simply place them in the same directory as the setup application (see below for more details). In the example for this chapter, we placed the redistributables in the same directory as the example code, so refer to the accompanying CD for an example of directory structure.

Retrieve Available Drive Space

Technically speaking, this step is not an absolute requirement, as the DirectX installation procedure will fail gracefully if it runs out of disk space. DirectX requires a minimum of 15 MB of free space (if you only use one language) on the drive in which Windows is installed. Out of courtesy to your customers, who may be computer novices that could get confused by insufficient disk space error messages during an install, you should always check and inform users if they do not have enough space to install DirectX.

Retrieve the Current Version of DirectX

Since many machines now have DirectX already installed, either by another application or by the manufacturer, you may want to check to see if the currently installed DirectX version is older than that shipped with your application. If the installed version is more current than the one you are shipping, you can skip DirectX installation altogether.

In order to retrieve the version number, the application must call the DirectXSetupGetVersion function. The DirectXSetupGetVersion function is defined as:

    function DirectXSetupGetVersion(

    var lpdwVersion: DWORD;                   // the version number

    var lpdwRevision: DWORD                   // the revision number

      : Integer;                              // returns non-zero if successful

The first parameter is a DWORD variable that will contain the major version number in the high-order word and the minor version number in the low-order word when the function returns. The second parameter is also a DWORD variable that will contain the release number in the high-order word and the build number in the low-order word. The minor version number reflects the “commercial” version of DirectX, and will be 6 for DirectX 6 or higher, 5 for DirectX 5, etc.

| Note: There was no version 4 of DirectX.

Set a Callback Function

If the developer wishes the DirectX installation to proceed using its standard, default behavior, this step can be skipped. However, in order to customize the behavior of the installation process, the application needs to inform DirectSetup that it should call a callback function during the installation process. This is accomplished by calling the DirectXSetupSetCallback function, which is defined as:

    function DirectXSetupSetCallback(

    Callback: TDSetup_Callback                   // pointer to the callback function

    ) : Integer;                                 // returns zero

Currently, this function only returns zero, whether it succeeded or failed. The only parameter for this function is a pointer to the callback function. This function will be called by the installation process at various times when certain events happen or the user needs to supply additional information. The callback function itself must be defined as:

    function TDSetup_Callback(

    Reason: DWORD;                              // reason flags

    MsgType: DWORD;                             // message type flags

    szMessage: PChar;                           // message string

    szName: PChar;                              // driver name string

    pInfo: Pointer                              // additional driver information

      : DWORD; stdcall;                         // returns MessageBox return values

We’ll examine this callback function in more detail below when we cover techniques for customizing the installation process.

Call the DirectXSetup Function

To begin the process of actually copying DirectX system files onto the hard drive and configuring Windows with the new components, we must call the DirectXSetup function. The DirectXSetup function is defined as:

    function DirectXSetup(

    hWnd: HWND;                                  // parent window handle

    lpszRootPath: PAnsiChar;                     // DirectX redistributables path

    dwFlags: DWORD                               // installation control flags

      : Integer;                                 // returns a DirectX error code

The first parameter is a handle to a window that will be used as the parent window for any dialog boxes that need to be displayed during the installation. The second parameter is the path for the location of the DirectX redistributable files. Setting this to nil causes DirectSetup to look for the files in the current directory, as described above.

The third parameter is set to a series of flags that indicate how DirectX is to be installed. This controls whether the entire DirectX system will be installed, or only certain parts. The available flags for this parameter are shown in Table A-1. The DirectSetup documentation recommends that applications perform a full install using the DSETUP_DIRECTX flag. However, an application could provide the user with a method to install only the run-time components or perhaps just audio and/or video drivers in the case of a malfunction or for troubleshooting purposes. Another very useful flag is DSETUP_TESTINSTALL, which runs through a test installation of DirectX but doesn’t actually replace any drivers or copy any run-time components to the system. Using this in conjunction with a callback function allows the developer to make a detailed list of drivers that will be replaced during the installation, which could then be presented to the user in a summary format before the actual installation process began.

Table A-1: DirectXSetup control flags
Flag | Description
--- | ---
DSETUP_DDRAWDRV | Installs display drivers only
DSETUP_DIRECTX | Performs a full installation of DirectX
DSETUP_DSOUNDDRV | Installs audio drivers only
DSETUP_DXCORE | Installs run-time components only
DSETUP_TESTINSTALL | Performs a test installation without installing files

This function can return a number of error codes that indicate various problems such as insufficient disk space or missing source files. However, the application should specifically watch out for the DSETUPERR_SUCCESS_RESTART return value. This indicates that the machine must be rebooted before DirectX functionality will be available. DirectSetup does not automatically inform the user of this, so your installation application will need to do the job. A return value of DSETUPERR_SUCCESS indicates that installation was successful and no reboot is necessary. See the DSetup.pas file (part of the JEDI DirectX headers) for a complete listing of error codes returnable by DirectXSetup.

#### Overriding Default Behavior

If the application did not specify a callback function, calling the DirectXSetup function will launch the installation of DirectX, and it will proceed to install DirectX drivers and components without any intervention from the user or the application. DirectSetup will provide a simple status window to the user, but this is the only feedback it outputs. The following illustration shows the default DirectSetup installation status box.

Figure A-1: Default DirectSetup status message

If any sort of error occurs, such as insufficient drive space, it will not display any message to the user, relying on the application to interpret the return value and display the appropriate message. It also will not ask the user for any sort of confirmation. If it encounters an unrecognized driver or other potential driver incompatibility problem, it simply skips the driver and returns success, without ever bothering the user. As mentioned before, this approach is taken so that the system is not left in an unusable state due to driver conflicts. However, this can lead to an unusable DirectX installation.

Therefore, it might be wise to provide a little more customized feedback to the user, especially if your application is to be widely distributed. As mentioned previously, we should set up a callback function using the DirectXSetupSetCallback function. For the sake of completeness (and so you don’t have to flip back and forth in this section), the callback function itself is defined as:

    function TDSetup_Callback(

    Reason: DWORD;                              // reason flags

    MsgType: DWORD;                             // message type flags

    szMessage: PChar;                           // message string

    szName: PChar;                              // driver name string

    pInfo: Pointer                              // additional driver information

      : DWORD; stdcall;                         // returns MessageBox return values

The first parameter contains one of several flags that indicate why the callback function was called. These flags are listed in Table A-2 below. As you can see, this callback function is called on several occasions, notably when an error has occurred or when DirectSetup is about to install DirectX drivers or components. Of particular interest is the DSETUP_CB_MSG_NOMESSAGE flag. This flag is sent to the callback function merely to provide a method for updating a status bar. When this flag is received, none of the other parameters contain any useful information, and the callback function should return immediately.

Table A-2: Reason flags
Flag | Description
--- | ---
DSETUP_CB_MSG_NOMESSAGE | Update pulse
DSETUP_CB_MSG_CANTINSTALL_UNKNOWNOS | The operating system cannot be determined, and DirectX can’t be installed
DSETUP_CB_MSG_CANTINSTALL_NT | Cannot install under Windows NT
DSETUP_CB_MSG_CANTINSTALL_BETA | Pre-release beta version of Windows 95 detected; cannot install DirectX
DSETUP_CB_MSG_CANTINSTALL_NOTWIN32 | 16-bit version of Windows detected; cannot install DirectX
DSETUP_CB_MSG_CANTINSTALL_WRONGLANGUAGE | The DirectX driver or component is not localized to the installed Windows language
DSETUP_CB_MSG_CANTINSTALL_WRONGPLATFORM | The DirectX driver or component is for another type of computer
DSETUP_CB_MSG_PREINSTALL_NT | DirectX is already installed on this version of NT
DSETUP_CB_MSG_ NOTPREINSTALLEDONNT | DirectX cannot be installed on this version of NT
DSETUP_CB_MSG_SETUP_INIT_FAILED | General setup failure
DSETUP_CB_MSG_INTERNAL_ERROR | An internal error has occurred
DSETUP_CB_MSG_CHECK_DRIVER_ UPGRADE | A driver is being considered for upgrade
DSETUP_CB_MSG_OUTOFDISKSPACE | Insufficient disk space to install all DirectX components
DSETUP_CB_MSG_BEGIN_INSTALL | Installation has begun
DSETUP_CB_MSG_BEGIN_INSTALL_ RUNTIME | Installation of DirectX run-time components has begun
DSETUP_CB_MSG_BEGIN_INSTALL_ DRIVERS | Installation of device drivers has begun
DSETUP_CB_MSG_FILECOPYERROR | An error occurred copying a file

The second and third parameters are used when a message should be presented to the user. These values are intended to be used with the MessageBox function, with the MsgType parameter indicating the flags to be used with MessageBox, and the szMessage parameter containing the text of the message to be presented. In any case when MsgType is not zero, the callback function should return a value commensurate with the values returned by the MessageBox function for the flags indicated in the MsgType parameter. Ideally, the callback function will just pass all of this to the MessageBox function, in turn passing its return value back as the return value for the callback. However, the application can display any form of dialog box desired with any type of feedback desired, as long as the callback return value matches that which would be returned by the MessageBox function for the given flags in the MsgType parameter. The sole exception to this rule is that the function can always return zero, in which case DirectSetup will act in a default manner as if no callback function had been specified.

In the case where MsgType is zero, the DirectSetup documentation states that we should always return IDOK. The IDOK return value, in this case, will suppress the default status window displayed by DirectSetup. However, if we return zero when MsgType is zero, the default status dialog box will be displayed. This allows us to display our own status indicator or use DirectSetup’s default status indicator as desired.

| Caution: It is possible through the use of the callback function to provide default responses and install DirectX without any intervention from the user, or even without the user being aware of the installation. This is very bad programming practice, and can potentially lead to an incorrect installation. Always inform the user that DirectX is being installed, and especially give the user the appropriate feedback and options when drivers are being upgraded.

#### Verification of Driver Upgrade

The most interesting of all of the reason flags is DSETUP_CB_MSG_CHECK_ DRIVER_UPGRADE. This indicates that DirectX is considering upgrading a driver, and verification from the user is recommended. The MsgType and szMessage parameters will most certainly contain values indicating the type of message box to display as well as a text description of the problem and recommended user action. The fourth parameter, szName, will contain the name of the driver being considered for upgrade.

The final parameter, pInfo, is a pointer to a TDSetup_CB_UpgradeInfo structure that contains additional information about the driver in question. This simple structure is defined as:

    TDSetup_CB_UpgradeInfo = record

      UpgradeFlags: DWORD;                   // driver upgrade information flags

    end;

The only member of this structure, UpgradeFlags, can contain one or more flags from Table A-3 which indicate the status of the upgrade. Of particular interest are the DSETUP_CB_UPGRADE_FORCE and DSETUP_CB_UPGRADE_KEEP flags. DSETUP_CB_UPGRADE_FORCE indicates that Windows may not function correctly unless the driver is upgraded. In this case, DirectSetup will upgrade the driver regardless of the value returned by the callback function. The DSETUP_CB_UPGRADE_KEEP flag, on the other hand, indicates that Windows may not function correctly if the driver is upgraded. In this case, Direct Setup will not upgrade the driver, again regardless of the return value. Other flags indicate the type of driver being upgraded or other warnings that the user should take into account when deciding to allow or disallow the upgrade.

Table A-3: Driver upgrade information flags
Flag | Description
--- | ---
DSETUP_CB_UPGRADE_KEEP | The system may fail if the driver is upgraded
DSETUP_CB_UPGRADE_SAFE | This driver is safe to upgrade; upgrading recommended
DSETUP_CB_UPGRADE_FORCE | The system may fail if the driver is not upgraded
DSETUP_CB_UPGRADE_UNKNOWN | Existing device driver unrecognized; upgrading is not recommended
DSETUP_CB_UPGRADE_HASWARNINGS | Upgrading the driver may affect one or more programs; upgrading is not recommended
DSETUP_CB_UPGRADE_CANTBACKUP | Existing system components cannot be backed up, and therefore cannot subsequently be restored
DSETUP_CB_UPGRADE_DEVICE_ACTIVE | The device driver is currently in use
DSETUP_CB_UPGRADE_DEVICE_DISPLAY | This is a display device driver
DSETUP_CB_UPGRADE_DEVICE_MEDIA | This is a media device driver (typically an audio device)

The following example demonstrates how to use the DirectXSetup function in conjunction with a callback function to suppress the default status dialog box as well as provide custom feedback information to the user. It also illustrates how to perform both a test installation as well as a full installation of all DirectX components.

Listing A-1: Installing DirectX

    interface

       .

       .

       .

      {declare the callback function}

      function DSetupCallback(Reason: DWORD; MsgType: DWORD;

          szMessage: PChar; szName: PChar; pInfo: Pointer) : DWORD; stdcall;

       .

       .

       .

    implementation

    {this function is called numerous times throughout the DirectX

     setup process}

    function DSetupCallback(Reason: DWORD; MsgType: DWORD;

          szMessage: PChar; szName: PChar; pInfo: Pointer) : DWORD; stdcall;

    begin

      {if the MsgType parameter is 0, return IDOK, otherwise let’s

       display a message box and return the appropriate value}

      if MsgType = 0 then

        Result := IDOK    // setting this to 0 displays the standard status box

      else

        Result := MessageBox(frmDXSetup.Handle, szMessage, ‘DirectX Setup’,MsgType);

      {display a message in our list box indicating the reason

       why the callback function was called}

      case Reason of

        DSETUP_CB_MSG_NOMESSAGE :

          frmDXSetup.lbxStatus.Items.Add(‘NoMessage Pulse (could display +

                                         a progression indicator on this message)’);

        DSETUP_CB_MSG_CANTINSTALL_UNKNOWNOS :

          frmDXSetup.lbxStatus.Items.Add(‘Can’‘t install, unknown OS’);

        DSETUP_CB_MSG_CANTINSTALL_NT :

          frmDXSetup.lbxStatus.Items.Add(‘Can’‘t install to versions of Windows +

                                         NT prior to 4.0’);

        DSETUP_CB_MSG_CANTINSTALL_BETA :

          frmDXSetup.lbxStatus.Items.Add(‘Pre-release beta version of Windows 95 +

                                         detected, cannot install.’);

        DSETUP_CB_MSG_CANTINSTALL_NOTWIN32 :

          frmDXSetup.lbxStatus.Items.Add(‘DirectX is not compatible with Windows +

                                         3.x’);

        DSETUP_CB_MSG_CANTINSTALL_WRONGLANGUAGE :

          frmDXSetup.lbxStatus.Items.Add(‘This version of DirectX not localized to+

                                    the current language configured for Windows.’);

        DSETUP_CB_MSG_CANTINSTALL_WRONGPLATFORM :

          frmDXSetup.lbxStatus.Items.Add(‘DirectX component or driver incompatible+

                                          with current hardware.’);

        DSETUP_CB_MSG_PREINSTALL_NT :

          frmDXSetup.lbxStatus.Items.Add(‘DirectX already installed on this +

                                         version of Windows NT.’);

        DSETUP_CB_MSG_NOTPREINSTALLEDONNT :

          frmDXSetup.lbxStatus.Items.Add(‘Cannot install DirectX on this version +

                                         of Windows NT.’);

        DSETUP_CB_MSG_SETUP_INIT_FAILED :

          frmDXSetup.lbxStatus.Items.Add(‘Setup of the DirectX component or +

                                         device driver has failed.’);

        DSETUP_CB_MSG_INTERNAL_ERROR :

          frmDXSetup.lbxStatus.Items.Add(‘An internal error has occurred and +

                                         DirectX setup has failed.’);

        {here, DirectSetup is considering upgrading a driver. the user will have

         already been asked for confirmation above, but here we can see how

         we can query the pInfo parameter for more information about the

         upgrade}

        DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE  :

          begin

            frmDXSetup.lbxStatus.Items.Add(‘Upgrading driver: ’+szName);

            frmDXSetup.lbxStatus.Items.Add(szMessage);

            {determine and display upgrade information}

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_KEEP) = DSETUP_CB_UPGRADE_KEEP then

              frmDXSetup.lbxStatus.Items.Add(‘Current driver cannot be upgraded’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_SAFE) = DSETUP_CB_UPGRADE_SAFE then

              frmDXSetup.lbxStatus.Items.Add(‘Driver recognized, upgrade is safe’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_FORCE) = DSETUP_CB_UPGRADE_FORCE then

              frmDXSetup.lbxStatus.Items.Add(‘Upgrade must be performed’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_UNKNOWN) = DSETUP_CB_UPGRADE_UNKNOWN then

              frmDXSetup.lbxStatus.Items.Add(‘Unknown driver’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_HASWARNINGS) = DSETUP_CB_UPGRADE_HASWARNINGS then

              frmDXSetup.lbxStatus.Items.Add(‘Upgrade is not recommended’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_CANTBACKUP) = DSETUP_CB_UPGRADE_CANTBACKUP then

              frmDXSetup.lbxStatus.Items.Add(‘Driver cannot be backed up, +

                                             restoration impossible’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_DEVICE_ACTIVE) =

                DSETUP_CB_UPGRADE_DEVICE_ACTIVE then

              frmDXSetup.lbxStatus.Items.Add(‘Driver being upgraded is currently +

                                             in use’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_DEVICE_DISPLAY) =

                DSETUP_CB_UPGRADE_DEVICE_DISPLAY then

              frmDXSetup.lbxStatus.Items.Add(‘Driver is a display driver’);

            if (TDSetup_CB_UpgradeInfo(pInfo^).UpgradeFlags and

                DSETUP_CB_UPGRADE_DEVICE_MEDIA) =

                DSETUP_CB_UPGRADE_DEVICE_MEDIA then

              frmDXSetup.lbxStatus.Items.Add(‘Driver is a sound driver’);

          end;

        DSETUP_CB_MSG_OUTOFDISKSPACE :

          frmDXSetup.lbxStatus.Items.Add(‘Out of disk space’);

        DSETUP_CB_MSG_BEGIN_INSTALL :

          frmDXSetup.lbxStatus.Items.Add(‘DirectX installation commencing’);

        DSETUP_CB_MSG_BEGIN_INSTALL_RUNTIME :

          frmDXSetup.lbxStatus.Items.Add(‘Installing DirectX run-time components’);

        DSETUP_CB_MSG_BEGIN_INSTALL_DRIVERS :

          frmDXSetup.lbxStatus.Items.Add(‘Installing DirectX device drivers’);

        DSETUP_CB_MSG_FILECOPYERROR :

          frmDXSetup.lbxStatus.Items.Add(‘An error occurred trying to copy a file’);

      end;

    end;

    procedure TfrmDXSetup.FormCreate(Sender: TObject);

    var

      Version, Revision: DWORD;

    begin

      {retrieve the version and revision number for the currently

       installed DirectX}

      DirectXSetupGetVersion(Version, Revision);

      {display the version and revision numbers}

      lblVersion.Caption := Format(‘%d.%d.%d.%d (Commercial Version: %d)’,

                                   [HiWord(Version), LoWord(Version),

                                    HiWord(Revision), LoWord(Revision),

                                    LoWord(Version)]);

      {set up our callback function}

      DirectXSetupSetCallback(@DSetupCallback);

    end;

    procedure TfrmDXSetup.btnTestInstallClick(Sender: TObject);

    begin

      {clear the feedback list box}

      lbxStatus.Items.Clear;

      { — we’ll use the ErrorString function located in the DSetup.pas unit  —

        — to retrieve a text string describing the success code returned by  —

        — DirectXSetup. we should specifically check to see if the system    —

        — must be rebooted.                                                  — }

      {perform a test installation}

      lbxStatus.Items.Add(ErrorString(DirectXSetup(Handle,nil,DSETUP_TESTINSTALL)));

      {indicate that installation has finished}

      lbxStatus.Items.Add(‘DirectSetup finished’);

    end;

    procedure TfrmDXSetup.btnRealInstallClick(Sender: TObject);

    begin

      {clear the feedback list box}

      lbxStatus.Items.Clear;

      {this time, we’ll perform a full installation of DirectX. we’re still

       using the ErrorString function as described above}

      lbxStatus.Items.Add(ErrorString(DirectXSetup(Handle, nil, DSETUP_DIRECTX)));

      {indicate that installation has finished}

      lbxStatus.Items.Add(‘DirectSetup finished’);

    end;

    end.

Figure A-2: The customized DirectSetup feedback

### Summary

In this appendix, we discussed how DirectSetup can automate the task of installing DirectX onto an end user’s machine. We examined various installation methods, including the standard, no-frills installation as well as a highly customized installation that overrides the default behaviors of DirectSetup. We also discussed retrieving the version of the currently installed DirectX, as well as some issues with redistribution of DirectX files. When writing an installation program that uses DirectSetup to install DirectX components, it is important to keep these points in mind:

  • If the version of DirectX installed on the target machine is equal to or more current than the version shipping with your application, there is no need to install DirectX.
  • Only those files located in the Redist directory of the DirectX SDK are redistributable with applications. Refer to the DirectX SDK EULA.txt file for more information, or visit http://www.microsoft.com/directx/developer/downloads/default.asp.
  • The only change to the redistributable files that can be made is that languages unsupported by your application can be left out. This can dramatically reduce the storage requirements for the DirectX redistributable file set.
  • Redistributables, and in particular the dsetup.dll, dsetup16.dll, and dsetup32.dll, must be located in the same directory as the installation program.
  • The minimum required disk space for DirectX is 15 MB, if you are installing only one language version.
  • The minor version number returned by DirectXSetupGetVersion reflects the commercial version of DirectX.
  • The DirectXSetup function can perform a full installation of all DirectX components, an installation of specific components (such as run-time components or drivers), or a test installation. The test installation acts like a real installation, except it makes no changes to the system.
  • By default, DirectSetup does not provide any feedback to the user other than a status dialog box, nor does it retrieve confirmation from the user concerning driver replacement. If any driver upgrade would cause any type of problem, it will simply be skipped and the DirectXSetup function will return success, with no indication to the user of any problems encountered.
  • A callback function can be specified, which will be called by DirectSetup at various times throughout the installation process. This allows the application to override default behavior and provide customized feedback to the user.
  • If the MsgType parameter of the callback function is anything other than zero, it should return a value commensurate with that returned by the MessageBox function.
  • If the MsgType parameter contains zero, the callback function should return a value of IDOK. However, returning a value of zero causes DirectSetup to perform the default action.

Previous | Table of Contents | Next

Products | Contact Us | About Us | Privacy | Ad Info | Home Use of this site is subject to certain Terms & Conditions, Copyright © 1996-2000 EarthWeb Inc. All rights reserved. Reproduction whole or in part in any form or medium without express written permission of EarthWeb is prohibited. Read EarthWeb's privacy statement.