Cue points are discrete locations or time positions in a media device. When a device encounters a time position associated with a cue point, a message is returned to the application window handle that is specified to receive the cue point messages. Cue points are maintained as part of a device context, so setting a cue point in one device context will not cause cue point messages to be generated for other device contexts.
Applications specify cue points for a device with the MCI_SET_CUEPOINT message. A cue point is identified by its location; setting a cue point "on" sets a cue point at the specified location, and setting a cue point "off" removes the cue point. Because cue points are identified by location, only one cue point can be set at a specified location in the media. Therefore, setting a cue point at a location where a cue point is already set causes the second MCI_SET_CUEPOINT to fail and to return the error MCIERR_DUPLICATE_CUEPOINT. Cue points can be set at any valid location in the media, regardless of current media position. If a device is currently playing at 2:00 (two minutes), and a cue point is set at 1:00 (one minute) in the media, and the device is subsequently seeked and played from the beginning, the cue point message will be generated when the device passes the 1:00 point in the media.
Cue points are persistent. That is, they remain set after they are encountered. The device will generate cue point messages whenever the cue point location is encountered, which may be many times if the device is seeked or played repeatedly. Cue points are encountered only when a device is playing or recording. If a device is seeked from its current position to some new position, cue points set at locations between the old and new position are not encountered during the seek operation, and no cue point messages are generated.
Because cue points can be set only within the valid range of a media element, cue points cannot be set when a file is not loaded. All cue points for a device context are removed when a new file element is loaded.
Cue points also can be created as part of a media element. In the case of cue points imbedded directly in a media element, the MCI_SET_CUEPOINT message performs no function. Imbedded cue points always result in cue point messages being returned when they are encountered. The user parameter value returned on the cue point message varies from one media data type to another and should be set to a meaning that is significant to the application.
When a cue point is encountered, an MM_MCICUEPOINT message is sent to the window specified by the hwndCallback field of the MCI_CUEPOINT_PARMS data structure passed with the MCI_SET_CUEPOINT message. The MM_MCICUEPOINT message parameters contain the device ID of the device context that generated the cue point message, as well as the media position and an additional application-defined parameter that can be specified when the cue point is set. Although the media position specified by the application on the MCI_SET_CUEPOINT message is in the currently set device units, the media position returned on the MM_MCICUEPOINT message is always in MMTIME units. MMTIME units are used because the time format set when the cue point is set might not be the same time format set when the cue point is encountered.
The maximum number of cue points that can be set in a device context is defined by the implementation of the logical device. Devices generally support up to 20 cue points per device context.