stop MCI Command String

"stop lpszDeviceID, lpszStopFlags, 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 stop MCI command string stops playback of an playing MCI device. For audio CDs, the current position is reset to the beginning of the track that had been playing. For all other MCI devices, the current position remains where it had been playing.

The following MCI device types recognize the stop command string: cdaudio, digitalvideo, sequencer, vcr, videodisk, waveaudio.

Return Value

The stop command string does not return any data.

Visual Basic-Specific Issues

None.

Parameters

lpszDeviceID

The device identifer string of the MCI device or file to stop playback of. This may be an alias to the device or file.

lpszStopFlags

The following option may be specified only for digitalvideo devices:

"hold": Do not release the resources needed to draw the current still image on the screen. This allows the currently displayed frame of the stopped video to be redrawn as necessary (for example, if the playback window moves).

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.

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