Microsoft Windows CE 3.0  

ACMDM_FILTER_DETAILS

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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

Parameters

dwDriverID
Specifies a driver instance identifier. The driver returns this value in response to the ACM_Openfunction.
hDriver
Handle to a driver.
uMsg
Specifies this message.
lParam1
Pointer to an ACMFILTERDETAILSstructure declared in the Msacm.h header file.
lParam2
Contains one of the following flags specified by the fdwDetailsparameter of the acmFilterDetailsfunction:
Value Description
ACM_FILTERDETAILSF_INDEX Indicates that the dwFilterIndexmember of ACMFILTERDETAILScontains a filter index. The valid index range is from 0 through 1 less than the cStandardFiltersmember returned in the ACMFILTERTAGDETAILSstructure for the filter tag.
ACM_FILTERDETAILSF_FILTER Indicates that the client has filled in the WAVEFILTERstructure 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. The following are possible error values.

MMSYSERR_NOTSUPPORTED
The driver does not support filter operations or the specified query operation.
ACMERR_NOTPOSSIBLE
The input parameter values do not represent valid filters or filter tags.

Remarks

The ACM (Waveapi.dll) sends this message by calling the ACM driver's ACM_IOControlentry point through the DeviceIoControlfunction. The ACM sends this message when an application calls the acmFilterDetailsfunction.

An ACM driver that provides filters must support this message.

The client can do either of the following:

  • 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 the dwFilterTagmember of ACMFILTERDETAILS. The driver returns the following information for a particular filter belonging to the filter tag:

    • If the ACM_FILTERDETAILSF_INDEX flag is set, the client has specified an index value in the dwFilterIndexmember of ACMFILTERDETAILS. The driver fills in WAVEFILTERfor the filter associated with the specified index value. It also fills in the szFilter, fdwSupport, and cbStructmembers 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 cbStructmembers of ACMFILTERDETAILS.

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

      • ACMFILTERDETAILSand the associated WAVEFILTERstructure are readable and writable.
      • The size of ACMFILTERDETAILS, contained in its cbStructmember, is at least as large as its defined size. The structure size can be larger than its defined size to allow for a longer szFiltermember or to enable newer, larger structure definitions to be used within drivers under development.
      • The size of WAVEFILTER,pointed to by the pwfltrmember of ACMFILTERDETAILS,is at least as large as the generic WAVEFILTERstructure's defined size.
      • The fdwSupportmember of ACMFILTERDETAILScontains 0.
      • The lParam2parameter contains a valid flag value.

        WAVEFILTERis a generic structure for describing a filter. Generally, extend this structure for your specific filter type. For examples, see VOLUMEWAVEFILTERand ECHOWAVEFILTERin 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 cbStructmember of ACMFILTERDETAILSto the actual number of bytes returned. The value returned in cbStructmust not be greater than the value received from the client.

        For more information about format tags and filters, see the Windows NT DDK.

        Requirements

        Runs on Versions Defined in Include Link to
        Windows CE OS 1.0 and later      
        Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

        See Also

        ACMDM_FILTERTAG_DETAILS



         Last updated on Tuesday, July 13, 2004

        © 2004 Microsoft Corporation. All rights reserved.