pause MCI Command String

"pause lpszDeviceID, 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 pause MCI command string pauses playback of an playing MCI device. Typically, the current position does not change as a result of pausing playback.

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

Return Value

The pause 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 pause. This may be an alias to the device or file.

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.
"test" (digitalvideo and vcr only): Test to see if the device supports the pause command. The device is not actually paused, and the call to mciSendString only returns successfully if the device supports the pause command.
"wait": Do not have mciSendString return until the command finishes.

Example

To run this code, place three command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI File". Name another one "cmdStop" and set its Caption to "&Stop MIDI File". Finally, if you haven't figured it out yet, name the last one "cmdPause" and set its Caption to "&Pause 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, stop, or pause playback of a MIDI file.  The file C:\Music\canyon.mid
' is opened when the form opens.  The various 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 cmdPause_Click()
	' Pause playback of the MIDI file when this button is pressed.
	' The position within the file, naturally, does not revert to the beginning.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("pause 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