MMProgRef - String Commands

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Multimedia Programming Reference

Introduction What's New... MCI Functions High-Level Macro Service Functions Subsystem Messages Notification Messages MCI Command Messages String Commands Memory Playlist Commands Graphic Button Control Secondary Window Functions MMIO Functions MMIO Messages CODEC Messages DIVE Functions Real-Time MIDI Functions SPI Functions Data Stream State Table SMH Messages DDCMD Messages VSD Commands SHD Messages SHC Messages Data Types Types of MIDI Messages Multimedia Specification Overview Resource Interchange File Format Multimedia File Formats RIFF Compound Files and Elements - Sharing and Access Return Codes Notices Glossary

The string interface enables application control of media devices using textual string commands. String commands are passed to the media control interface through the mciSendString function. Return information from string commands is converted to string format and returned in the *pszReturnString* parameter of mciSendString.

Not all functions available through the procedural interface, mciSendCommand, are available through the string interface. In general, operations that return complex data structures, such as a CD table of contents, are available only through the procedural interface. Operations that cause asynchronous responses to be generated, such as cue point and position advise, can be invoked from the string interface; however, their responses are returned to window procedures.

The keywords **WAIT** and **NOTIFY** are global keywords and are available for all commands except some system commands. As with the procedural interface, the default time base is **MMTIME**. The multimedia string parser is case insensitive.

Command Format

The string format is:

COMMAND --- object ---+-------------+--+------------+--+
                     |  keywords   |  |  WAIT      |
                     +-------------+  +------------+
                                      |  NOTIFY    |
                                      +------------+

where:

object         = device type | device name | filename | alias
keywords       = command-specific keywords
WAIT | NOTIFY = standard OS/2 multimedia definitions

The object associated with a media control interface command can be one of the following:

Device type

The default device of a given type. The possible types of controllable devices include the following:

Device	Description
videotape	Videotape player or recorder
videodisc	Videodisc player
cdaudio	CD-ROM device that supports standard compact disc playback
waveaudio	Device that supports digital audio files
sequencer	Device that supports MIDI files
digitalvideo	Device that supports audio/video files, either hardware-assisted or software motion video only

If you have multiple devices of the same type, the Multimedia Setup program allows you to decide which device should be the default for that type.

Device name

A name of a particular device. Device names are of the form **DevicetypeNN**, where **Devicetype** is one of the device types given above, and **NN** is a value (01, 02, ...) indicating which device of that type is to be controlled.

Filename

The name of a file to be opened or controlled. When a filename is opened, OS/2 multimedia first examines the file's extension, then its type, to determine which device is associated to the file.

Alias

A string that was specified on a previous OPEN command. This string can then be used as the object name in subsequent commands.

The only exception to the above command format is MASTERAUDIO, which does not require an object associated with the command. The format for MASTERAUDIO is:

MASTERAUDIO ---- keywords ---+----------+--+
                           |  WAIT    |
                           +----------+

How to Read the Syntax Diagram

The syntax diagram shows you how to specify a command so that the multimedia string parser can correctly interpret what you type. Read the syntax diagram from left to right and from top to bottom, following the horizontal baseline (the main path). The command name and items required to make the command work appear on the baseline; the items below the baseline are optional.

A line **ending** with an arrowhead means that the command syntax is continued. A line **starting** with an arrowhead means that the syntax is continued from the previous line. A vertical bar marks the end of the command syntax.

Command names are often followed by required or optional **keywords**, which affect the result of the command. Variables are represented in lowercase and must be replaced with a valid name or value you specify. In the following example, **object**, **devicealias**, and **devicetype** are variables. You must include any punctuation, such as parentheses or commas, that are shown in the diagram.

OPEN ---- object ----+-----------------------+--+------------+--+
                     +-- ALIAS devicealias --+  |  WAIT      |
                     +-- SHAREABLE -----------+  +------------+
                     +-- TYPE devicetype -----+  |  NOTIFY    |
                                                +------------+

In the OPEN command shown above, **object** is required, the **ALIAS**, **SHAREABLE**, and **TYPE** keywords are optional, and the **WAIT** and **NOTIFY** keywords are also optional.

Specifying Items Once in Any Order

A stack of keywords with a return arrow above the main path indicates that you can specify one or more keywords in any order, but you can specify each keyword only once.

                     +----------------------+
                     v                      |
COPY ---- object ----+--+------------+--+---+--+------------+--+
                     |  |  FROM pos  |  |     |  WAIT      |
                     +--+------------+--+     +------------+
                     |  |  TO pos    |  |     |  NOTIFY    |
                     +--+------------+--+     +------------+

Specifying One Item from a Stack

A stack of keywords with no return arrow means that you cannot specify more than one keyword from the stack.

SEEK ---- object ----+-- TO pos ----+--+------------+--+
                     |  TO START  --+  |  WAIT      |
                     +-- TO END ----+  +------------+
                                       |  NOTIFY    |
                                       +------------+

System Commands

System commands are interpreted directly by the media device manager (MDM), and are not passed to media control interface drivers. The following commands are system commands:

• ACQUIRE
• CONNECTION
• CONNECTORINFO
• DEFAULTCONNECTION
• GROUP
• MASTERAUDIO
• RELEASE
• SYSINFO

Required Commands

Required commands are standard commands that are recognized by all MCI devices. Additional options can be added to extend these commands, however an MCI device must still support the required options. The following commands are required commands:

   CAPABILITY
   CLOSE
   INFO
   OPEN
   STATUS

Basic Commands

In addition to the system and required commands, each device supports a set of device-type specific commands. Where possible, these type-specific commands are identical between device types. When type-specific commands are common to multiple devices, they are considered basic commands. For example, the basic PLAY command is identical for videodisc, wave audio, and CD audio players.

Although these commands are optional for a device, if a command is used it must recognize the options listed here and return MCIERR_UNSUPPORTED_FLAG for options that are not applicable.

For those devices that do not support a basic command, such as a RECORD command sent to a CD audio player, an MCIERR_UNSUPPORTED_FUNCTION is returned by that MCD. If a message is sent to a device that is not recognized, then MCIERR_UNRECOGNIZED_COMMAND is returned. Before using a basic command, an application can issue a CAPABILITY query to see if the device supports the command.

The following commands are basic commands:

   CONNECTION
   CONNECTOR
   LOAD
   PAUSE
   PLAY
   RECORD
   RESUME
   SAVE
   SEEK
   SET
   SETCUEPOINT
   SETPOSITIONADVISE
   STATUS
   STOP

Audio Amplifier Mixer Commands

The audio amplifier mixer device supports extensions to the basic and required command sets. A device context of the audio amplifier mixer is a channel, either stereo or monaural, so most commands apply to channel levels. The exception is commands that apply to the final (output) mix, such as master volume.

Note that volume commands can be sent directly to player devices. These devices forward the volume command to the connected audio amplifier mixer channel device context when the output of the player is to an amplifier mixer. Other shaping functions, such as bass and treble, must be sent to the amplifier mixer.

The ampmix device is a conduit of information and relies on another device to provide the flow of information. Therefore, commands for the transport of information (such as play, seek, or stop), are sent to the attached device. Commands for transforming the information (such as treble or bass) are sent directly to the ampmix device. If the application needs to talk directly to the ampmix device, the value of the stream connector can be queried using the CONNECTION command, which returns a device context connection. An alias can be established for the connected device. Ampmix commands can then be sent directly to the ampmix device.

The ampmix device supports the device-type specific command, MIXNOTIFY, and extensions to the following basic and required commands:

   CAPABILITY
   CONNECTOR
   MIXNOTIFY
   SET
   STATUS

CD Audio Commands

The CD audio device supports the device-type specific command, CUE, and extensions to the following basic and required commands:

   CAPABILITY
   CONNECTOR
   CUE
   INFO
   PLAY
   SET
   STATUS

CD/XA Commands

The CD/XA audio device supports the device-type specific command, CUE, and extensions to the following basic and required commands:

   CAPABILITY
   CONNECTOR
   CUE
   INFO
   PLAY
   SEEK
   SET
   STATUS

Digital Video Commands

The digital video device supports the following device-type specific commands and extensions to the following basic and required commands:

   CAPABILITY
   CONNECTOR
   COPY
   CUE
   CUT
   DELETE
   INFO
   LOAD
   OPEN
   PASTE
   PLAY
   PUT
   RECORD
   REDO
   SAVE
   REWIND
   SEEK
   SET
   SETTUNER
   STATUS
   STEP
   UNDO
   WHERE
   WINDOW

MIDI Sequencer Commands

The MIDI sequencer device supports the device-type specific command, CUE, and extensions to the following basic and required commands:

   CAPABILITY
   CLOSE
   CONNECTOR
   CUE
   SET
   STATUS

Videodisc Player Commands

The videodisc device supports the following device-type specific commands and extensions to the following basic and required commands:

   CAPABILITY
   CONNECTOR
   CUE
   ESCAPE
   INFO
   PAUSE
   PLAY
   SEEK
   SET
   SPIN
   STATUS
   STEP

Video Overlay Commands

The video overlay commands are the commands supported by the video overlay device for analog video. Information specific to the M-Motion Video Adapter/A, such as default values, is also provided.

The video overlay device for analog video supports the following device-type specific commands and extensions to the following basic and required commands:

   CAPABILITY
   CAPTURE
   CONNECTOR
   FREEZE
   INFO
   LOAD
   OPEN
   PUT
   RESTORE
   SAVE
   SET
   STATUS
   UNFREEZE
   WHERE
   WINDOW

Waveform Audio Commands

The waveform audio device supports the following device-type specific commands and extensions to the following basic and required commands:

   CAPABILITY
   CONNECTOR
   COPY
   CUE
   CUT
   DELETE
   LOAD
   PASTE
   RECORD
   REDO
   SEEK
   SET
   STATUS
   UNDO