MMProgRef - String Commands

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:

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

ACQUIRE (System Command) - Example

acquire digitalvideo exclusive wait

ACQUIRE (System Command) - Purpose

The **ACQUIRE** command acquires use of the physical resources for the device. The **EXCLUSIVE** and **EXCLUSIVE INSTANCE** keywords cannot be used together.

ACQUIRE (System Command) Keyword - object

object**: Object associated with this media control interface command. The object can be one of the following:

Device type
Device name
Filename
Alias