View source for MciPlayFile

{{DISPLAYTITLE:mciPlayFile}}
This function plays a multimedia data file (such as digital audio or video), or a digital audio element of a RIFF compound file, using media control interface commands. It opens, plays, and closes the file. `mciPlayFile` is a 32-bit function that is also provided as a 16-bit entry point.

The `mciPlayFile` function requires a message queue.

==Syntax==
 mciPlayFile(hwndOwner, pszFile, ulFlags,
             pszTitle, hwndViewport)

==Parameters==
;''hwndOwner'' ([[HWND]]) - input
:Window handle of the owner window. If this parameter is **NULL**, the currently active window is used.

;''pszFile'' ([[PSZ]]) - input
:Pointer to a multimedia file name. Compound-file names are also supported. For example:
<PRE>
a:\path\file+element
</PRE>

;''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 command issued by either **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 proceed 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 will return 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 should return immediately with an **MCIERR_NO_ASYNC_PLAY_ACTIVE**.
::* If another **MCI_RENDEZVOUS** command is pending, this command should return immediately with an **MCIERR_NO_ASYNC_PLAY_ACTIVE**.

;''pszTitle'' ([[PSZ]]) - input
:Title for window if one is generated. The title is ignored if a window would not be generated (for example, an audio file is to be played).

;''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** File is read only, or is opened for write mode by other application.
:* **MCIERR_INSTANCE_INACTIVE** The device is currently inactive. Can be returned if another application has opened or acquired the device for exclusive use. Issue [[MCI_ACQUIREDEVICE]] to activate the 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.

==How to Override==
This method is not covered in the provided text.

==Usage==
This method is not covered in the provided text.

== Remarks ==
This function provides a simple way of playing a multimedia data file. It supports any multimedia file type or RIFF compound files.

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 file **synchronously** unless the **MCI_ASYNC** or **MCI_ASYNCRENDEZVOUS** flag is specified. The message queue is processed during its processing.

When the file name that is passed is a **NULL** pointer or an empty buffer, then an **MCIERR_MISSING_PARAMETER** error is returned unless the **MCI_STOPACTIVE** or **MCI_RENDEZVOUS** flags are set. In order to stop a currently active command, use the **MCI_STOPACTIVE** flag.

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.

When the *pszFile* parameter is specified and there is an active **PLAY** command associated with the specified owner window, the first command is superseded by the second command.

==Example Code==
<PRE>
#define INCL_MACHDR
#define INCL_MCIOS2
#include <os2.h>

HWND hwndOwner; /* Window handle. */
PSZ pszFile; /* Pointer to file name. */
ULONG ulFlags; /* Flags. */
PSZ pszTitle; /* Window title. */
HWND hwndViewport; /* Window handle for video image. */
ULONG rc; /* Return code. */

rc = mciPlayFile(hwndOwner, pszFile, ulFlags,
            pszTitle, hwndViewport);

/* The following code illustrates how to play a digital audio file. */

#define INCL_MCIOS2
#define INCL_MACHDR
#include <os2me.h>  /* Play a wave file      */
                    /* set to valid window handle */
ULONG rc;
HWND hwnd;
rc=mciPlayFile ( hwnd, "GONG.WAV", 0,0,0);
</PRE>

== Related Functions==
* [[mciPlayResource]]
* [[mciRecordAudioFile]]
* [[mmioRemoveElement]]
* [[mmioFindElement]]

[[Category:mci]]