MCI_CUT
This message removes the specified range of data from the device element and places it in the system clipboard or application-supplied buffer. The position of the media after a cut command is the FROM position, if MCI_FROM is specified. If MCI_FROM is not specified, the current position is used.
Syntax
param1 ULONG ulParam1; /* Flags for cut operation. */ param2 PMCI_EDIT_PARMS pParam2; /* Pointer to the MCI_EDIT_PARMS data structure. */
Parameters
- ulParam1 (ULONG) - input
- This parameter can contain any of the following flags:
- MCI_NOTIFY A notification message will be posted to the window specified in 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_FROM The beginning position of a cut operation. The position of the media is either the position specified in the ulFrom field or the previous position if MCI_FROM is not specified.
- MCI_TO The ending position of a cut operation.
- MCI_TO_BUFFER Place the data from a file into an application-supplied buffer. If this flag is not specified, then the clipboard is used.
- pParam2 (PMCI_EDIT_PARMS) - input
- A pointer to the MCI_EDIT_PARMS data structure.
Returns
- rc (ULONG) - returns
- Return codes indicating success or type of failure:
- MCIERR_SUCCESS Cut was successful.
- MCIERR_INVALID_BUFFER Buffer too small to hold data.
- MCIERR_CANNOT_WRITE The file was not opened with write access.
- MCIERR_OUTOFRANGE The units are out of the range.
- MCIERR_INVALID_DEVICE_ID The device ID is not valid.
- MCIERR_MISSING_PARAMETER Required parameter is missing.
- MCIERR_INVALID_FLAG Flag is invalid (ulParam1).
- MCIERR_UNSUPPORTED_FLAG Given flag is unsupported for this device.
- MCIERR_INSTANCE_INACTIVE The device is currently inactive. Issue MCI_ACQUIREDEVICE to make the device context active.
- MCIERR_INVALID_CALLBACK_HANDLE Given callback handle is invalid.
- MCIERR_OUT_OF_MEMORY There is insufficient memory to perform the requested operation.
- MCIERR_CLIPBOARD_ERROR An error occurred while attempting to access the clipboard.
Remarks
If MCI_TO_BUFFER is specified and the buffer is not large enough to hold the data, then the error MCIERR_INVALID_BUFFER is returned.
The units of the MCI_FROM and MCI_TO parameters are interpreted in the currently selected time format. If neither MCI_FROM nor MCI_TO are specified, the range is assumed from the current position to the end of the file.
The difference between MCI_FROM and MCI_TO must be greater than zero; otherwise, an error is returned.
If data is already in the clipboard, then it is overwritten. If a cut interrupts an in-progress operation, such as play, the operation is aborted and an MM_MCINOTIFY message is sent to the application.
Edited Audio/Video Interleaved (AVI) movie files cannot always be saved with their original name after the cut operation. If the clipboard contains a reference to data that would be erased during saving or if another instance of the digital video device has a pending paste operation which depends on this data, the file cannot be saved unless a new file name has been provided. If a new file name is not provided, MMIOERR_NEED_NEW_FILENAME is returned by the AVI I/O procedure and a temporary file is created to save the edited movie.
> **Note:** AVI is the only video file format supporting editing commands.
Waveaudio Specific If either MCI_FROM or MCI_TO begin in the middle of a digital audio sample, the wave audio device begins at the beginning of that sample. If MCI_FROM_BUFFER or MCI_TO_BUFFER are used, the pHeader field of MCI_EDIT_PARMS must contain a pointer to an MMAUDIOHEADER structure. The ulBufLen field of MCI_EDIT_PARMS must be filled in.
Example Code
USHORT usDeviceID;
MCI_EDIT_PARMS mep;
mep.hwndCallback = hwndMyWindow;
mep.ulFrom = 0;
mep.ulTo = 5000;
mciSendCommand( usDeviceID,
MCI_CUT,
MCI_NOTIFY | MCI_FROM | MCI_TO,
&mep,
0 );