MCI_SET_POSITION_ADVISE
This message is used to request periodic position-change notifications from a media device. The interval between notifications is specified in the current time format.
Syntax
param1 ULONG ulParam1; /* Message flags. */ param2 PMCI_POSITION_PARMS pParam2; /* Pointer to the MCI_POSITION_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_POSITION_ADVISE_ON Enables position-change advise messages. The frequency is determined by the `ulUnits` field in the parameter structure.
- MCI_SET_POSITION_ADVISE_OFF Disables position-change advise messages.
- pParam2 (PMCI_POSITION_PARMS) - input
- A pointer to the MCI_POSITION_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 make it active.
- MCIERR_INVALID_CALLBACK_HANDLE The window handle in `hwndCallback` is invalid.
- MCIERR_OUTOFRANGE The `ulUnits` value is 0 or out of range.
- MCIERR_MISSING_FLAG A required flag is missing.
Remarks
When enabled, the device sends MM_MCIPOSITIONCHANGE messages to the window specified in `hwndCallback` every time the specified interval passes.
- **Frequency:** Only one frequency can be active at a time. Setting a new frequency replaces the previous request.
- **Format:** While `ulUnits` is provided in the current time format (e.g., milliseconds), the resulting MM_MCIPOSITIONCHANGE messages return the position in `MMTIME` format.
- **Scope:** Messages are only generated during playback or recording. Seeking does not trigger these events.
- **Element Loading:** A device element must be loaded for this message to work. The advise request is reset if a new element is loaded.
- **Accuracy:** Accuracy depends on the device hardware and driver. Devices without internal event detection may have less precise timing.
Example Code
The following code demonstrates how to request a position notification every 2 seconds.
USHORT usDeviceID;
HWND hwndMyWindow;
MCI_POSITION_PARMS positionparms; /* Position advise parm structure */
/* Set the window handle to receive MM_MCIPOSITIONCHANGE messages */
positionparms.hwndCallback = hwndMyWindow;
/* Set interval to 2000 milliseconds (assuming current format is MS) */
positionparms.ulUnits = (ULONG) 2000;
mciSendCommand( usDeviceID,
MCI_SET_POSITION_ADVISE,
MCI_SET_POSITION_ADVISE_ON | MCI_WAIT,
(PVOID) &positionparms,
0);