MciGetErrorString

This function fills the caller's buffer with the textual string associated with the given error code returned by the OS/2 multimedia function. It also contains a 16-bit entry point.

Syntax

mciGetErrorString(ulError, pszBuffer, usLength)

Parameters

ulError (ULONG) - input

Specifies the error code. The low-order word contains the error code and the high-order word contains the device ID. The device ID is used by OS/2 multimedia to determine if there are device-dependent errors. If there are device-dependent errors then OS/2 multimedia returns the device-dependent error string.

pszBuffer (PSZ) - output

Pointer to the application's buffer. The textual error string will be copied to this buffer based on the length of the buffer.

usLength (USHORT) - input

Specifies the size of the application's buffer.

Returns

rc (ULONG) - returns

Return code.

MCIERR_SUCCESS

Error code returned indicating success or type of failure.

MCIERR_INVALID_DEVICE_ID

The device ID is not valid. :;

MCIERR_OUTOFRANGE

The error code specified is not valid.

MCIERR_INVALID_BUFFER

The buffer address specified is not valid.

Remarks

The maximum string length returned is 128 bytes. If the size of the application's buffer (usLength) is smaller than the size of the error string to be returned, then only usLength bytes of the error string will be copied into the application's buffer. Therefore, a buffer size of 128 bytes is recommended to avoid this problem.

Example Code

Declaration:

 
#define INCL_MCIOS2
#include <os2.h>

ULONG     ulError;    /*  Error code. */
PSZ       pszBuffer;  /*  Pointer to application's buffer. */
USHORT    usLength;   /*  Length of buffer. */
ULONG     rc;         /*  Return code. */

rc = mciGetErrorString(ulError, pszBuffer,
       usLength);