mciSendString

This function sends a command string to an MCI device. 
The device that the command is sent to is specified in the command string.

Syntax

function mciSendString(lpstrCommand: PChar; lpstrReturnString: PChar; 
                       uReturnLength: Word; hWndCallback: HWnd): Longint;

Parameters

lpstrCommand         Specifies an MCI command string.
lpstrReturnString    Specifies a buffer for return information. 
                     If no return information is needed, you can specify NULL for this parameter.
wReturnLength        Specifies the size of the return buffer specified by lpstrReturnString.
hCallback            Specifies a handle to a window to call back if "notify" was specified in 
                     the command string.

Return Value

Returns zero if the function was successful. Otherwise, it returns error information. 
The low-order word of the returned longint contains the error return value. 

To get a textual description of mciSendString return values, pass the return value to 
mciGetErrorString.  The error returns listed for mciSendCommand also apply to mciSendString. 
The following error returns are unique to mciSendString:

MCIERR_BAD_CONSTANT
The specified constant is invalid for this command.

MCIERR_BAD_INTEGER
The specified integer is invalid for this command.

MCIERR_DUPLICATE_FLAGS
The parameter or value was specified twice. Remove the duplicate occurrence of the parameter 
or value.

MCIERR_MISSING_COMMAND_STRING
No command was specified.

MCIERR_MISSING_DEVICE_NAME
The specified command requires an alias or the name of a file, driver, or device, which 
you must specify.

MCIERR_MISSING_STRING_ARGUMENT
The specified command requires a string parameter, which you must supply.

MCIERR_NEW_REQUIRES_ALIAS
You must specify an alias when using the "new" parameter.

MCIERR_NO_CLOSING_QUOTE
The string parameter is missing a closing double quotation mark, which you must supply.

MCIERR_NOTIFY_ON_AUTO_OPEN
You cannot use the "notify" flag with automatically opened device.

MCIERR_PARAM_OVERFLOW
The output string was too large to fit in the return buffer. Increase the size of the buffer.

MCIERR_PARSER_INTERNAL
The device driver returned an invalid return type. Check with the device manufacturer about obtaining a new driver.

MCIERR_UNRECOGNIZED_KEYWORD
The driver cannot recognize the specified command parameter.

See Also
mciGetErrorString, mciSendCommand

----------------------------------------------------------------------------

mciGetErrorString

This function returns a textual description of the specified MCI error.

Syntax

function mciGetErrorString(wError: Longint; 
                           lpstrBuffer: PChar; uLength: Word): Bool;

Parameters

dwError     Specifies the error code returned by mciSendCommand or mciSendString.
lpstrBuffer Specifies a pointer to a buffer that is filled with a textual 
            description of the specified error.
wLength     Specifies the length of the buffer pointed to by lpstrBuffer.

Return Value

Returns TRUE if successful. Otherwise, the given error code was not known.

----------------------------------------------------------------------------

Waveform Audio Command Overview

The following list summarizes the commands used with the "waveaudio" device type:

Command        Description

capability        Obtains the capabilities of a device.
close        Closes the device.
cue        Prepares for playing or recording.
delete        Deletes a data segment from the MCI element.
info        Obtains textual information from a device.
open        Initializes the device.
pause        Pauses playing or recording.
play        Starts transmitting output data.
record        Starts recording input data.
resume        Resumes playing or recording on a paused device.
save        Saves data to a disk file.
seek        Seeks forward or backward.
set        Sets the operating state of the device.
status        Obtains status information from the device.
stop        Stops playing or recording.

-------------------------------------------------------------------------------------

open (Waveform Audio)

Syntax

open device [parameters] [notify] [wait]
The open command initializes the device.

Parameters

You can specify one or more of the following optional items for parameters:

alias device_alias
  Specifies an alternate name for the given device.
  If specified, it must be used as the device_id in subsequent commands.

buffer buffer_size
  Sets the size in seconds of the buffer used by the waveform audio device. The default size of the buffer is set when the waveform audio device is installed or
configured. Typically the buffer size is set to 4 seconds. With the MCIWAVE device, the minimum size is 2 seconds and the maximum size is 9 seconds.

shareable
  Initializes the device element as shareable.
  Subsequent attempts to open it fail unless you specify shareable in both the
  original and subsequent open commands. MCI returns an error if it the device
  is already open and not shareable. The MCIWAVE device does not support shared files.

type device_type
  Specifies the device type of a device element. MCI reserves waveaudio for
  the waveform audio device type. As an alternative to type, MCI can use the
  [mci extension] entries in the SYSTEM.INI file to select the controlling
  device based on the extension used by the device element. You can also use the device_name!element_name abbreviation described in Combining the Device Name and
Element Name.

Comments

The MCIWAVE device included with Windows requires an asynchronous waveform driver.
It does not work with synchronous drivers like the PC Speaker driver.

Example

The following command opens the "mysound" device:

open new type waveaudio alias mysound buffer 6

With device name "new", the waveform driver prepares a new waveform resource.
The command assigns device alias "mysound" and specifies a 6-second buffer.

-------------------------------------------------------------------------

Combining the Device Name and Element Name

You can eliminate the type flag in the open command if you combine the device
name with the device element name. MCI recognizes this combination when you
use the following syntax:

device_name!element_name

The exclamation point separates the device name from the element name.
There should not be any spaces between the exclamation point and the device_name
or element_name.
The following example opens the RIGHT.WAV element using the "waveaudio" device:

open waveaudio!right.wav

------------------------------------------------------------------------------

play (Waveform Audio)

Syntax

play device_id [parameters] [notify] [wait]
The play command starts playing audio.

Parameters

You can specify one or more of the following optional items for parameters:

from position
  Specifies the starting position for the playback.
  If the from parameter is not specified, playback begins at the current position.

to position
  Specifies the ending position for the playback.
  If the to parameter is not specified, play stops at the end of the media.

Comments

Before issuing any commands that use position values, you should set the desired
time format using the set command.

Example

The following command plays the "mysound" device from the beginning:

play mysound from 1

--------------------------------------------------------------------

close (Waveform Audio)

Syntax

close device_id [notify] [wait]
The close command closes the device element and any associated resources.

Example

The following command closes the "mysound" device:

close mysound

---------------------------------------------------------------------------

status (Waveform Audio)

Syntax

status device_id parameter [notify] [wait]
The status command gets status information for the device.

Parameters
Specify one of the following items for parameter:

alignment
  Returns the block alignment of data in bytes.

bitspersample
  Returns the bits per sample.

bytespersec
  Returns the average number of bytes per second played or recorded.

channels
  Returns the number of channels set (1 for mono, 2 for stereo).

current track
  Returns the index for the current track. The MCIWAVE device returns 1.

format tag
  Returns the format tag.

input
  Returns the input set. If one is not set, the error returned indicates that any device can be used.

length
  Returns the total length of the waveform.

length track track_number
  Returns the length of the specified track.

level
  Returns the current audio sample value.

media present
  Returns true.

mode
  Returns not ready, paused, playing, stopped,  recording, or seeking for the device mode.

number of tracks
  Returns the number of tracks. The MCIWAVE device returns 1.

 output
   Returns the currently set output. If no output is set, the error returned indicates that any device can be used.

position
  Returns the current position.

position track track_number
  Returns the position of the track specified by track_number. The MCIWAVE device returns 0.

ready
  Returns true if the device is ready.

samplespersec
  Returns the number of samples per second played or recorded.

start position
  Returns the starting position of the media.

time format
  Returns the current time format.

Comments

Before issuing any commands that use position values, you should set the
desired time format using the set command.

Example

The following command returns the length of the waveform data in milliseconds (assuming the time format is set to milliseconds):

status mysound length

--------------------------------------------------------------------

set (Waveform Audio)

Syntax

set device_id parameters [notify] [wait]
The set command specifies various settings for the driver.

Parameters

Specify one or more of the following items for parameters:

alignment integer
  Sets the alignment of data blocks relative to the start of waveform data passed
  to the waveform audio device. The file is saved in this format.

any input
  Use any input that supports the current format when recording. This is the default.

any output
  Use any output that supports the current format when playing. This is the default.

audio all off
  Disables audio output.
  The MCIWAVE sequencer does not support this option.

audio all on
  Enables audio output.
  The MCIWAVE sequencer does not support this option.

audio left off
  Disables output to the left audio channel.
  The MCIWAVE sequencer does not support this option.

audio left on
  Enables output to the left audio channel.
  The MCIWAVE sequencer does not support this option.

audio right off
  Disables output to the right audio channel.
  The MCIWAVE sequencer does not support this option.

audio right on
  Enables output to the right audio channel.
  The MCIWAVE sequencer does not support this option.

bitspersample bit_count
  Sets the number of bits per sample played or recorded.
  The file is saved in this format.

bytespersec byte_rate
  Sets the average number of bytes per second played or recorded.
  The file is saved in this format.

channels channel_count
  Sets the channels for playing and recording.
  The file is saved in this format.

format tag tag
  Sets the format type for playing and recording.
  The file is saved in this format.

format tag pcm
  Sets the format type to PCM for playing and recording.
  The file is saved in this format.

input integer
  Sets the audio channel used as the input.

output integer
  Sets the audio channel used as the output.

samplespersec integer
  Sets the sample rate for playing and recording.
  The file is saved in this format.

time format bytes
  Sets the time format to bytes.
  All position information is specified as bytes following this command.

time format milliseconds
  Sets the time format to milliseconds.
  All commands that use position values will assume milliseconds.
  You can abbreviate milliseconds as ms.

time format samples
  Sets the time format to samples.
  All position information is specified as samples following this command.

Example

The following command sets the time format to milliseconds and sets
the waveform audio format to 8 bit, mono, 11 kHz:

set mysound time format ms bitspersample 8 channels 1 samplespersec 11025

---------------------------------------------------------------------------

set (CD Audio)

Syntax

set device_id parameters [notify] [wait]
The set command establishes control settings for the driver.

Parameters

Specify one or more of the following items for parameters:

audio all off
  Disables audio output.

audio all on
  Enables audio output.

audio left off
  Disables output to the left audio channel.

audio left on
  Enables output to the left audio channel.

audio right off
  Disables output to the right audio channel.

audio right on
  Enables output to the right audio channel.

door closed
  Retracts the tray and closes the door if possible.

door open
  Opens the door and ejects the tray if possible.

time format milliseconds
  Sets the time format to milliseconds.
  All commands that use position values will assume milliseconds.
  You can abbreviate milliseconds as ms.

time format msf
  Sets the time format to minutes, seconds, and frames.
  All commands that use position values will assume MSF.
  MSF is the default format for CD audio.
  Specify an MSF value as mm:ss:ff, where mm is minutes, ss is seconds, and ff is frames.
  You can omit a field if it and all following fields are zero.
  For example, 3, 3:0, and 3:0:0 are valid ways to express 3 minutes.
  The MSF fields have the following maximum values:

  Minutes        99
  Seconds        59
  Tracks        74

time format tmsf
  Sets the time format to tracks, minutes, seconds, and frames.
  All commands that use position values will assume TMSF.
  Specify a TMSF value as tt:mm:ss:ff, where tt is tracks, mm is minutes, ss is seconds,
  and ff is frames. You can omit a field if it and all following fields are zero.
  For example, 3, 3:0, 3:0:0, 3:0:0:0 all specify track 3.
  The TMSF fields have the following maximum values:

  Tracks        99
  Minutes        99
  Seconds        59
  Frames        74

Example

The following command sets the time format of the cdaudio device to tracks, minutes,
seconds, and frames:

set cdaudio time format tmsf
