This message requests an ACM driver to return information about a format associated with a specified format tag.
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.
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:
The client specifies the format tag in the dwFormatTag member of ACMFORMATDETAILS. The driver returns the following information for a particular format belonging to the format tag:
Before calling the driver’s ACM_IOControl function, the ACM verifies the following conditions:
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 an 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 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.