IDirectPlayVoiceTest::CheckAudioSetup Method

Runs the Audio Setup Wizard on the specified devices. This wizard runs a series of tests on the devices to determine if they are capable of full duplex audio and to ensure that the microphone is plugged in and working correctly on the capture device.

Syntax

HRESULT CheckAudioSetup(      
    const GUID *pguidPlaybackDevice,
    const GUID *pguidCaptureDevice,
    HWND hwndParent,
    DWORD dwFlags
);

Parameters

pguidPlaybackDevice

[in] Pointer to the globally unique identifier (GUID) that identifies the playback device to test. If NULL is passed for this parameter, Microsoft® DirectPlay® Voice tests the system default playback device defined by Microsoft DirectSound®. You can also pass one of the DirectSound default GUIDs:

DSDEVID_DefaultPlayback

The system default playback device.

DSDEVID_DefaultVoicePlayback

The default voice playback device.

pguidCaptureDevice

[in] Pointer to the GUID that identifies the capture device to test. If NULL is passed for this parameter, DirectPlay Voice tests the system default capture device defined by DirectSound. You can also pass one of the DirectSound default GUIDs:

DSDEVID_DefaultCapture

The default system capture device. You can also specify this device by passing a NULL pointer in the device GUID parameter.

DSDEVID_DefaultVoiceCapture

The default voice communications capture device. Typically, this is a secondary device such as a USB headset with microphone.

hwndParent

[in] The test wizard invoked by this method is modal. If the calling application has a window that should be the parent window of the wizard, it should pass a handle to that window in this parameter. If the calling application does not have a window, it can pass NULL. If the DVFLAGS_QUERYONLY flag is specified, this parameter is not used and the application can pass NULL.

dwFlags

[in] Flags. The following flags can be set.

DVFLAGS_QUERYONLY

Audio setup is not run. Instead, the method checks the registry to see if the devices have been tested. If the devices have not been tested, the method returns DVERR_RUNSETUP. If the devices have been tested, the method returns DV_FULLDUPLEX if the devices support full duplex audio, or DV_HALFDUPLEX if the devices do not support full duplex audio.

DVFLAGS_ALLOWBACK

Passing this flag enables the Back button on the wizard's Welcome page. If the user clicks the Back button on the Welcome page, the wizard exits, and IDirectPlayVoiceTest::CheckAudioSetup returns DVERR_USERBACK.

Return Value

Returns DV_OK, DV_FULLDUPLEX, DV_HALFDUPLEX if successful, or one of the following error values.

DVERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DVERR_RUNSETUP	The specified audio configuration has not been tested. Call the IDirectPlayVoiceTest::CheckAudioSetup method.
DVERR_INVALIDDEVICE	The specified device is invalid.

Remarks

This method contains user interface (UI) elements and displays dialog boxes. If the DVFLAGS_QUERYONLY flag is specified, the tests are not actually run and no UI is raised. Instead, the registry is checked to determine the results of a previous test of these devices.

If the user cancels the wizard, the IDirectPlayVoiceTest::CheckAudioSetup call returns DVERR_USERCANCEL. The calling application can then handle the situation appropriately. For example, in DirectPlay Voice part of the gaming options control panel application, if the user clicks Cancel, the dialog box displays a message indicating that voice cannot be used because the wizard has been canceled.

This method might return DVERR_INVALIDDEVICE if the device specified does not exist. Also, if you specify the default device and this method still returns this error, then there are no sound devices on the system.