MCI_GETDEVCAPS

This message is used to return static information about the capabilities of a particular device instance.

Syntax

param1
ULONG ulParam1; /* Flags for capability query. */

param2
PMCI_GETDEVCAPS_PARMS pParam2; /* Pointer to the data structure. */

Parameters

ulParam1 (ULONG) - input

This parameter can contain any of the following flags. **Note:** Either MCI_GETDEVCAPS_MESSAGE or MCI_GETDEVCAPS_ITEM must be specified.

MCI_NOTIFY A notification message will be posted to the window specified in the hwndCallback parameter of the data structure.
MCI_WAIT Control is not to be returned until the action is completed or an error occurs.
MCI_GETDEVCAPS_EXTENDED Indicates extended device capabilities are required. (Implies MCI_GETDEVCAPS_ITEM.)
MCI_GETDEVCAPS_MESSAGE The usMessage field of the data structure contains a constant specifying the message to be queried. Returns MCI_TRUE if supported.
MCI_GETDEVCAPS_ITEM The ulItem field contains a constant specifying the device capability to be queried.

General Item Values

The following can be used regardless of device type:

MCI_GETDEVCAPS_CAN_EJECT Returns MCI_TRUE if the device can eject media.
MCI_GETDEVCAPS_CAN_LOCKEJECT Returns MCI_TRUE if manual ejection can be disabled.
MCI_GETDEVCAPS_CAN_PLAY Returns MCI_TRUE if playback is supported (implies support for PLAY, PAUSE, RESUME, and STOP).
MCI_GETDEVCAPS_CAN_PROCESS_INTERNAL Returns MCI_TRUE if internal digital processing (like a built-in DAC) is supported.
MCI_GETDEVCAPS_CAN_RECORD Returns MCI_TRUE if recording is supported.
MCI_GETDEVCAPS_CAN_SAVE Returns MCI_TRUE if saving files is supported.
MCI_GETDEVCAPS_CAN_SETVOLUME Returns MCI_TRUE if volume levels can be changed.
MCI_GETDEVCAPS_DEVICE_TYPE Returns the constant defined for the specific device type.
MCI_GETDEVCAPS_HAS_AUDIO Returns MCI_TRUE if capable of audio.
MCI_GETDEVCAPS_HAS_VIDEO Returns MCI_TRUE if capable of video.
MCI_GETDEVCAPS_USES_FILES Returns MCI_TRUE if a filename or playlist is required.

Device Extensions

Amplifier Mixer Extensions

Requires MCI_GETDEVCAPS_EXTENDED. Query attributes like:

MCI_AMP_CAN_SET_TREBLE / BASS / MID / BALANCE / VOLUME
MCI_AMP_CAN_SET_MUTE / LOUDNESS / REVERB / CHORUS

Digital Video Extensions

MCI_DGV_GETDEVCAPS_CAN_DISTORT Returns MCI_TRUE if independent X/Y scaling is supported.
MCI_DGV_GETDEVCAPS_CAN_REVERSE Returns MCI_TRUE if reverse play is supported.
MCI_DGV_GETDEVCAPS_FAST_RATE / SLOW_RATE Returns the standard fast/slow playback rates.
MCI_DGV_GETDEVCAPS_HAS_TUNER Returns MCI_TRUE if a TV tuner is present.

Video Overlay Extensions

MCI_OVLY_GETDEVCAPS_CAN_FREEZE Returns MCI_TRUE if the image can be frozen.
MCI_OVLY_GETDEVCAPS_MAX_WINDOWS Returns the maximum concurrent windows (Default: 10).
MCI_OVLY_GETDEVCAPS_VIDEO_X_EXTENT / Y_EXTENT Returns nominal source dimensions (706x484 for NTSC).

Waveform Audio Extensions

MCI_GETDEVCAPS_WAVE_FORMAT Used to determine if a specific wave format (SamplesPerSec, BitsPerSample, etc.) is supported.

Returns

rc (ULONG) - returns

The low-order word contains the success/failure code:

MCIERR_SUCCESS 0 is returned on success.
MCIERR_INVALID_DEVICE_ID Invalid device ID.
MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together.
MCIERR_MISSING_PARAMETER A required parameter is missing.
MCIERR_INVALID_ITEM_FLAG Invalid item specified.

Default Processing

For videodisc devices, the MCI_VD_GETDEVCAPS_CAV flag is the default.

Remarks

When checking the return code, always mask the value to examine the low-order word:

if ( (ulError & 0x0000FFFF) == MCIERR_SUCCESS )

The high-order word of the return value from `mciSendCommand` defines the format of the `ulReturn` value in the parameters structure, allowing `mciSendString` to handle conversions correctly.

Example Code

The following code illustrates how to determine if a device has audio capability.

   USHORT   usDeviceID;
   ULONG    rc;
   BOOL     fHas_audio;                   /* Set to TRUE by this example
                                             if device has audio      */
   MCI_GETDEVCAPS_PARMS  mgdcp;

   /* Determine if device has audio capability */

   mgdcp.ulItem = MCI_GETDEVCAPS_HAS_AUDIO;

   rc = mciSendCommand(usDeviceID,           /* Device ID              */
                       MCI_GETDEVCAPS,       /* Get device capability
                                                message                */
                       MCI_WAIT | MCI_GETDEVCAPS_ITEM,
                                             /* Flags for this message */
                       (PVOID) &mgdcp,       /* Data structure         */
                       0);                   /* No user parm           */

   if (LOUSHORT(rc) == MCIERR_SUCCESS)
     {
      fHas_audio = (BOOL) mgdcp.ulReturn; /* Return if device
                                                has audio              */
     }

The following example illustrates how an application can determine if it can set the volume attribute for a particular connector.

    ULONG  rc;
    MCI_AMP_GETDEVCAPS_PARMS mciAmpCaps;
    USHORT usDeviceID;

/* Test to see if the mixer supports volume changes on the mic. */
    mciAmpCaps.ulValue = MCI_MICROPHONE_CONNECTOR;
    mciAmpCaps.ulAttribute = MCI_AMP_CAN_SET_VOLUME;
    mciAmpCaps.ulExtended = MCI_MIXER_LINE;
    rc = mciSendCommand(usDeviceID,
                        MCI_GETDEVCAPS,
                        MCI_WAIT |
                        MCI_GETDEVCAPS_EXTENDED,
                        (ULONG)&mciAmpCaps,
                        0);