ACMDM_FORMATTAG_DETAILS

The ACMDM_FORMATTAG_DETAILS message requests an ACM driver to return information about a format tag.

Parameters

dwDriverID

Driver instance identifier. This is the value returned by the driver in response to the ACM_Open function.

hDriver

Driver handle.

uMsg

ACMDM_FORMATTAG_DETAILS

lParam1

Pointer to an ACMFORMATTAGDETAILS structure. ( ACMFORMATTAGDETAILS is defined in Msacm.h and described in the Win32 SDK.)

lParam2

Contains one of the following flags, specified by the fdwDetails parameter of the acmFormatTagDetails function, which is described in the Win32 SDK:

ACM_FORMATTAGDETAILSF_INDEX

Indicates the dwFormatTagIndex member of the ACMFORMATTAGDETAILS structure contains a format tag index. The valid index range is from zero to one less than the cFormatTags member returned in the driver's ACMDRIVERDETAILS structure. (See ACMDM_DRIVER_DETAILS.)

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

ACM_FORMATTAGDETAILSF_FORMATTAG

Indicates the dwFormatTag member of the ACMFORMATTAGDETAILS structure contains a format tag.

The driver should return details for the specified format tag.

ACM_FORMATTAGDETAILSF_LARGESTSIZE

Indicates the driver should return details for the format tag having the largest format. The dwFormatTag member of ACMFORMATTAGDETAILS can contain a format tag or WAVE_FORMAT_UNKNOWN.

Return Value

The driver should return MMSYSERR_NOERROR if the operation succeeds. Otherwise it should return one of the MMSYSERR error codes defined in Mmsystem.h, or one of the ACMERR error codes defined in Msacm.h. Possible error codes include:

Comments

The ACM (WAVEAPI.DLL) sends the ACMDM_FORMATTAG_DETAILS message by calling the ACM driver's ACM_IOControl() entry point via DeviceIoControl(). The ACM sends this message when an application calls the acmFormatTagDetails function, which is described the Win32 SDK.

All ACM drivers must support this message.

The client specifies the format tag in the ACMFORMATTAGDETAILS structure's dwFormatTag member. The driver returns information for a particular tag, as follows:

• If the ACM_FORMATDETAILSF_INDEX flag is set, the client has specified an index value in the ACMFORMATTAGDETAILS structure's dwFormatTagIndex member. The driver fills in the ACMFORMATTAGDETAILS structure 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 ACMFORMATTAGDETAILS structure's dwFormatTag member. The driver fills in the ACMFORMATTAGDETAILS structure for the specified format tag.
• If the ACM_FORMATTAGDETAILSF_LARGESTSIZE flag is set, the driver does one of two things:
  • If dwFormatTag contains WAVE_FORMAT_UNKNOWN, the driver fills in the ACMFORMATTAGDETAILS structure for the format tag that has a format with the largest format structure size.
  • If dwFormatTag contains a format tag, the driver fills in the ACMFORMATTAGDETAILS structure 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 ACMFORMATTAGDETAILS structure is readable and writeable.
• The size of the ACMFORMATTAGDETAILS structure (contained in its cbStruct member) is at least 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 allow newer, larger structure definitions to be used within drivers under development.)
• The ACMFORMATTAGDETAILS structure's fdwSupport member contains zero.
• The lParam2 parameter contains a valid flag value.

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

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

For more information about format tags, see Format Tags and Filter Tags in the Windows NT DDK.