Jump to content

mciPlayResource

From EDM2

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

Retrieved from "https://www.edm2.com/index.php?title=MciPlayResource&oldid=90503"