MCI_OPEN

This MCI command message initializes a device or device element. All devices respond to this message. The parameters and flags available for this message depend on the selected device. MMSYSTEM translates this message to the DRV_OPEN and MCI_OPEN_DRIVER messages sent to the device driver.

Parameters

DWORD lParam1

The following flags apply to all devices:

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback field of the data structure identified by lpOpen.

MCI_WAIT

Specifies that the open operation should finish before MCI returns control to the application.

MCI_OPEN_ALIAS

Specifies that an alias is included in the lpstrAlias field of the data structure identified by lpOpen.

MCI_OPEN_SHAREABLE

Specifies that the device or device element should be opened as shareable.

MCI_OPEN_TYPE

Specifies that a device type name or constant is included in the lpstrDeviceType field of the data structure identified by lpOpen.

MCI_OPEN_TYPE_ID

Specifies that the low-order word of the lpstrDeviceType field of the associated data structure contains a standard MCI device type ID and the high-order word optionally contains the ordinal index for the device. Use this flag with the MCI_OPEN_TYPE flag.

LPMCI_OPEN_PARMS lParam2

Specifies a far pointer to the MCI_OPEN_PARMS data structure. (Devices with extended command sets might replace this data structure with a device-specific data structure.)

Flags for Compound Devices

DWORD lParam1

The following additional flags apply to compound devices:

MCI_OPEN_ELEMENT

Specifies that an element name is included in the lpstrElementName field of the data structure identified by lParam2.

MCI_OPEN_ELEMENT_ID

Specifies that the lpstrElementName field of the data structure identified by lParam2 is interpreted as a DWORD and has meaning internal to the device. Use this flag with the MCI_OPEN_ELEMENT flag.

LPMCI_OPEN_PARMS lParam2

Specifies a far pointer to the MCI_OPEN_PARMS data structure. (Devices with additional parameters might replace this data structure with a device-specific data structure.)

Animation Extensions

DWORD lParam1

The following flags apply to animation devices:

MCI_ANIM_OPEN_NOSTATIC

Specifies that the device should reduce the number of static (system) colors in the palette to two.

MCI_ANIM_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParent field of the data structure identified by lParam2. The parent window handle is required for some window styles.

MCI_ANIM_OPEN_WS

Indicates a window style is specified in the dwStyle field of the data structure identified by lParam2. The dwStyle value specifies the style of the window that the driver will create and display if the application does not provide one. The style parameter takes an integer which defines the window style. These constants are the same as the ones in WINDOWS.H (such as WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP).

LPMCI_ANIM_OPEN_PARMS lParam2

Specifies a far pointer to the MCI_ANIM_OPEN_PARMS data structure.

Video Overlay Extensions

DWORD lParam1

The following flags apply to video overlay devices:

MCI_OVLY_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParent field of the data structure identified by lParam2.

MCI_OVLY_OPEN_WS

Indicates a window style is specified in the dwStyle field of the data structure identified by lParam2. The dwStyle value specifies the style of the window that the driver will create and display if the application does not provide one. The style parameter takes an integer that defines the window style. These constants are the same as those in WINDOWS.H (for example, WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP).

LPMCI_OVLY_OPEN_PARMS lParam2

Specifies a far pointer to the MCI_OVLY_OPEN_PARMS data structure.

Waveform Audio Extensions

DWORD lParam1

The following flags apply to waveform audio devices:

MCI_WAVE_OPEN_BUFFER

Indicates a buffer length is specified in the dwBuffer field of the data structure identified by lParam2.

LPMCI_WAVE_OPEN_PARMS lParam2

Specifies a far pointer to the MCI_WAVE_OPEN_PARMS data structure. (Devices with extended command sets might replace this data structure with a device-specific data structure.)

Return Value

Returns zero if the open is successful. If an error occurs, it returns the following values:

MCIERR_CANNOT_LOAD_DRIVER

Error loading media device driver.

MCIERR_DEVICE_OPEN

The device name is in use by this task. Use a unique alias.

MCIERR_DUPLICATE_ALIAS

The specified alias is an open device in this task.

MCIERR_EXTENSION_NOT_FOUND

Cannot deduce a device type from the given extension.

MCIERR_FILENAME_REQUIRED

A valid filename is required.

MCIERR_MISSING_PARAMETER

Required parameter is missing.

MCIERR_MUST_USE_SHAREABLE

The device is already open; use the shareable flag with each open.

MCIERR_NO_ELEMENT_ALLOWED

An element name cannot be used with this device.

Comments

If MCI_OPEN_SHAREABLE is not specified when a device or device element is initially opened, then all subsequent MCI_OPEN messages to the device or device element will fail. If the device or device element is already open, and this flag is not specified, the call will fail even if the first open command specified MCI_OPEN_SHAREABLE. Files for the MCISEQ and MCIWAVE devices are nonshareable.

Case is ignored in the device name, but there must not be any leading or trailing blanks.

To use automatic type selection (via the [mci extensions] section of the WIN.INI file), assign the file name (including file extension) to the lpstrElementName field, assign a NULL pointer to the lpstrDeviceType field, and set the MCI_OPEN_ELEMENT flag.

See Also

MCI_CLOSE, MCI_CLOSE_DRIVER, MCI_OPEN_DRIVER