MCI_CUE

This message prompts a device instance to ready itself (preroll) for a subsequent playback or recording message with minimum delay.

Syntax

param1
ULONG ulParam1; /* Flags for cue operation. */

param2
PMCI_GENERIC_PARMS pParam2; /* Pointer to the parameter data structure. */

Parameters

ulParam1 (ULONG) - input

This parameter can contain any of the following flags. **MCI_CUE_INPUT** and **MCI_CUE_OUTPUT** flags are mutually exclusive:

MCI_NOTIFY A notification message will be posted to the hwndCallback parameter of the data structure pointed to by the pParam2 parameter. The notification will be posted when the action indicated by this message is completed or when an error occurs.
MCI_WAIT Control is not to be returned until the action indicated by this message is completed or an error occurs.
MCI_CUE_INPUT This flag cues or prerolls the device instance for input or recording.
MCI_CUE_OUTPUT This flag cues or prerolls the device instance for output or playback.

- **Digital Video Extensions**: (These flags are only valid when cueing the device instance for output. The **MCI_NOSHOW** and **MCI_SHOW** flags are mutually exclusive.)
MCI_NOSHOW This flag causes the window to be hidden while the cue operation is performed. This is the default. If **MCI_TO** is not also specified, the media position will remain unchanged.
MCI_SHOW This flag causes the window to be displayed while the cue operation is performed. If **MCI_TO** is not also specified, the current frame is displayed and the media position will advance by one (frame).
MCI_TO This flag enables seeking to a specific location in the media while cueing the device for playback. If this flag is specified, the ulTo field of MCI_SEEK_PARMS indicates the ending position of the seek operation. If the ulTo position is beyond the end of the media or segment, an **MCIERR_OUTOFRANGE** error is returned.

- **Wave Audio Extensions**: (The **MCI_WAVE_INPUT** and **MCI_WAVE_OUTPUT** flags are mutually exclusive.)
MCI_WAVE_INPUT This flag cues or prerolls the device instance for input or recording.
MCI_WAVE_OUTPUT This flag cues or prerolls the device instance for output or playback.

pParam2 (PMCI_GENERIC_PARMS) - input

A pointer to the default media control interface parameter data structure. Devices with extended command sets might replace this pointer with a pointer to a device-specific data structure as follows:

PMCI_SEEK_PARMS A pointer to the MCI_SEEK_PARMS structure.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

MCIERR_SUCCESS If the function succeeds, 0 is returned.
MCIERR_INVALID_DEVICE_ID The device ID is not valid.
MCIERR_INSTANCE_INACTIVE The device ID is currently inactive. Issue MCI_ACQUIREDEVICE to make device ID active.
MCIERR_MISSING_FLAG A required flag is missing.
MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device.
MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid.
MCIERR_HARDWARE Device hardware error.
MCIERR_FILE_NOT_FOUND File has not been loaded.
MCIERR_UNSUPPORTED_FUNCTION Unsupported function.
MCIERR_INVALID_FLAG Flag (ulParam1) is invalid.
MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together.

Remarks

The preroll characteristics of the device can be obtained with MCI_GETDEVCAPS. On devices that require a file, the file must be loaded before the **MCI_CUE** command is issued; otherwise, **MCIERR_FILE_NOT_FOUND** is returned. If no flags are specified then the device instance is queued for output by default. **MCI_CUE_INPUT** is only supported on devices that support recording.

Example Code

    /* Cue the device for playback (output), and wait for completion */

    USHORT usDeviceID;
    HWND hwndMyWindow;
    MCI_GENERIC_PARMS mciGenericParms;      /* Generic message
                                               parms structure      */


                                      /* Assign hwndCallback the handle to the PM window */

    mciGenericParms.hwndCallback =  hwndMyWindow;

    mciSendCommand( usDeviceID,             /* Device ID              */
      MCI_CUE,                              /* MCI cue message        */
      MCI_WAIT | MCI_CUE_OUTPUT,            /* Standard flags         */
      (PVOID)&mciGenericParms,              /* Generic structure      */
      0 );                                  /* No user parm           */

Related Methods