ACMDM_FILTERTAG_DETAILS

The ACMDM_FILTERTAG_DETAILS message requests an ACM driver to return information about a 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_FILTERTAG_DETAILS

lParam1

Pointer to an ACMFILTERTAGDETAILS structure. ( ACMFILTERTAGDETAILS 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 acmFilterTagDetails function ( described in the Win32 SDK):

ACM_FILTERTAGDETAILSF_INDEX

Indicates the dwFilterTagIndex member of the ACMFILTERTAGDETAILS structure contains a filter tag index. The valid index range is from zero to one less than the cFilterTags member returned in the driver's ACMDRIVERDETAILS structure. (See ACMDM_DRIVER_DETAILS.)

The driver should return details for the filter tag associated with the index.

ACM_FILTERTAGDETAILSF_FILTERTAG

Indicates the dwFilterTag member of the ACMFILTERTAGDETAILS structure contains a filter tag.

The driver should return details for the specified filter tag.

ACM_FILTERTAGDETAILSF_LARGESTSIZE

Indicates the driver should return details for the filter tag having the largest filter. The dwFilterTag member of ACMFILTERTAGDETAILS can contain a filter tag or WAVE_FILTER_UNKNOWN.

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_FILTERTAG_DETAILS message by calling the ACM driver's ACM_IOControl() entry point via DeviceIoControl(). The ACM sends this message when an application calls acmFilterTagDetails, which is described in the Win32 SDK.

An ACM driver that provides filters must support this message.

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

• If the ACM_FILTERDETAILSF_INDEX flag is set, the client has specified an index value in the ACMFILTERTAGDETAILS structure's dwFilterTagIndex member. The driver fills in the ACMFILTERTAGDETAILS structure for the filter tag associated with the specified index value.
• If the ACM_FILTERTAGDETAILSF_FILTERTAG flag is set, the client has specified a filter tag in the ACMFILTERTAGDETAILS structure's dwFilterTag member. The driver fills in the ACMFILTERTAGDETAILS structure for the specified filter tag.
• If the ACM_FILTERTAGDETAILSF_LARGESTSIZE flag is set, the driver does one of two things:
  • If dwFilterTag contains WAVE_FILTER_UNKNOWN, the driver fills in the ACMFILTERTAGDETAILS structure for the filter tag having a filter with the largest filter structure size.
  • If dwFilterTag contains a filter tag, the driver fills in the ACMFILTERTAGDETAILS structure for that filter tag, describing the filter with the largest structure size belonging to the specified tag.

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

• The ACMFILTERTAGDETAILS structure is readable and writeable.
• The size of the ACMFILTERTAGDETAILS 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 szFilterTag member or to allow newer, larger structure definitions to be used within drivers under development.)
• The ACMFILTERTAGDETAILS structure's fdwSupport member contains zero.
• The lParam2 parameter contains a valid flag value.

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

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