MCI_SET_CUEPOINT

This message is used to set run-time cue points in a media device. When the device reaches a specified point during playback or recording, it notifies the application.

Syntax

param1
ULONG ulParam1; /* Message flags. */

param2
PMCI_CUEPOINT_PARMS pParam2; /* Pointer to the MCI_CUEPOINT_PARMS structure. */

Parameters

ulParam1 (ULONG) - input

The following flags can be used:

MCI_NOTIFY Posts a notification message when the action completes.
MCI_WAIT Does not return control until the action is completed.
MCI_SET_CUEPOINT_ON Sets a cue point at the location specified in the `ulCuepoint` field.
MCI_SET_CUEPOINT_OFF Removes a cue point at the location specified in the `ulCuepoint` field. The location must exactly match a previously set cue point.

Note: You can set or remove only one cue point at a time.

pParam2 (PMCI_CUEPOINT_PARMS) - input

A pointer to the MCI_CUEPOINT_PARMS data structure.

Returns

rc (ULONG) - returns

MCIERR_SUCCESS If the function succeeds.
MCIERR_INVALID_DEVICE_ID The device ID is not valid.
MCIERR_INSTANCE_INACTIVE The device is currently inactive. Issue MCI_ACQUIREDEVICE to activate.
MCIERR_DUPLICATE_CUEPOINT A cue point already exists at the specified location.
MCIERR_CUEPOINT_LIMIT_REACHED The maximum number of cue points for this device has been reached.
MCIERR_INVALID_CUEPOINT The specified cue point is invalid.
MCIERR_OUTOFRANGE The specified units are out of range for the media.

Remarks

When a cue point is reached, the MM_MCICUEPOINT message is sent to the window specified in `hwndCallback`. The `ulCuepoint` field is specified in the current time format, but notification messages are always returned in `MMTIME` format.

**Persistence:** Cue points remain set after being encountered until they are explicitly turned off or a new device element is loaded.
**Accuracy:** Cue points are triggered during playback or recording, but not during seek operations.
**Window Handles:** Each cue point can be directed to a different window handle. A valid `hwndCallback` is required when setting a cue point to ON.
**Limits:** Media drivers typically support at least twenty cue points.

Example Code

The following code illustrates how to set a cue point 30 seconds into the media.

   USHORT usDeviceID;
   HWND   hwndMyWindow;
   MCI_CUEPOINT_PARMS cuepointparms;        /* Cue point parameter structure */

   /* Assign hwndCallback the handle to the window that receives MM_MCICUEPOINT */
   cuepointparms.hwndCallback = hwndMyWindow;
   
   /* Set cue point at 30,000 milliseconds (assuming MS time format) */
   cuepointparms.ulCuepoint = (ULONG) 30000; 

   mciSendCommand( usDeviceID,        /* Device ID                 */
    MCI_SET_CUEPOINT,                 /* MCI set cue point message */
    MCI_SET_CUEPOINT_ON | MCI_WAIT,   /* Flags for this message    */
    (ULONG) &cuepointparms,           /* Data structure            */
    0);                               /* No user parm              */

Related Messages