ACMDM_FILTER_DETAILS

The ACMDM_FILTER_DETAILS message requests an ACM driver to return information about a filter associated with a specified filter tag.

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_FILTER_DETAILS

lParam1

Pointer to an ACMFILTERDETAILS structure. ( ACMFILTERDETAILS is defined in Msacm.h and described in the Win32 SDK.)

lParam2

Contains one of the following flags, specified by the fdwDetails parameter of the acmFilterDetails function ( described in the Win32 SDK):

ACM_FILTERDETAILSF_INDEX

Indicates the dwFilterIndex member of the ACMFILTERDETAILS structure contains a filter index. The valid index range is from zero to one less than the cStandardFilters member returned in the ACMFILTERTAGDETAILS structure for the filter tag. (See ACMDM_FILTERTAG_DETAILS.)

ACM_FILTERDETAILSF_FILTER

Indicates the client has filled in the WAVEFILTER structure associated with the ACMFILTERDETAILS structure.

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. Possible error codes include:

Comments

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

An ACM driver that provides filters must support this message.

The client can do either of the following:

• Specify a filter index, in order to obtain a description of the filter associated with the index.
• Specify a filter description, in order to validate the filter and obtain the filter's string description.

The client specifies the filter tag in the ACMFILTERDETAILS structure's dwFilterTag member. The driver returns information for a particular filter belonging to the filter tag, as follows:

• If the ACM_FILTERDETAILSF_INDEX flag is set, the client has specified an index value in the ACMFILTERDETAILS structure's dwFilterIndex member. The driver fills in the WAVEFILTER structure for the filter associated with the specified index value. It also fills in the ACMFILTERDETAILS structure's szFilter, fdwSupport, and cbStruct members.
• If the ACM_FILTERDETAILSF_FILTER flag is set, the client has filled in the WAVEFILTER structure. The driver validates the structure contents and, if the contents are valid, fills in the ACMFILTERDETAILS structure's szFilter, fdwSupport, and cbStruct members.

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

• The ACMFILTERDETAILS structure and its associated WAVEFILTER structure are readable and writeable.
• The size of the ACMFILTERDETAILS structure, contained in its cbStruct member, is at least the structure's defined size. (The structure's size can be larger than its defined size, to allow for a longer szFilter member or to allow newer, larger structure definitions to be used within drivers under development.)
• The size of the WAVEFILTER structure pointed to by the ACMFILTERDETAILS structure's pwfltr member is at least as large as the generic WAVEFILTER structure's defined size. (See The WAVEFILTER Structure below.)
• The ACMFILTERDETAILS structure's fdwSupport member contains zero.
• The lParam2 parameter contains a valid flag value.

Before returning, the driver must set the ACMFILTERDETAILS structure's cbStruct member to the actual number of bytes returned. The value returned in cbStruct must not be greater than the value received from the client.

For more information about filter tags and filter structures, see Format Tags and Filter Tags and Defining Format Structures and Filter Structures in the Windows NT DDK.

The WAVEFILTER Structure

The WAVEFILTER structure is a generic structure for describing a filter. Generally, you will extend this structure for your specific filter type, as has been done in the Microsoft Audio Filter. (For examples, see VOLUMEWAVEFILTER and ECHOWAVEFILTER in mmreg.h.) When a client sends an ACMDM_FILTER_DETAILS message, it specifies the address of a structure that you have defined for the specified filter type. This structure is typically larger than the generic WAVEFILTER structure.