Microsoft Windows CE 3.0  

ACMDM_FILTERTAG_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 tag, in the form of an ACMFILTERTAGDETAILSstructure.

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 ACMFILTERTAGDETAILSstructure declared in the Msacm.h header file.
lParam2
Contains one of the following flags specified by the fdwDetailsparameter of the acmFilterTagDetails:
Value Description
ACM_FILTERTAGDETAILSF_INDEX Indicates that the dwFilterTagIndexmember of ACMFILTERTAGDETAILScontains a filter tag index. The valid index range is from 0 through 1 less than the cFilterTagsmember returned in the driver's ACMDRIVERDETAILSstructure.

The driver should return details for the filter tag associated with the index.
ACM_FILTERTAGDETAILSF_FILTERTAG Indicates that the dwFilterTagmember of ACMFILTERTAGDETAILScontains a filter tag.

The driver returns details for the specified filter tag.
ACM_FILTERTAGDETAILSF_LARGESTSIZE Indicates that the driver returns details for the filter tag with the largest filter. The dwFilterTagmember of ACMFILTERTAGDETAILScan 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. 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 acmFilterTagDetailsfunction.

An ACM driver that provides filters must support this message.

The client specifies the filter tag in the dwFilterTagmember 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 dwFilterTagIndexmember of ACMFILTERTAGDETAILS. The driver fills in ACMFILTERTAGDETAILSfor 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 dwFilterTagmember of ACMFILTERTAGDETAILS. The driver fills in ACMFILTERTAGDETAILSfor the specified filter tag.
  • If the ACM_FILTERTAGDETAILSF_LARGESTSIZE flag is set, the driver performs one of two actions:
    • If dwFilterTagcontains WAVE_FILTER_UNKNOWN, the driver fills in ACMFILTERTAGDETAILSfor the filter tag that has a filter with the largest filter structure size.
    • If dwFilterTagcontains a filter tag, the driver fills in ACMFILTERTAGDETAILSfor that filter tag, describing the filter with the largest structure size belonging to the specified tag.

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

      • ACMFILTERTAGDETAILSis readable and writable.
      • The size of ACMFILTERTAGDETAILS, contained in its cbStructmember, 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 szFilterTagmember or to enable newer, larger structure definitions to be used within drivers under development.
      • The fdwSupportmember of ACMFILTERTAGDETAILScontains 0.
      • The lParam2parameter contains a valid flag value.

        Before returning, the driver must set the cbStructmember of ACMFILTERTAGDETAILSto the actual number of bytes returned. The value returned in cbStructmust not be greater than the value received.

        For more information about format tags and filter tags, 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_DRIVER_DETAILS


         Last updated on Tuesday, July 13, 2004

        © 2004 Microsoft Corporation. All rights reserved.