DVSOUNDDEVICECONFIG Structure

Used to set and retrieve information about the sound device configuration and cannot be changed once a connection has been made. After a connection is made, you can retrieve the current sound device configuration by calling IDirectPlayVoiceClient::GetSoundDeviceConfig.

Syntax

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    GUID guidPlaybackDevice;
    LPDIRECTSOUND lpdsPlaybackDevice;
    GUID guidCaptureDevice;
    LPDIRECTSOUNDCAPTURE lpdsCaptureDevice;
    HWND hwndAppWindow;
    LPDIRECTSOUNDBUFFER lpdsMainBuffer;
    DWORD dwMainBufferFlags;
    DWORD dwMainBufferPriority;
} DVSOUNDDEVICECONFIG, *LPDVSOUNDDEVICECONFIG, *PDVSOUNDDEVICECONFIG;

Members

dwSize

Must be set the to size of this structure, in bytes, before using this structure.

dwFlags

A combination of the following flags.

DVSOUNDCONFIG_AUTOSELECT

Tells Microsoft® DirectPlay® Voice to attempt to automatically select (or un-mute) the microphone line in the mixer for the specified recording device.

DVSOUNDCONFIG_HALFDUPLEX

Tells DirectPlay Voice to initialize itself in half-duplex mode. In half-duplex mode no recording takes place. If the initialization of the sound system fails in full-duplex mode, this flag will be set by the system.

DVSOUNDCONFIG_NORMALMODE

Tells DirectPlay Voice to use Microsoft DirectSound® Normal Mode when initializing the DirectSound object. If this flag is not specified, the DirectSound object is initialized with DirectSound Priority Mode. See documentation for IDirectSound8::SetCooperativeLevel for more information. If a valid DirectSound object is specified in the lpdsPlaybackDevice member, this flag is ignored.

DVSOUNDCONFIG_SETCONVERSIONQUALITY

Enables better quality audio at the expense of higher CPU usage.

DVSOUNDCONFIG_NORECVOLAVAILABLE

Set by DirectPlay Voice if there are no volume controls available on the recording device you specified. You cannot set this flag.

DVSOUNDCONFIG_NOFOCUS

The voice application will never go out of focus. In other words, the application will never release the sound capture device. Use of this flag is not recommended.

DVSOUNDCONFIG_STRICTFOCUS

The voice application will lose focus whenever its window is not the foreground window.

guidPlaybackDevice

When this structure is used in the IDirectPlayVoiceClient::GetSoundDeviceConfig method, this member contains the actual device globally unique identifier (GUID) used for playback.

When this structure is used in the IDirectPlayVoiceClient::Connect method, this member specifies the GUID of the device used for playback. This must be specified even if the lpdsPlaybackDevice member is used. You can also specify the following default GUIDs provided by DirectSound.

DSDEVID_DefaultPlayback

The system default playback device.

DSDEVID_DefaultVoicePlayback

The default voice playback device.

lpdsPlaybackDevice

When this structure is used in the IDirectPlayVoiceClient::Connect method, this member specifies the DirectSound object you want DirectPlay Voice to use for playback. The GUID specified in guidPlaybackDevice must match the one used to create the device specified by this parameter. If you used NULL when specifying the device when you created your DirectSound object, pass DSDEVID_DefaultPlayback for this member.

When this structure is used in the IDirectPlayVoiceClient::GetSoundDeviceConfig method, this member contains a pointer to the DirectSound object being used by DirectPlay Voice. This will either be a pointer to the object specified when Connect was called or a pointer to a newly created and initialized DirectSound object. If you want to use this DirectSound object, you must store the pointer and increment the reference count by calling AddRef on the DirectSound interface.

guidCaptureDevice

When this structure is used in IDirectPlayVoiceClient::Connect method, this member specifies the GUID of the device used for capture. This must be specified even if the lpdsCaptureDevice member is used. If you used NULL when specifying the device when you created your DirectSoundCapture object, pass DSDEVID_DefaultCapture for this member.

When this structure is used in the IDirectPlayVoiceClient::GetSoundDeviceConfig method, this member will contain the actual device GUID used for capture.

lpdsCaptureDevice

When this structure is used in the IDirectPlayVoiceClient::Connect method, this member specifies the DirectSound object you want DirectPlay Voice to use for capture. The GUID specified in guidCaptureDevice must match the one used to create the device specified by this parameter. If you want to have DirectPlay Voice create the DirectSoundCapture object for you, specify NULL for this member.

When this structure is used in the IDirectPlayVoiceClient::GetSoundDeviceConfig method, this member contains a pointer to the DirectSoundCapture object being used by DirectPlay Voice. This will either be a pointer to the object specified when Connect was called or a pointer to a newly created and initialized DirectSoundCapture object. If you want to use this DirectSoundCapture object, you must store the pointer and increment the reference count by calling AddRef on the IDirectSoundCapture8 interface. If the DirectPlay Voice object is operating in half duplex mode, this member will be NULL.

hwndAppWindow

Must be set to the handle of the window that will be used to determine focus for sound playback. See IDirectSound8::SetCooperativeLevel for information about DirectSound focus. If you do not have a window to use for focus, use GetDesktopWindow to use the desktop window.

lpdsMainBuffer

Pointer to an IDirectSoundBuffer8 interface, which is used to create the DirectPlay Voice main buffer. This can be either NULL or a user-created DirectSound buffer. If this member is set to NULL, DirectPlay Voice will create a buffer for the main voice buffer. If users specify a buffer here, DirectPlay Voice will use their buffer for the main voice buffer. User-created buffers have the following restrictions.

• The buffer must be 22 kilohertz, 16-bit, Mono format.
• The buffer must be at least 1 second in length.
• The buffer must have been created with the DSBCAPS_GETCURRENTPOSITION2 and DSBCAPS_CTRL3D flags.
• The buffer must not be a primary buffer.
• The buffer must not be playing when it is passed to the DirectPlay Voice software.
• The buffer must not be locked when it is passed to the DirectPlay Voice software.

dwMainBufferFlags

Passed directly to the dwFlags parameter of the IDirectSoundBuffer8::Play method when Play is called for the main buffer. The DSBPLAY_LOOPING flag is automatically added to this field. See the documentation on IDirectSoundBuffer8::Play for details. This parameter must be 0 if the lpdsMainBuffer member of this structure is NULL.

dwMainBufferPriority

Passed directly to the dwPriority parameter of the IDirectSoundBuffer8::Play method when Play is called on the main buffer. See documentation for IDirectSoundBuffer8::Play for more information. This member must be set to 0 if lpdsMainBufferDesc is NULL.

Remarks

Note  Applications should set the DVSOUNDCONFIG_NOFOCUS or DVSOUNDCONFIG_STRICTFOCUS flags only when strictly necessary. Instead, you should normally use the default behavior that results when neither flag is set.

Structure Information

Header	dvoice8.h
Minimum operating systems	Windows 98