MCI_OPEN

This message is used to open or create a new device instance.

Syntax

param1
ULONG ulParam1; /* Flags for open operation. */

param2
PMCI_OPEN_PARMS pParam2; /* Pointer to the MCI_OPEN_PARMS data structure. */

Parameters

ulParam1 (ULONG) - input

This parameter can contain any of the following flags. **MCI_OPEN_ELEMENT** and **MCI_OPEN_MMIO** are mutually exclusive flags:

MCI_NOTIFY A notification message will be posted to the hwndCallback parameter of the data structure pointed to by the pParam2 parameter. The notification will be posted when the action indicated by this message is completed or when an error occurs.
MCI_WAIT Control is not to be returned until the action indicated by this message is completed or an error occurs.
MCI_DOS_QUEUE This flag specifies that window handles passed in for this device instance will be treated as OS/2 Control Program queue handles.
MCI_OPEN_ALIAS This flag specifies that the pszAlias field of the open structure contains an alias for this device instance. This alias can then be used on subsequent commands using the string interface.
MCI_OPEN_ELEMENT This flag specifies that an element name is included. The element name can be that of a file or a file element in a compound file. The element name is specified in the pszElementName field of the open data structure. If the element name does not exist or is NULL, then a temporary element is created for subsequent use. The temporary file can be made permanent by providing a name using the MCI_SAVE message.
MCI_OPEN_MMIO This flag specifies that an MMIO handle (hmmio) is passed in the pszElementName field of the open data structure. The file must have been opened through MMIO with ulTranslate of the MMIOINFO data structure set to **MMIO_TRANSLATEHEADER**, unless a particular MCD indicates differently.
MCI_OPEN_PLAYLIST This flag indicates that the pszElementName field of the open data structure contains a pointer to a memory playlist structure.
MCI_OPEN_READONLY This flag specifies that the file is to be opened in read-only mode. The load and run-time performance for the wave audio and digital video devices can be improved by specifying this flag. This flag can only be used in conjunction with the **MCI_OPEN_ELEMENT** or **MCI_OPEN_MMIO** flags. By specifying this flag, **MCI_RECORD** and **MCI_SAVE** are automatically disabled.
MCI_OPEN_SHAREABLE This flag specifies that the device instance is to be opened in a fully shareable mode. Omitting this flag causes the device instance to be opened for exclusive use.
MCI_OPEN_TYPE_ID This flag specifies that the pszDeviceType field of the open data structure is to be interpreted as follows. The low-order word is a standard device type and the high-order word is the ordinal index for the device. If **MCI_OPEN_TYPE_ID** is specified and the index is 0, the default device will be opened. If **MCI_OPEN_TYPE_ID** is not specified and the pszDeviceType field is not NULL, the media control interface will attempt to open the device specified by pszDeviceType. If **MCI_OPEN_TYPE_ID** is not specified, pszDeviceType is NULL, and the **MCI_OPEN_ELEMENT** flag is specified, the system attempts to select and open a device based on the element extension or EA type of the file specified in the pszElementName field of the open data structure.

- **Digital Video Extensions**:
MCI_DGV_OPEN_PARENT This flag indicates that the hwndParent field of the open data structure contains a valid parent window handle. If this flag is not specified, **HWND_DESKTOP** is assumed to be the parent window handle.

- **Video Overlay Extensions**:
MCI_OVLY_OPEN_PARENT This flag indicates that the hwndParent field of the open data structure contains a valid parent window handle. If this flag is not specified, **HWND_DESKTOP** is assumed to be the parent window handle.

pParam2 (PMCI_OPEN_PARMS) - input

A pointer to the MCI_OPEN_PARMS data structure. Devices with extended command sets might replace this pointer with a pointer to a device-specific data structure as follows:

PMCI_AMP_OPEN_PARMS A pointer to the MCI_AMP_OPEN_PARMS data structure.
PMCI_DGV_OPEN_PARMS A pointer to the MCI_DGV_OPEN_PARMS data structure.
PMCI_OVLY_OPEN_PARMS A pointer to the MCI_OVLY_OPEN_PARMS data structure.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

MCIERR_SUCCESS MMPM/2 command completed successfully.
MCIERR_OUT_OF_MEMORY System out of memory.
MCIERR_INVALID_DEVICE_ID Invalid device ID given.
MCIERR_MISSING_PARAMETER Missing parameter for this command.
MCIERR_DRIVER Internal MMPM/2 driver error.
MCIERR_INVALID_FLAG Invalid flag specified for this command.
MCIERR_UNSUPPORTED_FLAG Flag not supported by this MMPM/2 driver for this command.
MCIERR_DEVICE_LOCKED Device is locked.
MCIERR_FLAGS_NOT_COMPATIBLE Flags cannot be used together.
MCIERR_FILE_NOT_FOUND File not found.
MCIERR_INI_FILE MMPM2.INI file error.
MCIERR_OVLY_MAX_OPEN_LIMIT Opened maximum limit.
MCIERR_INVALID_MEDIA_TYPE Invalid media type given.
MCIERR_HARDWARE Hardware error.
MCIERR_FILE_ATTRIBUTE File attribute error specified.
MCIERR_NO_DEVICEDRIVER There was no device driver found or it is not operational.
MCIERR_UNSUPP_SAMPLESPERSEC The hardware does not support this sampling rate.
MCIERR_UNSUPP_BITSPERSAMPLE The hardware does not support this bits per sample setting.
MCIERR_UNSUPP_CHANNELS The hardware does not support this channel setting.
MCIERR_UNSUPP_FORMAT_MODE The hardware does not support this format mode.
MCIERR_UNSUPP_FORMAT_TAG The hardware does not support this format tag.
MMIOERR_ACCESS_DENIED The file cannot be opened.

Remarks

Case is ignored in the device name, but there must not be any leading or trailing blanks. Note that the device type is the pszDeviceType element of the open data structure, but it does not have a corresponding flag because it is required and does not have a command-string parameter. Also, if automatic type selection is desired (through the extensions or EA section or INI), the file name (including the file extension) must be passed in the pszElementName field, the pszDeviceType field must be left NULL, and the **MCI_OPEN_ELEMENT** flag must be set.

If a parent window handle is specified, but the window handle is invalid, the overlay device opens successfully, but uses **HWND_DESKTOP** as its parent.

Default Processing

If the **MCI_OPEN_SHAREABLE** flag is not specified, the device instance is opened for exclusive use.

If the **MCI_OPEN_TYPE_ID** flag is not specified and the pszDeviceType field of the open data structure is not NULL, the media control interface attempts to open the device specified by the pszDeviceType string. If pszDeviceType is NULL and **MCI_OPEN_ELEMENT** flag is specified, the media control interface attempts to select and open a device based on the element extension or EA type of the file specified in the pszElementName field of the open data structure.

If pszDeviceType is a device type ID with a NULL ordinal or a string device name with no ordinals, then the default device of the specified type is opened. The default device can be selected using the Multimedia Setup application.

Example Code

/* Open a waveaudio device context, specifying the element
   "speech.wav". */

ULONG rc;
MCI_OPEN_PARMS mop;
USHORT usDeviceID;

mop.hwndCallback = (HWND) NULL;     /* N/A - we're waiting        */
mop.usDeviceID = (USHORT) NULL;     /* This is returned           */
mop.pszDeviceType = (PSZ) NULL;     /* using default device type  */
mop.pszElementName = (PSZ) "speech.wav";
                                    /* File name to open          */
rc = mciSendCommand( 0,
    MCI_OPEN,                       /* MCI open message           */
    MCI_WAIT | MCI_OPEN_ELEMENT |
    MCI_OPEN_SHAREABLE,             /* Flags for this message     */
    (ULONG) &mop,                   /* Data structure             */
    0);                             /* No user parm               */
if (LOUSHORT(rc) == MCIERR_SUCCESS)
  {
   usDeviceID = mop.usDeviceID;     /* Return device ID           */
  }

Related Methods