MciSendString: Difference between revisions

Latest revision as of 02:14, 26 November 2025

This function sends a media control interface command string to a media device. It also contains a 16-bit entry point.

Syntax

mciSendString(pszCommandBuf, pszReturnString,
              usReturnLength, hwndCallBack, usUserParm)

Parameters

pszCommandBuf (PSZ) - input: Media control command string of the form:

    <command> <object> <keywords>

The object can be the device type, file name, alias, and so forth.

pszReturnString (PSZ) - output: An application-supplied buffer for the return data. This pointer can be **NULL** if no return information is desired. For more information see String Commands.

usReturnLength (USHORT) - input: The number of bytes reserved for *pszReturnString*.

hwndCallBack (HWND) - input: A PM window handle to be used in returning asynchronous notification messages. This parameter must be specified if **notify** was specified in the command string.

usUserParm (USHORT) - input: User parameter returned in the notification for this message.

Returns

rc (ULONG) - returns: Returns **MCIERR_SUCCESS** in the low-order word if there was no error; otherwise it returns an error code in the low-order word of the return value. Use mciGetErrorString to convert this code to a string. If the error code is a device-dependent error, the high-order word will contain the device ID.

Remarks

If *pszReturnString* is **NULL** or *usReturnLength* is 0, no data will be returned.

If the return code is **MCIERR_SUCCESS** and the command does return data (such as **status**), the string parser will convert the return data to string format if appropriate. An example is **status cdaudio media present** would return **TRUE** or **FALSE**. If the application requests the return value to be converted to a string by the string parser, it must specify the **WAIT** flag. See String Commands for a description of the media control interface strings and return values.

Example Code

#define INCL_MCIOS2
#include <os2.h>

PSZ pszCommandBuf;  /* Media control command string. */
PSZ pszReturnString; /* Application-supplied buffer. */
USHORT usReturnLength; /* Bytes reserved. */
HWND hwndCallBack; /* Window handle. */
USHORT usUserParm; /* User-specified parameter. */
ULONG rc; /* Return code. */

rc = mciSendString(pszCommandBuf, pszReturnString,
            usReturnLength, hwndCallBack, usUserParm);

/* The following code illustrates how to send a command to a specified device. */

      CHAR szBuffer[128];         /* String command buffer      */

      strcpy (szBuffer, "open bell.wav alias wav1 wait");
                                  /* String command to open     */

      mciSendString ((PSZ)szBuffer,       /* Open a wav file             */
                     NULL,                /* No return data              */
                     0,                   /* No return length            */
                     0,                   /* No window callback handle   */
                     0);                  /* No notify message           */

      strcpy (szBuffer, "play wav1 wait");/* String command to play      */

      mciSendString ((PSZ)szBuffer,       /* Play a wav file             */
                     NULL,                /* No return data              */
                     0,                   /* No return length            */
                     0,                   /* No window callback handle   */
                     0);                  /* No notify message           */

      strcpy (szBuffer, "close wav1 wait");/* String command to close    */

      mciSendString ((PSZ)szBuffer,       /* Close a wav file            */
                     NULL,                /* No return data              */
                     0,                   /* No return length            */
                     0,                   /* No window callback handle   */
                     0);                  /* No notify message           */

Related Functions

@@ Line 15: / Line 15: @@
 ;''pszReturnString'' ([[PSZ]]) - output
-:An application-supplied buffer for the return data. This pointer can be **NULL** if no return information is desired. For more information see [[String Commands]].
+:An application-supplied buffer for the return data. This pointer can be **NULL** if no return information is desired. For more information see [[MMProgRef - String Commands|String Commands]].
 ;''usReturnLength'' ([[USHORT]]) - input
@@ Line 33: / Line 33: @@
 If *pszReturnString* is **NULL** or *usReturnLength* is 0, no data will be returned.
-If the return code is **MCIERR_SUCCESS** and the command does return data (such as **status**), the string parser will convert the return data to string format if appropriate. An example is **status cdaudio media present** would return **TRUE** or **FALSE**. If the application requests the return value to be converted to a string by the string parser, it must specify the **WAIT** flag. See [[String Commands]] for a description of the media control interface strings and return values.
+If the return code is **MCIERR_SUCCESS** and the command does return data (such as **status**), the string parser will convert the return data to string format if appropriate. An example is **status cdaudio media present** would return **TRUE** or **FALSE**. If the application requests the return value to be converted to a string by the string parser, it must specify the **WAIT** flag. See [[MMProgRef - String Commands|String Commands]] for a description of the media control interface strings and return values.
 ==Example Code==