mciPlayResource

This function plays a multimedia resource, such as a waveform, MIDI, or video, on the default device associated with the resource type. `mciPlayResource` is a 32-bit function that is also provided as a 16-bit entry point.

Syntax

mciPlayResource(hwndOwner, hmod, resType,
                resID, ulFlags, pszTitle, hwndViewport)

Parameters

hwndOwner (HWND) - input: Window handle of the owner window. If this parameter is **NULL**, then the currently active window is used.

hmod (HMODULE) - input: Module handle of the module that contains the resource. The resource is loaded using **DosGetResource**. **NULL** indicates the program file's resources.

resType (ULONG) - input

Defines resource type with one of the following values:

**RT_WAVE** Resource type is digital audio.
**RT_AVI** Resource type is digital video using the AVI file format.
**RT_RMID** Resource type is MIDI.
**RT_RIFF** Resource type is RIFF. Any of the resource types can be contained within this resource type.

resID (ULONG) - input: Identifier for resource.

ulFlags (ULONG) - input

**MCI_OWNERISPARENT** Indicates that the owner window should be used as the parent window for any default window that is created. If this flag is passed to a device that does not support a parent window, an error is returned.
**MCI_STOPACTIVE** Indicates that any currently active **PLAY** command issued by mciPlayFile or **mciPlayResource** should be stopped.
**MCI_ASYNC** Indicates that the command should be processed asynchronously. A rendezvous command will not be done.
**MCI_ASYNCRENDEZVOUS** Indicates that the command should be processed asynchronously. A rendezvous command will be done.
**MCI_RENDEZVOUS** Indicates that the call should wait for a currently pending asynchronous command to complete.

If no command is pending, then it returns immediately.
If an asynchronous command is not pending, this function returns immediately. This flag indicates that the command should wait until a pending asynchronous play command completes and then return.
If a synchronous (default) play command is pending, this command returns immediately with a **MCIERR_NO_ASYNC_PLAY_ACTIVE**.
If another **MCI_RENDEZVOUS** command is pending, this command should return immediately with a **MCIERR_ASYNC_PLAY_ACTIVE**.

pszTitle (PSZ) - input: Title for window if one is generated. The title is ignored if a window would not be generated.

hwndViewport (HWND) - input: Window handle for displaying the video image. If a viewport window is not specified, then a default video window is displayed. This parameter only has an effect when the data type supports video.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

**MCIERR_SUCCESS** If the function succeeds, 0 is returned.
**MCIERR_NO_ASYNC_PLAY_ACTIVE** A synchronous (default) play command is pending or no asynchronous play is currently active for the associated owner window.
**MCIERR_MISSING_PARAMETER** Required parameter is missing.
**MCIERR_FILE_ATTRIBUTE** Returned if another application has opened or acquired the same device for exclusive use.
**MCIERR_INSTANCE_INACTIVE** The device is currently inactive. Issue **MCI_ACQUIREDEVICE** message to activate device ID.
**MCIERR_UNSUPPORTED_FLAG** Given flag is unsupported for this device.
**MCIERR_INVALID_CALLBACK_HANDLE** Given callback handle is invalid.
**MCIERR_UNSUPPORTED_FUNCTION** Unsupported function.
**MCIERR_FLAGS_NOT_COMPATIBLE** Flags can not be used together.
**MCIERR_FILE_NOT_FOUND** File has not been loaded.
**MCIERR_DUPLICATE_ALIAS** Alias already exists.
**MCIERR_INVALID_BUFFER** Invalid return buffer given.
**MCIERR_CANNOT_LOAD_DRIVER** The driver could not be loaded.
**MCIERR_DEVICE_LOCKED** The device is acquired for exclusive use.
**MCIERR_OUT_OF_MEMORY** Out of memory.

Remarks

This function provides a simple way of playing a multimedia resource stored in a program resource.

The audio is played on the default media control interface device. A device control panel is not displayed for audio.

Still images are not supported.

For video, the default media control interface driver window is displayed. The movie is played from beginning to end. The window is destroyed when the device is closed. If an *hwndViewport* window is specified, then the video will be shown in the viewport window.

The default is to play the resource **synchronously** unless the **MCI_ASYNC** or **MCI_ASYNCRENDEZVOUS** flag is specified. The message queue is processed during its processing.

Either mciPlayFile or **mciPlayResource** could return an **MCIERR_NO_ASYNC_PLAY_ACTIVE** error. This error indicates that no asynchronous play is currently active for the associated owner window.

The *pszTitle* parameter can be **NULL**. If a title is specified and a window is displayed, the title is used as the window title. A window is only displayed if a video file is played.

If the *resID* is 0, **MCIERR_MISSING_PARAMETER** is returned unless the **MCI_STOPACTIVE** or **MCI_RENDEZVOUS** flags are set. To stop a currently active command, use the **MCI_STOPACTIVE** flag.

Example Code

#define INCL_MACHDR
#define INCL_MCIOS2
#include <os2.h>

HWND hwndOwner; /* Window handle. */
HMODULE hmod; /* Module handle. */
ULONG resType; /* Resource type. */
ULONG resID; /* Resource identifier. */
ULONG ulFlags; /* Flags. */
PSZ pszTitle; /* Window title. */
HWND hwndViewport; /* Window handle. */
ULONG rc; /* Return code. */

rc = mciPlayResource(hwndOwner, hmod, resType,
            resID, ulFlags, pszTitle, hwndViewport);

/* Resource file examples: */
#include <os2medef.h>
RESOURCE RT_WAVE IDR_WAVE "zipper.wav"
RESOURCE RT_RMID IDR_MIDI "bach.mid"
RESOURCE RT_AVI  IDR_ULT "\\mmos2\\movies\\macaw.avi"
RESOURCE RT_RIFF IDR_WAVE "zipper.wav"
RESOURCE RT_RIFF IDR_MIDI "bach.mid"
RESOURCE RT_RIFF IDR_ULT "macaw.avi"

/* mciPlayResource usage example: */
#define INCL_MACHDR
#define INCL_MCIOS2
#include <os2me.h>
rc = mciPlayResource( hwnd,          /* Window handle */
                      hmod,          /* Resource module handle or 0 for EXE */
                      RT_WAVE,       /* Resource type */
                      IDR_WAVE,      /* Resource ID */
                      ulFlags,
                      szTitle,       /* Other API values */
                      hwndClient);

Related Functions