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.

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.