MXDM_SETCONTROLDETAILS
Sent to an audio mixer device driver to set the state of one or more items for a control. This message is normally sent to an audio mixer driver in response to a mixerSetControlDetails 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. |
| MIXERR_INVALVALUE |
The value specified for the mixer control is not within the limits for the control. |
| 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 that references the MIXERCONTROLDETAILS structures to set the controls details to.
- dwParam2
- Specifies flags for setting the line control details. This argument is identical to the fdwDetails argument passed to the mixerSetControlDetails function. For additional information about the flag settings, see the mixerSetControlDetails 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_SETCONTROLDETAILS message before calling the driver. Your driver does not need to check for the following conditions:
- dwParam1 will contain 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.
- 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.
- dwParam2 will be a valid combination of flags.
- If the request is for MIXER_SETCONTROLDETAILSF_CUSTOM, then the hwndOwner of the MIXERCONTROLDETAILS structure is a valid window handle (which can be NULL) to use as the owner for the custom mixer control's dialog box.
However, a mixer driver should verify the following:
- The control identifier.
- The size of the details buffer for a custom mixer control.
- All control values to insure they are in the correct ranges for the specified control.
- MIXERCONTROLDETAILS.cChannels. This member must be zero for custom mixer controls. This member must be non-zero for standard mixer controls.
- If the calling application specifies cChannels equal to one for a multi-channel control, then the driver must set all channel values to the specified single value.
- MIXERCONTROLDETAILS.cMultipleItems. It is invalid to specify any number for cMultipleItems other than the value given in the cMultipleItems member of the MIXERCONTROL structure.
If the user cancels a custom mixer control dialog, then the mixer driver should return the current state of the mixer control and succeed the call with MMSYSERR_NOERROR.
An application can set details for standard and custom controls. A driver must use the bitwise AND operator with dwParam2 and the MIXER_SETCONTROLDETAILSF_QUERYMASK constant to identify the type of information being set.
- If the result matches the MIXER_SETCONTROLDETAILSF_VALUE constant, the details for a standard control are set to the specified state.
- If the result matches the MIXER_SETCONTROLDETAILSF_CUSTOM constant, the details for a customer control are set to the specified state.
All mixer drivers must support these queries. If a query other than those previously mentioned is sent, the mixer driver must return MMSYSERR_NOTSUPPORTED.