Partager via

ACMDM_FORMAT_DETAILS (Compact 2013)

  • Article

3/26/2014

This message requests an ACM driver to return information about a format associated with a specified format 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 ACMFORMATDETAILS structure declared in the Msacm.h header file.

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

    Value

    Description

    ACM_FORMATDETAILSF_INDEX

    Value that indicates that the dwFormatIndex member of ACMFORMATDETAILS contains a format index. The valid index range is from 0 through 1 less than the cStandardFormats member returned in ACMFORMATTAGDETAILS for the format tag.

    ACM_FORMATDETAILSF_FORMAT

    Value that indicates that the client has filled in the WAVEFORMATEX structure associated with ACMFORMATDETAILS.

Return Values

A return value of 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 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 acmFormatDetails function. 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 dwFormatTag memberof 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 dwFormatIndex member of ACMFORMATDETAILS. The driver fills in WAVEFORMATEX for the format associated with the specified index value. It also fills in the szFormat, fdwSupport, and cbStruct members 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 cbStruct members of ACMFORMATDETAILS.

Before calling the driver's ACM_IOControl function, the ACM verifies that the following conditions have been met:

  • ACMFORMATDETAILS and its associated WAVEFORMATEX structure are readable and writable.
  • The size of ACMFORMATDETAILS, contained in its cbStruct member, 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 szFormat member or to enable newer, larger structure definitions to be used within drivers under development.
  • The size of the WAVEFORMATEX structure associated with the pwfx member of ACMFORMATDETAILS is at least as large as the generic WAVEFORMATEX structure's defined size.
  • The fdwSupport member of ACMFORMATDETAILS contains zero (0).
  • The lParam2 parameter contains a valid flag value.

The WAVEFORMATEX structure 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 example, see the IMAADPCMWAVEFORMAT structure 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 WAVEFORMATEX structure.

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

The szFormat member of WAVEFORMATEX is 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 nChannels members of WAVEFORMATEX. If wBitsPerSample contains zero (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.

Requirements

Header

msacmdrv.h

See Also

Reference

ACM Driver Messages
ACMDM_FORMATTAG_DETAILS
ACM_Open (ACM Driver)
ACM_IOControl