Share via

ACMDM_FILTER_DETAILS (Compact 2013)

  • Article

3/26/2014

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

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 ACMFILTERDETAILS structure declared in the Msacm.h header file.

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

    Value

    Description

    ACM_FILTERDETAILSF_INDEX

    Flag that indicates that the dwFilterIndex member of ACMFILTERDETAILS contains a filter index. The valid index range is from 0 through 1 less than the cStandardFilters member returned in the ACMFILTERTAGDETAILS structure for the filter tag.

    ACM_FILTERDETAILSF_FILTER

    Flag that indicates that the client has filled in the WAVEFILTER structure associated with ACMFILTERDETAILS.

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 acmFilterDetails function. An ACM driver that provides filters must support this message.

The following list shows the actions the client can take:

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

The client specifies the filter tag in thedwFilterTag member of ACMFILTERDETAILS. The driver then returns information for a particular filter belonging to the filter tag. The following list shows the information that can be returned by the driver:

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

Before calling the driver's ACM_IOControl function, the ACM should verify the following conditions:

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

WAVEFILTER is a generic structure for describing a filter. Generally, extend this structure for your specific filter type. For examples, see VOLUMEWAVEFILTER and ECHOWAVEFILTER in the Mmreg.h header file. When a client sends an ACMDM_FILTER_DETAILS message, it specifies a pointer to a structure that you have defined for the specified filter type. This structure typically is larger than the generic WAVEFILTER.

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

Requirements

Header

msacmdrv.h

See Also

Reference

ACM Driver Messages
ACMDM_FILTERTAG_DETAILS
ACM_Open (ACM Driver)