ACMDM_STREAM_OPEN

The ACMDM_STREAM_OPEN message requests an ACM driver to either open a conversion stream or indicate whether the specified conversion is supported.

Parameters

dwDriverID

Driver instance identifier. This is the value returned by the driver in response to the ACM_Open function.

hDriver

Driver handle.

uMsg

ACMDM_STREAM_OPEN

lParam1

Pointer to an ACMDRVSTREAMINSTANCE structure.

lParam2

Not used.

Return Value

The driver should return MMSYSERR_NOERROR if the operation succeeds. Otherwise it should return one of the MMSYSERR error codes defined in Mmsystem.h, or one of the ACMERR error codes defined in Msacm.h. If a specified conversion is not supported, the driver should return ACMERR_NOTPOSSIBLE.

Comments

The ACM (WAVEAPI.DLL) sends the ACMDM_STREAM_OPEN message by calling the ACM driver's ACM_IOControl() entry point via DeviceIoControl(). The ACM sends this message when an application calls the acmStreamOpen function, which is described in the Win32 SDK.

All ACM drivers that provide stream conversions must support this message. For more information about stream conversions, see Converting Data Streams in the Windows NT DDK.

If the client has specified the ACM_STREAMOPENF_QUERY flag (contained in the ACMDRVSTREAMINSTANCE structure's fdwOpen member), then the driver should not open a stream instance. It should return MMSYSERR_NOERROR if the conversion is possible, and MMSYSERR_NOTPOSSIBLE otherwise.

When a driver receives an ACMDM_STREAM_OPEN message, it should first determine if it can perform the specified conversion. If it can, then it should perform instance initialization operations for the stream, such as determining which conversion routines to use and allocating instance-specific resources.

Store stream instance data in a local, dynamically allocated structure. Store a pointer to the structure in the ACMDRVSTREAMINSTANCE structure's dwDriver member.

If the driver supports asynchronous operations, and if the client has specified the ACM_STREAMOPENF_ASYNC flag ( contained in the ACMDRVSTREAMINSTANCE structure's fdwOpen member), then the driver should send the client an MM_ACM_OPEN callback message, by calling the PostThreadMessage function, after the operation completes.

Before calling the driver's ACM_IOControl function, the ACM verifies that:

• The ACMDRVSTREAMINSTANCE structure's fdwOpen member contains valid flag values.
• The source and destination WAVEFORMATEX structures are readable.
• If a WAVEFILTER structure is specified, it is readable and the source and destination format structures contain identical information.
• If the client has specified different source and destination format tags, then the driver has declared itself to be a codec by setting ACMDRIVERDETAILS_SUPPORTF_CODEC in the ACMDRIVERDETAILS structure's fdwSupport member. (See ACMDM_DRIVER_DETAILS.)
• If the client has specified source and destination formats associated with a single format tag, then the driver has declared itself to be a converter by setting ACMDRIVERDETAILS_SUPPORTF_CONVERTER in the ACMDRIVERDETAILS structure's fdwSupport member. (See ACMDM_DRIVER_DETAILS.)
• If the client has specified a filter operation, then the driver has declared itself to be a filter by setting ACMDRIVERDETAILS_SUPPORTF_FILTER in the ACMDRIVERDETAILS structure's fdwSupport member. (See ACMDM_DRIVER_DETAILS.)

If the client has specified the ACM_STREAMOPENF_NONREALTIME flag (contained in the ACMDRVSTREAMINSTANCE structure's fdwOpen member), then the driver can perform the conversion without time constraints. However, if this flag is not specified, and the driver cannot perform the conversion in real time, then it should return ACMERR_NOTPOSSIBLE. For more information, see Real Time Conversions.