MCI_SET
The MCI_SET
command sets device information. CD audio, digital-video, MIDI sequencer, VCR,
videodisc, video-overlay, and waveform-audio devices recognize this command.
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
Address of an
MCI_SET_PARMS
structure. (Devices with extended command sets might replace this structure
with a device-specific structure.)
Return Values
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_FORMAT
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
See Also