For an application that is simply going to play sounds through the user's preferred playback device, you don't need to enumerate the available devices. When you create the DirectSound object with NULL as the device identifier, the interface will automatically be associated with the default device if one is present. (If no device driver is present, the call to the DirectSoundCreate function fails.)

However, if you are looking for a particular kind of device, wish to offer the user a choice of devices, or need to work with two or more devices, you must get DirectSound to enumerate the devices available on the system.

Enumeration serves three purposes:

• Reports what hardware is available.
• Supplies a globally unique identifier (GUID) for each device.
• Allows you to initialize DirectSound for each device as it is enumerated, so that you can check the capabilities of the device.

To enumerate devices you must first set up a callback function that will be called each time DirectSound finds a device. You can do anything you want within this function, and you can give it any name, but you must declare it in the same form as DSEnumCallback, a prototype in this documentation. The callback function must return TRUE if enumeration is to continue, or FALSE otherwise (for instance, after finding a device with the capabilities you need).

The following callback function, extracted from Dsenum.c in the DSShow3D tool, adds information about each enumerated device to a combo box. Note that the first three parameters are supplied by the device driver. The fourth parameter is passed on from the DirectSoundEnumerate function.

BOOL CALLBACK DSEnumProc(LPGUID lpGUID, 
                         LPCTSTR lpszDesc,
                         LPCTSTR lpszDrvName, 
                         LPVOID lpContext )
{
    HWND   hCombo = *(HWND *)lpContext;
    LPGUID lpTemp = NULL;
 
    if ( lpGUID != NULL )
    {
        if (( lpTemp = malloc( sizeof(GUID))) == NULL )
        return( TRUE );
 
        memcpy( lpTemp, lpGUID, sizeof(GUID));
    }
 
    ComboBox_AddString( hCombo, lpszDesc );
    ComboBox_SetItemData( hCombo,
                ComboBox_FindString( hCombo, 0, lpszDesc ),
                lpTemp );
    return( TRUE );
}
 

The enumeration is set in motion when the dialog containing the combo box is initialized:

if FAILED(DirectSoundEnumerate((LPDSENUMCALLBACK)DSEnumProc,
        &hCombo))
{
    EndDialog( hDlg, TRUE );
    return( TRUE );
}
 

In this case the address of the combo box handle is passed into DirectSoundEnumerate, which in turn passes it to the callback function. This parameter can be any 32-bit value that you want to have access to within the callback.

For an application that is simply going to play sounds through the user's preferred playback device, you don't need to enumerate the available devices. When you create the DirectSound object by passing an empty string as the device identifier, the object will automatically be associated with the default device if one is present. (If no device driver is present, the call to the DirectX7.DirectSoundCreate method fails.)

However, if you are looking for a particular kind of device, wish to offer the user a choice of devices, or need to work with two or more devices, you must get DirectSound to enumerate the devices available on the system.

Enumeration serves three purposes:

• Reports what hardware is available.
• Supplies a globally unique identifier (GUID) for each device.
• Allows you to initialize DirectSound for each device as it is enumerated, so that you can check the capabilities of the device.

To enumerate devices you must first call the DirectX7.GetDSEnum method to create a DirectSoundEnum object. The returned DirectSoundEnum object contains a collection of DirectSound devices. You then call the DirectSoundEnum.GetCount method to determine the number of available devices. Information on each device is then obtained by calling the DirectSoundEnum.GetDescription, DirectSoundEnum.GetGuid, and DirectSoundEnum.GetName methods and passing the specified device in the collection as the index argument.