ACMDM_FILTERTAG_DETAILS (Windows Embedded CE 6.0)

1/6/2010

This message requests an ACM driver to return information about a filter tag, in the form of an ACMFILTERTAGDETAILS structure.

Parameters

• dwDeviceID
  Value that specifies a driver instance identifier. The driver returns this value in response to the ACM_Open (ACM Driver) function.

• hDriver
  Handle to a driver.

• uMsg
  Value that specifies this message.

• lParam1
  Pointer to an ACMFILTERTAGDETAILS structure declared in the Msacm.h header file.

• lParam2
  Value that contains one of the flags specified by the fdwDetails parameter of the acmFilterTagDetails. The following table shows the possible values for lParam2.

  Value	Description
  ACM_FILTERTAGDETAILSF_INDEX	Flag that indicates that the dwFilterTagIndex member of ACMFILTERTAGDETAILS contains a filter tag index. The valid index range is from 0 through 1 less than the cFilterTags member returned in the driver's ACMDRIVERDETAILS structure. The driver should return details for the filter tag associated with the index.
  ACM_FILTERTAGDETAILSF_FILTERTAG	Flag that indicates that the dwFilterTag member of ACMFILTERTAGDETAILS contains a filter tag. The driver returns details for the specified filter tag.
  ACM_FILTERTAGDETAILSF_LARGESTSIZE	Flag that indicates that the driver returns details for the filter tag with the largest filter. The dwFilterTag member of ACMFILTERTAGDETAILS can contain a filter tag or WAVE_FILTER_UNKNOWN.

Return Values

MMSYSERR_NOERROR indicates success. Otherwise, the driver returns one of the MMSYSERR error values declared in the Mmsystem.h header file or one of the ACMERR error values declared in the Msacm.h header file.

Remarks

The ACM (Waveapi.dll) sends this message by calling the ACM driver's ACM_IOControl entry point through the DeviceIoControl function. The ACM sends this message when an application calls the acmFilterTagDetails function. An ACM driver that provides filters must support this message.

The client specifies the filter tag in the dwFilterTag member of ACMFILTERTAGDETAILS. The driver returns the following information for a particular tag:

• If the ACM_FILTERDETAILSF_INDEX flag is set, the client has specified an index value in the dwFilterTagIndex member of ACMFILTERTAGDETAILS. The driver fills in ACMFILTERTAGDETAILS 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 dwFilterTag member of ACMFILTERTAGDETAILS. The driver fills in ACMFILTERTAGDETAILS for the specified filter tag.
• If the ACM_FILTERTAGDETAILSF_LARGESTSIZE flag is set, the driver performs one of the following actions:
  • If dwFilterTag contains WAVE_FILTER_UNKNOWN, the driver fills in ACMFILTERTAGDETAILS for the filter tag that has a filter with the largest filter structure size.
  • If dwFilterTag contains a filter tag, the driver fills in ACMFILTERTAGDETAILS 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 following conditions have been met:

• ACMFILTERTAGDETAILS is readable and writable.
• The size of ACMFILTERTAGDETAILS, contained in its cbStruct member, is at least as large as 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 enable newer, larger structure definitions to be used within drivers under development.
• The fdwSupport member of ACMFILTERTAGDETAILS contains zero (0).
• The lParam2 parameter contains a valid flag value.

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

Requirements

See Also

Reference

ACMDM_DRIVER_DETAILS
ACM_Open (ACM Driver)

Concepts

ACM Driver Messages