SOUND_DEVICE_INIT

typedef struct {

PCWSTR LeftVolumeName, RightVolumeName;

ULONG DefaultVolume;

ULONG Type;

ULONG DeviceType;

char Key[4];

PCWSTR PrototypeName;

PIO_DPC_ROUTINE DeferredRoutine;

SOUND_EXCLUDE_ROUTINE *ExclusionRoutine;

SOUND_DISPATCH_ROUTINE *DispatchRoutine;

SOUND_DISPATCH_ROUTINE *DevCapsRoutine;

SOUND_HW_SET_VOLUME_ROUTINE *HwSetVolume;

ULONG IoMethod;

} SOUND_DEVICE_INIT;

The SOUND_DEVICE_INIT structure associates driver dispatch routines with a driver object. A SOUND_DEVICE_INIT structure must be defined for each logical input or output device. The structure's definition is in devices.h.

LeftVolumeName

Registry key value name used when storing the left channel volume in the registry. Used with SoundSaveDeviceVolume.

RightVolumeName

Registry key value name used when storing the right channel volume in the registry. Used with SoundSaveDeviceVolume.

DefaultVolume

Initial volume setting to use during installation. Required for devices with mixers.

Type

Type of device. SoundCreateDevice passes this value to IoCreateDevice. The following values, defined in ntddk.h, should be used.

DeviceType

Type of device, used within soundlib.lib and drvlib.lib. The following values, defined in soundcfg.h, are accepted.

Key

For debugging purposes. Code in soundlib.lib copies this four-character string value into the device's LOCAL_DEVICE_INFO structure.

PrototypeName

Prototype to use for creating a device object name. Unless the SOUND_CREATION_NO_NAME_RANGE flag is specified as a SoundCreateDevice parameter, SoundCreateDevice appends a sequential number, starting with zero, to this name.

If you are using mmdrv.dll as your user-mode driver, then you must use the prototype name that mmdrv.dll recognizes for the device. The names recognized by mmdrv.dll are predefined and their string IDs can be referenced using the following names.

If you are using a customized user-mode driver, you cannot use the predefined names. For example, in the SOUND_DEVICE_INIT structures for the kernel-mode driver sndblst.sys, predefined names are used for MIDI devices but not for waveform, auxiliary, or mixer devices. The result is that mmdrv.dll handles user-mode MIDI operations, and sndblst.dll handles all others.

DeferredRoutine

Pointer to a deferred procedure call (DPC) routine, which SoundCreateDevice passes to IoInitializeDpcRequest.

If the device object does not support interrupts, this member must be NULL. For drivers using soundlib.lib, specify one of the following DPC routines.

ExclusionRoutine

Pointer to a mutual exclusion function, called from within soundlib.lib when it is necessary to acquire or release a mutex for the device. To understand under what circumstances this function is called, see the soundlib.lib source code, included with this DDK. The function type is SOUND_EXCLUDE_ROUTINE.

DispatchRoutine

Pointer to a function that serves as a dispatcher for IRP function codes received by the driver. Functions supplied by soundlib.lib are as follows:

The function type is SOUND_DISPATCH_ROUTINE. The specified function is called by SoundDispatch.

DevCapsRoutine

Pointer to a driver-defined function that returns device capabilities.

The function type is SOUND_DISPATCH_ROUTINE. The specified function is called by the dispatcher pointed to by the DispatchRoutine member, when the dispatcher receives IRP_MJ_DEVICE_CONTROL with an accompanying request for device capabilities. Capabilities for waveform, MIDI, and auxiliary devices are written into the IRP at Irp->AssociatedIrp.SystemBuffer, in the form of either a WAVEINCAPS, WAVEOUTCAPS, MIDIINCAPS, MIDIOUTCAPS, or AUXCAPS capabilities structure. (These structures are defined in mmsystem.h and described in the Win32 SDK.)

Note: When filling in the szPname member of the capabilities structure, remember the following:

·If your user-mode driver is mmdrv.dll, you must call InternalLoadString to translate string IDs into strings, and return the strings in the szPname member.

·If your user-mode driver makes use of drvlib.lib, just return the string IDs in the szPname member. Code in drvlib.lib calls InternalLoadString.

For mixer devices only, the following rules apply:

·Capabilities are written into the IRP at Irp->AssociatedIrp.SystemBuffer, in the form of a MIXER_DD_CONFIGURATION_DATA structure (defined in ntddmix.h). Code in drvlib.lib calls the capabilities function only when the device is being initialized. It stores the MIXER_DD_CONFIGURATION_DATA structure contents and returns them to a client, in a MIXERCAPS structure, when requested.

·The capabilities function is called twice (and only twice). The first time, it must only return the size of the capabilities information. The second time it is called, the function returns the capabilities information as a MIXER_DD_CONFIGURATION_DATA structure and a set of associated structures.

As an aid to understanding these special rules, see the mixer capabilities function, SoundMixerDumpConfiguration, provided in sndblst.sys, in src\mmedia\sndblst\driver\mixer.c.

HwSetVolume

Pointer to a driver-supplied function that sets the volume for the device. The function type is SOUND_HW_SET_VOLUME_ROUTINE.

The specified function is called by the dispatcher pointed to by the DispatchRoutine member, when the dispatcher receives IRP_MJ_DEVICE_CONTROL with an accompanying request to set the volume.

For devices without volume setting capabilities, use the SoundNoVolume function. Also use SoundNoVolume for devices that include mixer hardware, because drivers for these devices include a MIXER_INFO structure, and volume is controlled by a routine pointed to by that structure's HwSetControlData member.

IoMethod

Specifies whether the Windows NT I/O Manager should use direct I/O or buffered I/O for data transfers. Audio drivers should specify this value as shown in the following table.

For a discussion of direct I/O and buffer I/O methods, refer to the Kernel-Mode Drivers Design Guide.

Comments

The SOUND_DEVICE_INIT structure's address is passed to SoundCreateDevice. The structure must not be freed and must be nonpaged, because SoundCreateDevice does not copy it.

You must initialize all structure members before calling SoundCreateDevice. The LeftVolumeName, RightVolumeName, and DefaultVolume members can be initialized to NULL, NULL, and 0, respectively.