77.3.1 Sending Command Strings Using MciSendString

Use the mciSendString function to send command strings to a device. It has the following syntax:

DWORD mciSendString(lpstrCommand, lpstrRtnString, wRtnLength, hCallback)

The far pointer lpstrCommand points to a null-terminated string containing the MCI string command. The string command has the following form:

command device_name arguments

The second parameter, lpstrRtnString, points to an application-supplied buffer for a return string. The third parameter, wRtnLength, specifies the size of this buffer. If an MCI command returns a value or a string, MCI copies it into lpstrRtnString as a null-terminated string (integers are converted to strings). If the length of the return string exceeds the size of the buffer, MCI returns an error. You can assign NULL to lpstrRtnString if you don't want the return string, or for commands that don't supply return information.

The last parameter, hCallback, is a handle to the window that receives the MM_MCINOTIFY message. MCI ignores this parameter unless the command contains the notify flag. This parameter must contain a valid window handle if the notify flag is used.

The following statement passes the “play to 500” command string to a waveform audio device driver:

dwErrorCode = mciSendString ("play waveaudio to 500", NULL, 0, 0L);

The mciSendString function returns zero if successful. If the function fails, it returns an error code. If there is an error, you can get a description of it by passing the error code to mciGetErrorString.