MCI_MASTERAUDIO

This message provides support for setting and retrieving system-wide audio control settings. Unlike MCI_SET, which affects only a specific device instance, `MCI_MASTERAUDIO` affects all logical audio devices in the system.

Syntax

param1
ULONG ulParam1; /* Audio control flags. */

param2
PMCI_MASTERAUDIO_PARMS pParam2; /* Pointer to the MCI_MASTERAUDIO_PARMS structure. */

Parameters

ulParam1 (ULONG) - input

This parameter can contain any of the following flags. Note that MCI_NOTIFY is not valid for this message.

MCI_WAIT Does not return control until the action is completed.
MCI_QUERYCURRENTSETTING Queries the current setting of the indicated attribute.
MCI_QUERYSAVEDSETTING Queries the setting saved in the INI file.
MCI_SAVESETTING Saves the current setting to the INI file.
MCI_MASTERVOL Sets or queries the system master volume (0-100). Values > 100 are treated as 100.
MCI_SPEAKERS Specifies that the operation applies to the speakers.
MCI_HEADPHONES Specifies that the operation applies to the headphones.
MCI_ON Enables the output (must be used with SPEAKERS or HEADPHONES).
MCI_OFF Disables the output (must be used with SPEAKERS or HEADPHONES).

pParam2 (PMCI_MASTERAUDIO_PARMS) - input: A pointer to the MCI_MASTERAUDIO_PARMS structure. Results for queries are returned in the ulReturn field.

Returns

rc (ULONG) - returns

MCIERR_SUCCESS Command completed successfully.
MCIERR_MISSING_FLAG A required flag (like ON/OFF with SPEAKERS) is missing.
MCIERR_INVALID_FLAG An invalid flag was specified.
MCIERR_FLAGS_NOT_COMPATIBLE Incompatible flags were used together.

Remarks

When a logical device is opened, it queries these master settings and adjusts its output automatically. Generally, only applications designed to act as a system volume mixer should modify these settings.

Example Code

The following code demonstrates how to query the current master volume and the speaker status.

   ULONG mastervolume;              /* Percentage 0-100 */
   BOOL  speakers_on;               /* Status flag      */
   USHORT usDeviceID;
   MCI_MASTERAUDIO_PARMS masteraudioparms;

   /* 1. Get current system master volume setting */

   mciSendCommand(usDeviceID,       
    MCI_MASTERAUDIO,                
    MCI_WAIT | MCI_QUERYCURRENTSETTING | MCI_MASTERVOL,
    (PVOID) &masteraudioparms,      
    0);                             

   mastervolume = masteraudioparms.ulReturn;

   /* 2. Get current system speaker enable status */

   mciSendCommand(usDeviceID,       
    MCI_MASTERAUDIO,                
    MCI_WAIT | MCI_QUERYCURRENTSETTING | MCI_SPEAKERS,
    (PVOID) &masteraudioparms,      
    0);                             
    
   speakers_on = (BOOL)masteraudioparms.ulReturn;

Related Messages