Microsoft Windows CE 3.0  

ACMDM_FORMAT_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 associated with a specified 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 ACMFORMATDETAILSstructure declared in the Msacm.h header file.
lParam2
Contains one of the following flags specified by the fdwDetailsparameter of the acmFormatDetailsfunction:
Value Description
ACM_FORMATDETAILSF_INDEX Indicates that the dwFormatIndexmember of ACMFORMATDETAILScontains a format index. The valid index range is from 0 through 1 less than the cStandardFormatsmember returned in ACMFORMATTAGDETAILSfor the format tag.
ACM_FORMATDETAILSF_FORMAT Indicates that the client has filled in the WAVEFORMATEXstructure associated with ACMFORMATDETAILS.

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 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 acmFormatDetailsfunction.

All ACM drivers must support this message.

The client can perform either of the following actions:

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

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

    • If the ACM_FORMATDETAILSF_INDEX flag is set, the client has specified an index value in the dwFormatIndexmember of ACMFORMATDETAILS. The driver fills in WAVEFORMATEXfor the format associated with the specified index value. It also fills in the szFormat, fdwSupport, and cbStructmembers of ACMFORMATDETAILS.
    • If the ACM_FORMATDETAILSF_FORMAT flag is set, the client has filled in WAVEFORMATEX. The driver validates the structure contents and, if the contents are valid, fills in the szFormat, fdwSupport, and cbStructmembers of ACMFORMATDETAILS.

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

      • ACMFORMATDETAILSand its associated WAVEFORMATEXstructure are readable and writable.
      • The size of ACMFORMATDETAILS, 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 szFormatmember or to enable newer, larger structure definitions to be used within drivers under development.
      • The size of the WAVEFORMATEXstructure associated with the pwfxmember of ACMFORMATDETAILSis at least as large as the generic WAVEFORMATEXstructure's defined size.
      • The fdwSupportmember of ACMFORMATDETAILScontains 0.
      • The lParam2parameter contains a valid flag value.

        The WAVEFORMATEXstructure is a generic structure for describing a waveform format. Generally, use this structure as a basis for defining structures for your specific format types, as in the IMA ADPCM audio codec. For an example, see the IMAADPCMWAVEFORMATstructure in the Mmreg.h header file. When a client sends an ACMDM_FORMAT_DETAILS message, it specifies the address of a structure that you have defined for the specified format type. This structure typically is larger than the generic WAVEFORMATEXstructure.

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

        The szFormatmember of WAVEFORMATEXis used for returning a format description string. If an ACM driver returns a 0-length string in szFormat, the ACM creates an internationalized description string for the format. This string includes the format's speed, in Hz; bit depth; and channel setting, mono or stereo; based on the contents of the nSamplesPerSec, wBitsPerSample, and nChannelsmembers of WAVEFORMATEX. If wBitsPerSamplecontains 0, the ACM does not include the bit depth in the description string. You can provide your own description string and return it in szFormat, but it is best to enable the ACM to generate an internationalized description.

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



         Last updated on Tuesday, July 13, 2004

        © 2004 Microsoft Corporation. All rights reserved.