ACMDM_FORMAT_DETAILS

The ACMDM_FORMAT_DETAILS message requests an ACM driver to return information about a format associated with a specified 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_FORMAT_DETAILS

lParam1

Pointer to an ACMFORMATDETAILS structure. ( ACMFORMATDETAILS 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 acmFormatDetails function, which is described in the Win32 SDK:

ACM_FORMATDETAILSF_INDEX

Indicates the dwFormatIndex member of the ACMFORMATDETAILS structure contains a format index. The valid index range is from zero to one less than the cStandardFormats member returned in the ACMFORMATTAGDETAILS structure for the format tag. (See ACMDM_FORMATTAG_DETAILS.)

ACM_FORMATDETAILSF_FORMAT

Indicates the client has filled in the WAVEFORMATEX structure associated with the ACMFORMATDETAILS structure.

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_FORMAT_DETAILS message by calling the ACM driver's ACM_IOControl() entry point via DeviceIoControl(). The ACM sends this message when an application calls the acmFormatDetails function, which is described in the Win32 SDK.

All ACM drivers must support this message.

The client can do either of the following:

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

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

• If the ACM_FORMATDETAILSF_INDEX flag is set, the client has specified an index value in the ACMFORMATDETAILS structure's dwFormatIndex member. The driver fills in the WAVEFORMATEX structure for the format associated with the specified index value. It also fills in the ACMFORMATDETAILS structure's szFormat, fdwSupport, and cbStruct members.
• If the ACM_FORMATDETAILSF_FORMAT flag is set, the client has filled in the WAVEFORMATEX structure. The driver validates the structure contents and, if the contents are valid, fills in the ACMFORMATDETAILS structure's szFormat, fdwSupport, and cbStruct members.

Before calling the driver's ACM_IOControl function, the ACM verifies that:

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

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

The WAVEFORMATEX Structure

The WAVEFORMATEX structure is a generic structure for describing a waveform format. Generally, you will use this structure as a basis for defining structures for your specific format types, as has been done in the IMA ADPCM Audio Codec. (For an example, see IMAADPCMWAVEFORMAT in mmreg.h.) 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 is typically larger than the generic WAVEFORMATEX structure.

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

Returning a Description String

The WAVEFORMATEX structure's szFormat member is used for returning a format description string. If an ACM driver returns a zero-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 the WAVEFORMATEX structure. If wBitsPerSample contains zero, 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 allowing ACM to generate an internationalized string is preferred.