open MCI Command String

"open lpszDevice, lpszOpenFlags, lpszFlags"

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

The open MCI command string opens a MCI device, initializing it for further use. One of the most useful features of open is the ability to assign an alias to a device, which makes referring to a file opened implicitly through a device simpler. Although in some cases it is not necessary to open a device before using it, it should be done nonetheless. Once your program is finished using the device, it should close it using the close command string.

All MCI device types recognize the open command string.

Return Value

The open command string does not return a value.

Visual Basic-Specific Issues

None.

Parameters

lpszDevice

The device identifier string of the MCI device or file to open. When opening a file, it will be manipulated through its typically associated device unless you use the "type" option in lpszOpenFlags to use a different device. For example, opening a MIDI file opens it through the sequencer. If this is "new", then a new resource is created; use the "type" option in lpszOpenFlags to specify the device type.

lpszOpenFlags

Zero or more of the following options for opening the device:

"elementname" (digitalvideo)

Specifies the file to load when the device opens.

"alias device_alias" (all)

Assigns an alternate name that can be used in subsequent command strings. This is particularly useful to avoid referring to a lengthy filename multiple times. The device_alias can then be used in place of the device ID string.

"buffer buffer_size" (waveaudio)

Sets the size of the waveform audio device buffer, in seconds. Valid values range from 2 to 9 inclusive.

"parent hwnd" (digitalvideo, overlay)

Specifies a handle to the parent window for any windows the device may open. Windows opened by the device will become that window's children.

"shareable" (all)

Allow this particular instance of the device to be opened multiple times simultaneously, shared among any programs that wish to use it. However, the MCISEQ and MCIWAVE drivers do not support sharing.

"style child" (digitalvideo, overlay)

Open a window with the style of a child window.

"style overlapped" (digitalvideo, overlay)

Open a window with the style of an overlapped (regular) window.

"style popup" (digitalvideo, overlay)

Open a window with the style of a pop-up window.

"style style_type" (digitalvideo, overlay)

Open a window with the specified style. style_type is the numerical value of one of the following flags:

SW_HIDE: Hide the window.
SW_MAXIMIZE: Maximize the window.
SW_MINIMIZE: Minimize the window.
SW_RESTORE: Restore the window (not maximized nor minimized).
SW_SHOW: Show the window.
SW_SHOWMAXIMIZED: Show the window maximized.
SW_SHOWMINIMIZED: Show the window minimized.
SW_SHOWMINNOACTIVE: Show the window minimized but do not activate it.
SW_SHOWNA: Show the window in its current state but do not activate it.
SW_SHOWNOACTIVATE: Show the window in its most recent size and position but do not activate it.
SW_SHOWNORMAL: Show the window and activate it (as usual).

"type device_type" (all)

When opening a new instance of a device, this specifies the type of device being opened. Remember that "new" was specified as lpszDevice.

lpszFlags

Zero or more of the following options:

"notify": When the command finishes, post the MM_MCINOTIFY message to the window specified in the call to mciSendString.
"wait": Do not have mciSendString return until the command finishes.

Constant Definitions

Const SW_HIDE = 0
Const SW_MAXIMIZE = 3
Const SW_MINIMIZE = 6
Const SW_RESTORE = 9
Const SW_SHOW = 5
Const SW_SHOWMAXIMIZED = 3
Const SW_SHOWMINIMIZED = 2
Const SW_SHOWMINNOACTIVE = 7
Const SW_SHOWNA = 8
Const SW_SHOWNOACTIVATE = 4
Const SW_SHOWNORMAL = 1

Example

To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File".

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _
	lpszCommand As String, ByVal lpszReturnString As String, ByVal cchReturnLength _
	As Long, ByVal hwndCallback As Long) As Long
Public Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" (ByVal _
	fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) As Long

' Use the MCI to play or stop playback of a MIDI file.  The file C:\Music\canyon.mid
' is opened when the form opens.  The Play and Stop buttons behave as you'd expect.  The
' only potential surprise is that the current position is not reset when playback stops; it
' behaves just as pausing playback would.  The file closes when the form unloads.

' If anything goes wrong in the example, display a message box with
' the MCI error message text.

Private Sub Form_Load()
	' Open the file "C:\Music\canyon.mid" for later use in the example.
	' Give it an alias of "canyon" so we don't need to refer to the filename again.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("open C:\Music\canyon.mid alias canyon", "", 0, 0)
	If errcode <> 0 Then DisplayError errcode
End Sub

Private Sub cmdPlay_Click()
	' Begin playback of the MIDI file when this button is pressed.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("play canyon", "", 0, 0)
	If errcode <> 0 Then DisplayError errcode
End Sub

Private Sub cmdStop_Click()
	' Stop playback of the MIDI file when this button is pressed.
	' The position within the file does not move back to the beginning.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("stop canyon", "", 0, 0)
	If errcode <> 0 Then DisplayError errcode
End Sub

Private Sub Form_Unload(Cancel As Integer)
	' Close the MIDI file when the form unloads.  This is important, because the
	' MIDI driver can only work with one file at a time.  There's no need to check
	' for an error here, since we're just closing the file.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("close canyon", "", 0, 0)
End Sub

Private Sub DisplayError(ByVal errcode As Long)
	' This subroutine displays a dialog box with the text of the MCI error.  There's
	' no reason to use the MessageBox API function; VB's MsgBox function will suffice.
	Dim errstr As String  ' MCI error message text
	Dim retval As Long    ' return value
	
	' Get a string explaining the MCI error.
	errstr = Space(128)
	retval = mciGetErrorString(errcode, errstr, Len(errstr))
	' Remove the terminating null and empty space at the end.
	errstr = Left(errstr, InStr(errstr, vbNullChar) - 1)
	
	' Display a simple error message box.
	retval = MsgBox(errstr, vbOKOnly Or vbCritical)
End Sub