WIDM_OPEN

The WIDM_OPEN message is sent to a waveform input driver to request it to open an instance of a specified device.

Parameters

uDeviceId

Device identifier (0, 1, 2, and so on) for the target device.

uMsg

WIDM_OPEN

dwUser

Pointer to location to receive device instance identifier.

dwParam1

Pointer to a WAVEOPENDESC structure, containing the client’s device handle, notification target, and instance ID.

dwParam2

Contains flags. The following flags are defined:

Flag	Definition
CALLBACK_EVENT	Indicates the dwCallback member of WAVEOPENDESC is an event handle.
CALLBACK_FUNCTION	Indicates the dwCallback member of WAVEOPENDESC is the address of a callback function.
CALLBACK_TASK	Indicates the dwCallback member of WAVEOPENDESC is a task handle.
CALLBACK_WINDOW	Indicates the dwCallback member of WAVEOPENDESC is a window handle.
WAVE_FORMAT_DIRECT	Data compression/decompression operations should take place in hardware. See Comments section below.
WAVE_FORMAT_QUERY	The driver should indicate whether or not it supports the specified format. See Comments section below.

Return Value

The driver should return MMSYSERR_NOERROR if the operation succeeds. Otherwise it should return one of the MMSYSERR or WAVERR error codes defined in mmsystem.h. See waveInOpen return values in the Win32 SDK.

Comments

A client sends the WIDM_OPEN message by calling the user-mode driver’s widMessage entry point, passing the specified parameters.

Typically, user-mode drivers connect to kernel-mode drivers by calling CreateFile, specifying the MS-DOS device name of one of the kernel-mode driver’s devices.

The driver assigns a device instance identifier and returns it in the location pointed to by dwUser. The driver can expect to receive this value as the dwUser input argument to all other widMessage messages.

The driver determines the number of clients it allows to use a particular device. If a device is opened by the maximum number of clients, it returns MMSYSERR_ALLOCATED for subsequent open requests.

The WAVE_FORMAT_DIRECT flag is meant for use with a wave mapper. If the flag is set in dwParam2, the driver should not call the Audio Compression Manager to handle compression/decompression operations; the caller wants the hardware to perform these operations directly. If the hardware is not capable of performing compression/decompression operations, the driver should return MMSYSERR_NOTSUPPORTED when WAVE_FORMAT_DIRECT is set.

If the WAVE_FORMAT_QUERY flag is set in dwParam2, the driver should not open the device, but should instead determine whether it supports the format specified by the WAVEOPENDESC structure’s lpFormat member. If the driver supports the requested format, it should return MMSYSERR_NOERROR. Otherwise it should return WAVERR_BADFORMAT.

If the open operation succeeds, the driver should send the client a WIM_OPEN message by calling the DriverCallback function.

For additional information, see Transferring Waveform Input Data.