MXDM_GETCONTROLDETAILS

Sent to an audio mixer device driver to get the state of one or more items for a control. This message is normally sent to an audio mixer driver in response to a mixerGetControlDetails call.

The return value is an error code, or zero (MMSYSERR_NOERROR) if the operation is successful. Possible error codes are:

MIXERR_INVALCONTROL	The audio mixer device control reference is invalid.
MIXERR_INVALLINE	The audio mixer device line reference is invalid.
MMSYSERR_NOTENABLED	The driver failed to load or initialize.
MMSYSERR_NOTSUPPORTED	The specified query type is not supported by the driver.

dwParam1

Specifies a pointer to a MIXERCONTROLDETAILS structure, which in turn references one or more MIXERCONTROL structures containing the control details.

dwParam2

Specifies flags for getting the line control details. This argument is identical to the fdwDetails argument passed to the mixerGetControlDetails function. For additional information about the flag settings, see the mixerGetControlDetails function listed in the SDK documentation.

An audio mixer driver must support this message. The Mixer Manager will validate the following parameters for the MXDM_GETCONTROLDETAILS message before calling the driver. Your driver does not need to check for the following conditions:

1 dwParam1 contains a valid pointer to a MIXERCONTROLDETAILS structure. This structure will be at least large enough to hold the base MIXERCONTROLDETAILS structure members. This buffer has also been validated to insure it is big enough to hold at least cbStruct bytes of information.

2 All members of the MIXERCONTROLDETAILS structure have been validated to contain proper structure sizes and a valid pointer to one or more mixer control details structures.

3 dwParam2 will be a valid combination of flags.

A mixer driver should validate the control identifier and should verify that the size of the details buffer for a custom mixer control is correct.

A mixer driver should verify that the cChannels member of the MIXERCONTROLDETAILS structure is correct for the control. This member must be zero for custom mixer controls and non-zero for standard mixer controls.

If the calling application specifies cChannels equal to one for a multi-channel control, the driver must combine the channel values into one value using the following rules:

MIXERCONTROL_CT_CLASS_CUSTOM	This class of mixer controls cannot be coalesced; cChannels must always be zero.
MIXERCONTROL_CT_CLASS_FADER	This class of mixer controls should use the largest absolute value of all channels as the return value.
MIXERCONTROL_CT_CLASS_LIST	This class of mixer controls should logically or all values of all channels as the return value. For single selection lists, the left channel information should be returned.
MIXERCONTROL_CT_CLASS_METER	This class of mixer controls should use the largest absolute value of all channels as the return value.
MIXERCONTROL_CT_CLASS_NUMBER	This class of mixer controls should use the largest absolute value of all channels as the return value.
MIXERCONTROL_CT_CLASS_SLIDER	This class of mixer controls should use the largest absolute value of all channels as the return value.
MIXERCONTROL_CT_CLASS_SWITCH	This class of mixer controls should logically OR all values of all channels as the return value.
MIXERCONTROL_CT_CLASS_TIME	This class of mixer controls should use the largest absolute value of all channels as the return value.

A mixer driver should verify that the cMultipleItems member of the MIXERCONTROLDETAILS structure is correct for the control. It is invalid to specify any number for cMultipleItems other than the value given in the cMultipleItems member of the MIXERCONTROL structure.

An application can generate two types of queries for a mixer control's details. A driver must use the bitwise AND operator with dwParam2 and the MIXER_GETCONTROLDETAILSF_QUERYMASK constant to obtain the query type.

If the result matches the MIXER_GETCONTROLDETAILSF_VALUE constant, the query is a request for the control's current value.
If the result matches the MIXER_GETCONTROLDETAILSF_LISTTEXT constant, the request is to get the list text and instance data for list or banded controls.

All mixer drivers must support these queries. If a query other than the above list is sent that the mixer device does not know how to handle, MMSYSERR_NOTSUPPORTED must be returned.