Microsoft Windows CE 3.0  

ACMDM_FORMATTAG_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 format 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 ACMFORMATTAGDETAILSstructure declared in the Msacm.h header file.
lParam2
Contains one of the following flags specified by the fdwDetailsparameter of the acmFormatTagDetailsfunction:
Value Description
ACM_FORMATTAGDETAILSF_INDEX Indicates that the dwFormatTagIndexmember of ACMFORMATTAGDETAILScontains a format tag index. The valid index range is from 0 through 1 less than the cFormatTagsmember returned in the driver's ACMDRIVERDETAILSstructure.

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

ACM_FORMATTAGDETAILSF_FORMATTAG Indicates that the dwFormatTagmember of ACMFORMATTAGDETAILScontains a format tag.

The driver returns details for the specified format tag.

ACM_FORMATTAGDETAILSF_LARGESTSIZE Indicates that the driver should return details for the format tag that has the largest format. The dwFormatTagmember of ACMFORMATTAGDETAILScan contain a format tag or WAVE_FORMAT_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 the specified query operation.
ACMERR_NOTPOSSIBLE
The input parameter values do not represent valid formats or format 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 acmFormatTagDetailsfunction.

All ACM drivers must support this message.

The client specifies the format tag in the dwFormatTagmember of ACMFORMATTAGDETAILS. The driver returns the following information for a particular tag:

  • If the ACM_FORMATDETAILSF_INDEX flag is set, the client has specified an index value in the dwFormatTagIndexmember of ACMFORMATTAGDETAILS. The driver fills in ACMFORMATTAGDETAILSfor the format tag associated with the specified index value.
  • If the ACM_FORMATTAGDETAILSF_FORMATTAG flag is set, the client has specified a format tag in the dwFormatTagmember of ACMFORMATTAGDETAILS. The driver fills in the ACMFORMATTAGDETAILSfor the specified format tag.
  • If the ACM_FORMATTAGDETAILSF_LARGESTSIZE flag is set, the driver performs one of two actions:
    • If dwFormatTagcontains WAVE_FORMAT_UNKNOWN, the driver fills in ACMFORMATTAGDETAILSfor the format tag that has the format with the largest format structure size.
    • If dwFormatTagcontains a format tag, the driver fills in ACMFORMATTAGDETAILSfor that format tag, describing the format with the largest structure size belonging to the specified tag.

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

      • ACMFORMATTAGDETAILSis readable and writable.
      • The size of ACMFORMATTAGDETAILS, 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 szFormatTagmember or to enable newer, larger structure definitions to be used within drivers under development.
      • The fdwSupportmember of ACMFORMATTAGDETAILScontains 0.
      • The lParam2parameter contains a valid flag value.

        If the format tag is WAVE_FORMAT_PCM, the driver return a 0-length string in szFormatTag. The ACM provides a description string for this format.

        Before returning, the driver must set the cbStructmember of ACMFORMATTAGDETAILSto 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.