ACMDM_FORMATTAG_DETAILS (Compact 2013)

3/26/2014

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

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

  Value	Description
  ACM_FORMATTAGDETAILSF_INDEX	Value that indicates that the dwFormatTagIndex member of ACMFORMATTAGDETAILS contains a format tag index. The valid index range is from 0 through 1 less than the cFormatTags member returned in the driver's ACMDRIVERDETAILS structure. The driver should return details for the format tag associated with the index.
  ACM_FORMATTAGDETAILSF_FORMATTAG	Value that indicates that the dwFormatTag member of ACMFORMATTAGDETAILS contains a format tag. The driver returns details for the specified format tag.
  ACM_FORMATTAGDETAILSF_LARGESTSIZE	Value that indicates that the driver should return details for the format tag that has the largest format. The dwFormatTag member of ACMFORMATTAGDETAILS can contain a format tag or WAVE_FORMAT_UNKNOWN.

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 (Waveapi.dll) 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 acmFormatTagDetails function. All ACM drivers must support this message.

The client specifies the format tag in the dwFormatTag member 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 dwFormatTagIndex member of ACMFORMATTAGDETAILS. The driver fills in ACMFORMATTAGDETAILS for 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 dwFormatTag member of ACMFORMATTAGDETAILS. The driver fills in the ACMFORMATTAGDETAILS for the specified format tag.
• If the ACM_FORMATTAGDETAILSF_LARGESTSIZE flag is set, the driver performs one of the following actions:
  • If dwFormatTag contains WAVE_FORMAT_UNKNOWN, the driver fills in ACMFORMATTAGDETAILS for the format tag that has the format with the largest format structure size.
  • If dwFormatTag contains a format tag, the driver fills in ACMFORMATTAGDETAILS for that format tag, describing the format with the largest structure size belonging to the specified tag.

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

• ACMFORMATTAGDETAILS is readable and writable.
• The size of ACMFORMATTAGDETAILS, 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 szFormatTag member or to enable newer, larger structure definitions to be used within drivers under development.
• The fdwSupport member of ACMFORMATTAGDETAILS contains zero (0).
• The lParam2 parameter contains a valid flag value.

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

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

Requirements

See Also

Reference

ACM Driver Messages
ACMDM_DRIVER_DETAILS
ACM_Open (ACM Driver)
ACM_IOControl