MCI_SET command

The MCI_SET command sets device information. CD audio, digital-video, MIDI sequencer, VCR, videodisc, video-overlay, and waveform-audio devices recognize this command.

To send this command, call the mciSendCommand function with the following parameters.

MCIERROR mciSendCommand(
  MCIDEVICEID wDeviceID, 
  MCI_SET, 
  DWORD dwFlags, 
  (DWORD) (LPMCI_SET_PARMS) lpSet
);

Parameters

wDeviceID

Device identifier of the MCI device that is to receive the command message.

dwFlags

MCI_NOTIFY, MCI_WAIT, or, for digital-video and VCR devices, MCI_TEST. For information about these flags, see The Wait, Notify, and Test Flags.

lpSet

Pointer to an MCI_SET_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Return Value

Returns zero if successful or an error otherwise.

Remarks

The following additional flags apply to all devices supporting MCI_SET:

MCI_SET_AUDIO

An audio channel number is included in the dwAudio member of the structure identified by lpSet. This flag must be used with MCI_SET_ON or MCI_SET_OFF. Use one of the following constants to indicate the channel number:

MCI_SET_AUDIO_ALL

All audio channels.

MCI_SET_AUDIO_LEFT

Left channel.

MCI_SET_AUDIO_RIGHT

Right channel.

MCI_SET_DOOR_CLOSED

Closes the media cover (if any).

MCI_SET_DOOR_OPEN

Opens the media cover (if any).

MCI_SET_OFF

Disables the specified video or audio channel.

MCI_SET_ON

Enables the specified video or audio channel.

MCI_SET_TIME_FORMAT

A time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. The following flags are used with this flag:

MCI_FORMAT_BYTES

Within a PCM (Pulse Code Modulation) data format, changes the time member description to bytes for input or output. Recognized by the waveaudio device type.

MCI_FORMAT_FRAMES

Subsequent commands will use frames. Recognized by the digitalvideo, vcr, and videodisc device types.

MCI_FORMAT_HMS

Changes the time format to hours, minutes, and seconds. Recognized by the vcr and videodisc device types.

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds. Recognized by all device types.

MCI_FORMAT_MSF

Changes the time format to minutes, seconds, and frames. Recognized by the cdaudio and vcr device types.

MCI_FORMAT_SAMPLES

Changes the time format to samples for input or output. Recognized by the waveaudio device type.

MCI_FORMAT_SMPTE_24, MCI_FORMAT_SMPTE_25, and MCI_FORMAT_SMPTE_30

Sets the time format to 24, 25, and 30 frame SMPTE (Society of Motion Picture and Television Engineers), respectively. Recognized by the sequencer and vcr device types.

MCI_FORMAT_SMPTE_30DROP

Sets the time format to 30 drop-frame SMPTE. Recognized by the sequencer and vcr device types.

MCI_FORMAT_TMSF

Changes the time format to tracks, minutes, seconds, and frames. (MCI uses continuous track numbers.) Recognized by the cdaudio and vcr device types.

MCI_SET_VIDEO

Sets the video signal on or off. This flag must be used with either MCI_SET_ON or MCI_SET_OFF. Devices that do not have video return MCIERR_UNSUPPORTED_FUNCTION.

The following additional flags are used with the digitalvideo device type:

MCI_DGV_SET_FILEFORMAT

A file format parameter is included in the dwFileFormat member of the structure identified by lpSet. For digital-video devices, the file format is used for save or capture commands. If omitted, this might default to a device driver defined format. If the specified file format conflicts with the currently selected algorithm and quality, then they are changed to the defaults for the file format. The following file format constants are defined:

MCI_DGV_FF_AVI

AVI format.

MCI_DGV_FF_AVSS

AVSS format.

MCI_DGV_FF_DIB

DIB format.

MCI_DGV_FF_JFIF

JFIF format.

MCI_DGV_FF_JPEG

JPEG format.

MCI_DGV_FF_MPEG

MPEG format.

MCI_DGV_FF_RDIB

RLE DIB format.

MCI_DGV_FF_RJPEG

RJPEG format.

MCI_DGV_SET_SEEK_EXACTLY

Sets the format used for positioning. This flag must be used with MCI_SET_ON or MCI_SET_OFF. If MCI_SET_ON is specified, playing or recording precisely accesses the frame specified with the MCI_FROM flag. This might add some extra delay if the requested frame is not a key frame. If MCI_SET_OFF is specified, the device will seek to a key-frame image that precedes the requested frame. For some files and devices, this might be the first frame of the file. The default for this flag is device dependent.

MCI_DGV_SET_SPEED

A speed parameter is included in the dwSpeed member of the structure identified by lpSet. Speed is specified as a ratio between the nominal frame rate and the desired frame rate where the nominal frame rate is designated as 1000. Half speed is 500 and double speed is 2000. The allowable speed range is dependent on the device and possibly the file, too.

MCI_DGV_SET_STILL

When used with MCI_DGV_SET_FILEFORMAT, MCI_SET sets the file format used for capture commands.

For digital-video devices, the lpSet parameter points to an MCI_DGV_SET_PARMS structure.

The following additional flags are used with the sequencer device type:

MCI_SEQ_FORMAT_SONGPTR

Sets the time format to song pointer units.

MCI_SEQ_SET_MASTER

Sets the sequencer as a source of synchronization data and indicates that the type of synchronization is specified in the dwMaster member of the structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type:

MCI_SEQ_MIDI

The sequencer will send MIDI format synchronization data.

MCI_SEQ_SMPTE

The sequencer will send SMPTE format synchronization data.

MCI_SEQ_NONE

The sequencer will not send synchronization data.

MCI_SEQ_SET_OFFSET

Changes the SMPTE offset of a sequence to that specified by the dwOffset member of the structure identified by lpSet. This affects only sequences with a SMPTE division type.

MCI_SEQ_SET_PORT

Sets the output MIDI port of a sequence to that specified by the MIDI device identifier in the dwPort member of the structure identified by lpSet. The device closes the previous port (if any), and attempts to open and use the new port. If it fails, it returns an error and reopens the previously used port (if any). The following constants are defined for the ports:

MCI_SEQ_NONE

Closes the previously used port (if any). The sequencer behaves exactly the same as if a port were open, except no MIDI message is sent.

MIDI_MAPPER

Sets the port opened to the MIDI mapper.

MCI_SEQ_SET_SLAVE

Sets the sequencer to receive synchronization data and indicates that the type of synchronization is specified in the dwSlave member of the structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type:

MCI_SEQ_FILE

Sets the sequencer to receive synchronization data contained in the MIDI file.

MCI_SEQ_MIDI

Sets the sequencer to receive MIDI synchronization data.

MCI_SEQ_NONE

Sets the sequencer to ignore synchronization data in a MIDI stream.

MCI_SEQ_SMPTE

Sets the sequencer to receive SMPTE synchronization data.

MCI_SEQ_SET_TEMPO

Changes the tempo of the MIDI sequence to that specified by the dwTempo member of the structure pointed to by lpSet. For sequences with division type PPQN, tempo is specified in beats per minute; for sequences with division type SMPTE, tempo is specified in frames per second.

For sequencer devices, the lpSet parameter points to an MCI_SEQ_SET_PARMS structure.

The following additional flags are used with the vcr device type:

MCI_VCR_SET_ASSEMBLE_RECORD

Sets the device to record in assemble or insert modes (when assemble is off, insert is on, and vice-versa). Use with one of the following flag:

MCI_SET_ON

Sets assemble record on, and turns insert record off. Records all video, audio and timecode tracks.

MCI_SET_OFF

Sets assemble record off, and turns insert record on. When assemble record is off, individual tracks of video, audio, and timecode can be selected for recording.

MCI_VCR_SET_CLOCK

The dwClock member of the structure identified by lpSet contains the new clock time.

MCI_VCR_SET_COUNTER_FORMA

The dwCounterFormat member of the structure identified by lpSet contains a constant specifying the new counter-time format to be used by the status counter. For a list of valid constants, see MCI_SET_TIME_FORMAT in the list of additional flags for this command.

MCI_VCR_SET_COUNTER_VALUE

The dwCounterValue member of the structure identified by lpSet contains the new counter value.

MCI_VCR_SET_INDEX

The dwIndex member of the structure identified by lpSet contains a constant indicating the contents of the on-screen display and must be one of the following:

MCI_VCR_INDEX_COUNTER

Displays counter.

MCI_VCR_INDEX_DATE

Displays date.

MCI_VCR_INDEX_TIME

Displays time.

MCI_VCR_INDEX_TIMECODE

Displays timecode.

For more information, see the MCI_INDEX command.

MCI_VCR_SET_PAUSE_TIMEOUT

The dwPauseTimeout member of the structure identified by lpSet contains the maximum duration, in milliseconds, of a pause command.

MCI_VCR_SET_POSTROLL_DURATION

The dwPostrollDuration member of the structure identified by lpSet contains the videotape length, in the current time format, needed to brake the VCR transport when a stop or pause command is issued.

MCI_VCR_SET_POWER

Sets the power on or off. Must be used with one of the following flags:

MCI_SET_OFF

Turns power off.

MCI_SET_ON

Turns power on.

MCI_VCR_SET_PREROLL_DURATION

The dwPrerollDuration member of the structure identified by lpSet contains the videotape length, in the current time format, needed to stabilize the VCR output.

MCI_VCR_SET_RECORD_FORMAT

The dwRecordFormat member of the structure identified by lpSet contains a constant describing the record speed, which must be one of the following:

MCI_VCR_FORMAT_EP

Records at slow speed.

MCI_VCR_FORMAT_LP

Records at medium-slow speed.

MCI_VCR_FORMAT_SP

Records at standard speed.

MCI_VCR_SET_SPEED

The dwSpeed member of the structure identified by lpSet contains the new speed setting, where 1000 is normal speed, 2000 is double speed, and 500 is half speed, and so on.

MCI_VCR_SET_TAPE_LENGTH

The dwTapeLength member of the structure identified by lpSet contains the new length of the tape, provided that the length of the tape is undetectable.

MCI_VCR_SET_TIME_MODE

The dwTimeMode member of the structure identified by lpSet contains a constant indicating the new positional time mode. The following constants are valid:

MCI_VCR_TIME_COUNTER

Forces the device to use counter exclusively.

MCI_VCR_TIME_DETECT

Each time a new videotape is inserted into the device, or the mode changes from not ready to ready, the device should attempt to determine if there is timecode available on the videotape. If timecode is available, use timecode in all subsequent commands that specify positions. Otherwise, use the counter.

MCI_VCR_TIME_TIMECODE

Forces the device to use timecode exclusively.

MCI_VCR_SET_TRACKING

Tunes the speed of the VCR tape transport with a fine adjustment, and must be used with one of the following flags:

MCI_VCR_PLUS

Increases the tape transport speed.

MCI_VCR_MINUS

Decreases the tape transport speed.

MCI_VCR_RESET

Returns the tracking adjustment to zero.

For VCR devices, the lpSet parameter points to an MCI_VCR_SET_PARMS structure.

The following additional flag is used with the videodisc device type:

MCI_VD_FORMAT_TRACK

Changes the time format to tracks. MCI uses continuous track numbers.

The following additional flags are used with the waveaudio device type:

MCI_WAVE_INPUT

Sets the input used for recording to the wInput member of the structure identified by lpSet.

MCI_WAVE_OUTPUT

Sets the output used for playing to the wOutput member of the structure identified by lpSet.

MCI_WAVE_SET_ANYINPUT

Any wave input compatible with the current format can be used for recording.

MCI_WAVE_SET_ANYOUTPUT

Any wave output compatible with the current format can be used for playing.

MCI_WAVE_SET_AVGBYTESPERSEC

Sets the bytes per second used for playing, recording, and saving to the nAvgBytesPerSec member of the structure identified by lpSet.

MCI_WAVE_SET_BITSPERSAMPLE

Sets the bits per sample used for playing, recording, and saving to the nBitsPerSample member of the PCM data format identified by lpSet.

MCI_WAVE_SET_BLOCKALIGN

Sets the block alignment used for playing, recording, and saving to the nBlockAlign member of the structure identified by lpSet.

MCI_WAVE_SET_CHANNELS

The number of channels is indicated in the nChannels member of the structure identified by lpSet.

MCI_WAVE_SET_FORMATTAG

Sets the format type used for playing, recording, and saving to the wFormatTag member of the structure identified by lpSet. Specifying WAVE_FORMAT_PCM changes the format to PCM.

MCI_WAVE_SET_SAMPLESPERSEC

Sets the samples per second used for playing, recording, and saving to the nSamplesPerSec member of the structure identified by lpSet.

For waveform-audio devices, the lpSet parameter points to an MCI_WAVE_SET_PARMS structure.

Several properties of waveform-audio data are defined when the file to store the data is created. These properties describe how the data is structured within the file and cannot be changed once recording begins. The following list of flags identifies these properties:

• MCI_WAVE_SET_AVGBYTESPERSEC
• MCI_WAVE_SET_BITSPERSAMPLE
• MCI_WAVE_SET_BLOCKALIGN
• MCI_WAVE_SET_CHANNELS
• MCI_WAVE_SET_FORMATTAG
• MCI_WAVE_SET_SAMPLESPERSEC

Requirements

See also

MCI

MCI Commands