Help Contents
MDKRef 1.0

MDKRef 1.0 is an online reference to the application programming interface (API) of Microsoft Multimedia Extensions 1.0. The Multimedia extensions API includes the functions, messages, and data structures you can use with the Microsoft Windows 3.0 API to create applications for Windows with Multimedia.

Function Overview

Message Overview

Data Structure Overview


Function Overview

This chapter gives an overview of the functions in the Multimedia extensions to Windows. The functions are organized into the following categories, some of which contain smaller groups of related functions:

High-Level Audio Services

Low-Level Waveform Audio Services

Low-Level MIDI Audio Services

Auxiliary Audio Services

Multimedia Movie Playback Services

File I/O Services

Media Control Interface Services

Joystick Services

Timer Services

Screen Saver Services

Debugging Services

For detailed information on any of the functions listed in this chapter, see Chapter 3, 'Function Directory.' Chapter 3 is an alphabetical listing of the functions in the Multimedia extensions to Windows.


High-Level Audio Services

The high-level audio services allow applications to play audio files directly, while the system manages audio playback. Use these functions to play memory-resident waveform sounds specified by filename, system alert level, or WIN.INI entries:

MessageBeep

Plays the sound that corresponds to a given system alert level.

sndPlaySound

Plays the sound that corresponds to the given filename or WIN.INI entry.

In addition to these two functions, the Media Control Interface provides high-level audio services. For an overview of the Media Control Interface functions, see the section 'Media Control Interface Services' in this chapter.


Low-Level Waveform Audio Services

The low-level waveform audio services allow applications to communicate directly with device drivers to manage waveform audio playback and recording. The low-level waveform audio services are divided into the following categories:

Querying Waveform Devices

Opening and Closing Waveform Devices

Recording Waveform Data

Playing Waveform Data

Handling Waveform Errors

Getting the Current Position of Waveform Devices

Controlling Waveform Playback

Controlling Waveform Recording

Changing Pitch and Playback Rate

Changing Playback Volume


Querying Waveform Devices

Before playing or recording a waveform, you must determine the capabilities of the waveform hardware that is present in the system. Use these functions to retrieve the number of waveform devices and the capabilities of these devices:

waveInGetNumDevs

Retrieves the number of waveform input devices present in the system.

waveInGetDevCaps

Retrieves the capabilities of a given waveform input device.

waveOutGetNumDevs

Retrieves the number of waveform output devices present in the system.

waveOutGetDevCaps

Retrieves the capabilities of a given waveform output device.


Opening and Closing Waveform Devices

You must first open a device before you can begin waveform playback or recording. Once you have finished using the device, you must close it so that it will be available to other applications. Use these functions to open and close waveform devices:

waveInOpen

Opens a waveform input device for recording.

waveInClose

Closes a specified waveform input device.

waveOutOpen

Opens a waveform output device for playback.

waveOutClose

Closes a specified waveform output device.


Playing Waveform Data

After opening a waveform output device, you can begin sending data blocks to the device. Before sending data blocks to the device, the data blocks must be prepared. Use the following functions to prepare data blocks and send them to a waveform output device:

waveOutPrepareHeader

Informs the waveform output device driver that the given data block should be prepared for playback.

waveOutWrite

Writes a data block to a waveform output device.

waveOutUnprepareHeader

Informs the waveform output device driver that the preparation performed on the given data block can be cleaned up.


Recording Waveform Data

After opening a waveform input device, you can begin recording waveform data. To record waveform data, you must supply the waveform input device with data buffers. These data buffers must be prepared before being sent to the waveform device. Use the following functions to prepare data buffers and send them to waveform input devices:

waveInAddBuffer

Sends a data buffer to a waveform output device. The data buffer is filled with recorded waveform data and sent back to the application.

waveInPrepareHeader

Informs the waveform input device driver that the given data buffer should be prepared for recording.

waveInUnprepareHeader

Informs the waveform input device driver that the preparation performed on the given data buffer can be cleaned up.


Getting the Current Position of Waveform Devices

While you are playing or recording waveform audio, you can query the device for the current playback or recording position. Use these functions to determine the current position of a waveform device:

waveInGetPosition

Retrieves the current recording position of a waveform input device.

waveOutGetPosition

Retrieves the current playback position of a waveform output device.


Controlling Waveform Playback

Waveform playback begins as soon as you start sending data to the waveform output device. Use these functions to pause, restart, or stop playback and to break loops on a waveform device:

waveOutBreakLoop

Breaks a loop on a waveform output device.

waveOutPause

Pauses playback on a waveform output device.

waveOutRestart

Resumes playback on a paused waveform output device.

waveOutReset

Stops playback on a waveform output device. Marks all pending data blocks as being done.


Controlling Waveform Recording

When recording waveform audio, you can control when recording starts and stops. Use these functions to start and stop recording on a waveform input device:

waveInStart

Starts recording on a waveform input device.

waveInStop

Stops recording on a waveform input device.

waveInReset

Stops recording on a waveform input device. Marks all pending data blocks as being done.


Changing Pitch and Playback Rate

Some waveform output devices can scale the pitch and the playback rate when playing a waveform. Both of these operations have the effect of changing the pitch of the waveform without altering the playback time. Use these functions to query and set waveform pitch and playback rate scale factors:

waveOutGetPitch

Queries the pitch scale factor for a waveform output device.

waveOutGetPlaybackRate

Queries the playback rate scale factor for a waveform output device.

waveOutSetPitch

Sets the pitch scale factor for a waveform output device.

waveOutSetPlaybackRate

Sets the playback rate scale factor for a waveform output device.


Changing Playback Volume

Some waveform output devices support changes to the playback volume level. Use these functions to query and set the volume level of waveform output devices:

waveOutGetVolume

Queries the current volume level of a waveform output device.

waveOutSetVolume

Sets the volume level of a waveform output device.


Handling Waveform Errors

Most of the low-level waveform audio functions return error codes. Use these functions to convert the error codes returned from waveform functions into a textual description of the error:

waveInGetErrorText

Retrieves a textual description of a specified waveform input error.

waveOutGetErrorText

Retrieves a textual description of a specified waveform output error.


Low-Level MIDI Audio Services

The low-level MIDI audio services allow applications to communicate directly with device drivers to manage MIDI audio playback and recording. The low-level MIDI audio services are divided into the following categories of functions:

Querying MIDI Devices

Opening and Closing MIDI Devices

Sending MIDI Messages

Receiving MIDI Messages

Controlling MIDI Input

Changing MIDI Volume and Caching Patches

Handling MIDI Errors


Querying MIDI Devices

Before playing MIDI audio, you must determine the capabilities of the MIDI hardware that is present in the system. Use the following functions to get the number of MIDI devices and the capabilities of these devices:

midiInGetNumDevs

Retrieves the number of MIDI input devices present in the system.

midiInGetDevCaps

Retrieves the capabilities of a given MIDI input device.

midiOutGetNumDevs

Retrieves the number of MIDI output devices present in the system.

midiOutGetDevCaps

Retrieves the capabilities of a given MIDI output device.


Opening and Closing MIDI Devices

After getting the MIDI capabilities, you must open a MIDI device to play or record MIDI messages. After using the device, you should close it to make it available to other applications. Use the following functions to open and close MIDI devices:

midiInOpen

Opens a MIDI input device for recording.

midiInClose

Closes a specified MIDI input device.

midiOutOpen

Opens a MIDI output device for playback.

midiOutClose

Closes a specified MIDI output device.


Sending MIDI Messages

Once you have opened a MIDI output device, you can send it MIDI messages. MIDI system exclusive messages are sent in data blocks that must be prepared before being sent to an output device. Use the following functions to send MIDI messages to output devices and to prepare system exclusive data blocks:

midiOutLongMsg

Sends a MIDI system exclusive data block to a specified MIDI output device.

midiOutShortMsg

Sends any MIDI message other than a system exclusive message to the specified MIDI output device.

midiOutPrepareHeader

Informs the MIDI output device driver that the given system exclusive data block should be prepared for playback.

midiOutReset

Turns off all notes on all channels for a specified MIDI output device.

midiOutUnprepareHeader

Informs the MIDI output device driver that the preparation performed on the given system exclusive data block can be cleaned up.


Receiving MIDI Messages

Once you have opened a MIDI input device, you can begin receiving MIDI input. MIDI messages other than system exclusive messages are sent directly to a callback. To receive system exclusive messages, you must pass data buffers to the input device. These data buffers must be prepared before being sent to the device. Use the following messages to prepare system exclusive data buffers and pass these buffers to a MIDI input device:

midiInAddBuffer

Sends an input buffer for system exclusive messages to a specified MIDI input device. The buffer is sent back to the application when it is filled with system exclusive data.

midiInPrepareHeader

Informs a MIDI input device that the given data buffer should be prepared for recording.

midiInUnprepareHeader

Informs a MIDI input device that the preparation performed on the given data buffer can be cleaned up.


Controlling MIDI Input

When receiving MIDI input, you can control when the input starts and stops. Use these functions to start and stop input on a MIDI input device:

midiInStart

Starts input on a MIDI input device.

midiInStop

Stops input on a MIDI input device.

midiInReset

Stops input on a MIDI input device. Marks all pending data buffers as being done.


Changing MIDI Volume and Caching Patches

Some internal MIDI synthesizers support volume level changes and patch caching. Use these functions to query and set the volume level and to cache and uncache patches with internal MIDI synthesizer devices:

midiOutCacheDrumPatches

Requests that an internal MIDI synthesizer device preload a specified set of key-based percussion patches.

midiOutCachePatches

Requests that an internal MIDI synthesizer device preload a specified set of patches.

midiOutGetVolume

Queries the current volume level of an internal MIDI synthesizer device.

midiOutSetVolume

Sets the volume level of an internal MIDI synthesizer device.


Handling MIDI Errors

Most of the low-level MIDI audio functions return error codes. Use these functions to convert the error codes returned from MIDI functions into a textual description of the error:

midiInGetErrorText

Retrieves a textual description of a specified MIDI input error.

midiOutGetErrorText

Retrieves a textual description of a specified MIDI output error.


Auxiliary Audio Services

Auxiliary audio devices are audio devices whose output is mixed with the output of waveform and MIDI synthesizer devices. Use these functions to query the capabilities of auxiliary audio devices and to query and set their volume level:

auxGetDevCaps

Retrieves the capabilities of a given auxiliary audio device.

auxGetNumDevs

Retrieves the number of auxiliary audio devices present in a system.

auxGetVolume

Queries the volume level of an auxiliary audio device.

auxSetVolume

Sets the volume level of an auxiliary audio device.


Multimedia Movie Playback Services

The multimedia movie playback services provide support for playing Multimedia Movie files. The movie playback services are divided into the following categories:

Loading the Multimedia Movie Player

Handling Movie Files

Animating the Movie

Controlling the Playback Window

Controlling Playback


Loading the Multimedia Movie Player

Before playing a movie, you must open an instance of the Multimedia Movie Player. Use these functions to start, stop, and get information about the Movie Player:

mmpClose

Closes a Movie Player instance.

mmpError

Returns error information and optionally fills a character buffer with a descriptive error message.

mmpOpen

This function initializes a Movie Player instance.


Handling Movie Files

After opening a Movie Player instance, you can load a movie file. Use these functions to load and unload movie files and get information about movie files:

mmpFileLoaded

Determines whether a movie file has been loaded into the Movie Player instance.

mmpFreeFile

Frees memory associated with a movie file previously loaded by mmpLoadFile.

mmpGetFileInfo

Returns information about a movie file on disk.

mmpGetInfo

Returns a handle to an RMMP data structure.

mmpGetMovieInfo

Returns information about a movie file in memory.

mmpGetPaletteHandle

Returns a handle to the movie's palette.

mmpLoadFile

Loads a movie file and specifies playback options.

mmpSetInfo

Sets a handle to an RMMP data structure.


Animating the Movie

After starting the Movie Player and loading a movie file, you can start the animation. Use the following functions to start and stop the animation and advance the frames:

mmpAnimate

Performs the transition to the next movie frame.

mmpAnimStatus

Returns information about the playback status.

mmpAnimStopped

Determines whether the movie is stopped.

mmpStartAnimating

Starts the playback.

mmpStopAnimating

Stops the playback.


Controlling the Playback Window

The Movie Player provides various functions for controlling the playback window. The following functions assign a playback window and specify the position of the animation within the window, update an invalid rectangle on the playback window, and return information about the playback window:

mmpGetStage

Returns information about the stage window for a Movie Player instance.

mmpSetDC

Assigns a device context to a Movie Player instance.

mmpSetStage

Assigns a playback window to a Movie Player instance and specifies the position and size of the playback area within the window.

mmpUpdate

Updates an invalid rectangle on the stage window, generally in response to a WM_PAINT message.


Controlling the Playback

The following functions allow you to control various aspects of the playback:

mmpGetCurFrame

Returns the current frame number in the movie.

mmpGetFrameHook

Returns a pointer to the most recently attached frame-callback function.

mmpGetMute

Determines whether the Movie Player is disabling sound playback.

mmpGetRepeat

Determines whether the Movie Player instance is set to repeat the movie.

mmpGoToFrame

Jumps to a specified frame number.

mmpIsLastFrame

Determines whether the movie is at the last frame.

mmpRewind

This function rewinds the movie, setting the current frame to frame number 1.

mmpSetMute

Disables or enables the playback of audio cast members.

mmpSetFrameHook

Hooks a callback function into the frame advance.

mmpSetRepeat

Tells the Movie Player instance whether to continuously repeat the movie.


File I/O Services

The multimedia file I/O services provide buffered and unbuffered file I/O, and support for standard Resource Interchange File Format (RIFF) files. The services are extensible with custom I/O procedures that can be shared among applications.

The file I/O services are divided into the following categories:

Performing Basic File I/O

Performing Buffered File I/O

Working with RIFF Files

Using Custom I/O Procedures


Performing Basic File I/O

Using the basic file I/O services is very similar to using other file I/O services such as the C runtime file I/O services. Files must be opened before they can be read or written. After reading or writing, the file must be closed. You can seek to a specified position in an open file. Use the following functions for basic file I/O:

mmioClose

Closes an opened file.

mmioOpen

Opens a file for reading and/or writing, and returns a handle to the opened file.

mmioRead

Reads a specified number of bytes from an opened file.

mmioSeek

Changes the current position for reading and/or writing in an opened file.

mmioWrite

Writes a specified number of bytes to an opened file.


Performing Buffered File I/O

Using the basic buffered file I/O services is very similar to using the unbuffered services. Specify the MMIO_ALLOCBUF option with the mmioOpen function to open a file for buffered I/O. The file I/O manager will maintain an internal buffer which is transparent to the application.

You can also change the size of the internal buffer, allocate your own buffer, and directly access a buffer for optimal I/O performance. Use the following functions for I/O buffer control and direct I/O buffer access:

mmioAdvance

Fills and/or flushes the I/O buffer of a file set up for direct I/O buffer access.

mmioFlush

Writes the contents of the I/O buffer to disk.

mmioGetInfo

Gets information about the file I/O buffer of a file opened for buffered I/O.

mmioSetBuffer

Changes the size of the I/O buffer, and allows applications to supply their own buffer.

mmioSetInfo

Changes information about the file I/O buffer of a file opened for buffered I/O.


Working with RIFF Files

The preferred format for multimedia files is the Microsoft Resource Interchange File Format (RIFF). The RIFF format is based on a tagged-file structure using chunks identified by four-character codes. You can use the multimedia file I/O services to open, read, and write RIFF files the same way as you would any other type of file. You can also use the following functions to create chunks, convert characters and strings to four-character codes, and navigate between chunks in RIFF files:

mmioAscend

Ascends out of a RIFF file chunk to the next chunk in the file.

mmioCreateChunk

Creates a chunk in a RIFF file.

mmioDescend

Descends into a RIFF file chunk starting at the current file position, or searches for a specified chunk.

mmioFOURCC

Converts four individual characters into a FOURCC code.

mmioStringToFOURCC

Converts a NULL-terminated string into a FOURCC code.


Using Custom I/O Procedures

The multimedia file I/O services use I/O procedures to handle the physical input and output associated with reading and writing different types of storage systems. I/O procedures know how to open, close, read, write, and seek a particular type of storage system. Applications can supply custom I/O procedures for accessing unique storage systems such as databases or file archives. Use the following functions for working with custom I/O procedures:

mmioInstallIOProc

Installs, removes, or locates an I/O procedure.

mmioSendMessage

Sends a message to an I/O procedure associated with a specified file.


Media Control Interface Services

The Media Control Interface (MCI) provides a high-level generalized interface for controlling both internal and external media devices. MCI uses device handlers to interpret and execute high-level MCI commands. Applications can communicate with MCI device handlers either by sending messages, or by sending strings.

MCI also provides a set of macros for extracting time and position information from a packed DWORD. MCI uses the packed DWORD during operation of CD audio devices.


Communicating with MCI Devices

MCI parses the strings into messages that it then sends to the device handler. Use these functions to send messages or string commands to MCI, to get the ID assigned to a device, and to get a textual description of an MCI error:

mciSendCommand

Sends a command message to MCI.

mciSendString

Sends a command string to MCI.

mciExecute

A simple version of mciSendString. Handles errors by bringing up a dialog box.

mciGetDeviceID

Returns the device ID assigned when the device was opened.

mciGetErrorString

Returns the error string corresponding to an error number.

Most of the functionality of MCI is expressed in its command set. See the 'Message Overview' and 'Message Directory' chapters for an overview and reference to all MCI command messages. MCI command messages are prefixed with MCI.

In addition to its message-based interface, MCI has a string-based interface. For a reference to MCI command strings, see Chapter 7, 'MCI Command Strings.'


MCI Macros for CD Audio

MCI also has a set of macros defined to extract time and position information from the packed DWORD used to encode the time format for CD audio devices. The following list summarizes the macros:

MCI_MSF_FRAME

Returns the frames from the DWORD argument packed with minutes, seconds, and frames.

MCI_MSF_MINUTE

Returns the minutes from the DWORD argument packed with minutes, seconds, and frames.

MCI_MSF_SECOND

Returns the seconds from the DWORD argument packed with minutes, seconds, and frames.

MCI_TMSF_FRAME

Returns the frames from the DWORD argument packed with minutes, seconds, and frames.

MCI_TMSF_MINUTE

Returns the minutes from the DWORD argument packed with tracks, minutes, seconds, and frames.

MCI_TMSF_SECOND

Returns the seconds from the DWORD argument packed with tracks, minutes, seconds, and frames.

MCI_TMSF_TRACK

Returns the tracks from the DWORD argument packed with tracks, minutes, seconds, and frames.


Joystick Services

The joystick services provide support for up to two joystick devices. Use these functions to get information about joystick devices, to control joystick sensitivity, and to receive messages related to joystick movement and button activity:

joyGetDevCaps

Returns the capabilities of a joystick device.

joyGetNumDevs

Returns the number of devices supported by the joystick driver. The return value is zero if no driver is present.

joyGetPos

Returns the position and button state of a joystick.

joyGetThreshold

Returns the movement threshold of a joystick.

joyReleaseCapture

Releases the joystick captured with joySetCapture.

joySetCapture

Causes periodic joystick messages to be sent to the window specified.

joySetThreshold

Sets the movement threshold of a joystick.


Timer Services

The timer services allow applications to schedule timed periodic or one-time events at a higher resolution than is available through the standard Windows timer services. Use these functions to request and receive timer messages:

timeBeginPeriod

Establishes the minimum timer resolution an application intends to use.

timeEndPeriod

Clears a minimum timer resolution previously set by timeBeginPeriod.

timeGetDevCaps

Returns the capabilities of the timer device.

timeGetSystemTime

Fills an MMTIME structure with the system time in milliseconds.

timeGetTime

Returns the system time in milliseconds.

timeKillEvent

Cancels a timer event previously created with timeSetEvent.

timeSetEvent

Creates a timer event which will execute the action specified at periodic intervals or after a single period.


Screen Saver Services

The screen saver services provide support for creating screen saver applications. Screen saver applications temporarily replace the screen display of an inactive application. Use the following function in screen saver applications to process default actions:

DefScreenSaverProc

Provides default message processing for any messages that a screen saver application does not process.


Debugging Services

The debugging services provide support for debugging applications. Use the following functions to get the current version of the Multimedia extensions and to send debugging messages from an application:

mmsystemGetVersion

Gets the version number of the Multimedia extensions.

OutputDebugStr

Sends a debug string to either the COM1 port or to a monochrome display adapter.


Message Overview

This chapter gives an overview of the messages in the Multimedia extensions to Windows. The messages are organized into the following categories, some of which contain smaller groups of related messages:

Audio Messages

Media Control Interface Messages

Joystick Messages

File I/O Messages

Movie Player Messages

Screen Saver Messages

For detailed information on any of the messages listed in this chapter, see Chapter 5, 'Message Directory.' Chapter 5 is an alphabetical listing of the messages in the Multimedia extensions to Windows.


About Multimedia Extensions Messages

Unlike standard Windows messages, messages in the Multimedia extensions are not all sent to windows and do not all have a WORD and a DWORD parameter. Some messages are sent by an application and others are received by an application. The parameter types are dependent on the message.


Audio Messages

Audio messages are sent by low-level audio device drivers to an application so that the application can manage audio playback and recording. An application may choose to have audio messages sent either to a window, or to a low-level callback function. There is a set of messages for windows, and a parallel set of messages for low-level callback functions. The Multimedia extensions provide the following groups of audio messages:

Waveform Output Messages

Waveform Input Messages

MIDI Output Messages

MIDI Input Messages


Waveform Output Messages

Waveform output messages are sent by audio device drivers to an application to inform the application about the status of waveform output operations. By specifying flags with the waveOutOpen function, applications may choose to have messages sent either to a window or to a low-level callback function. Use these messages to manage waveform playback:

MM_WOM_CLOSE

Sent to a window when a waveform output device is closed.

MM_WOM_DONE

Sent to a window when a data block has been played and is being returned to the application.

MM_WOM_OPEN

Sent to a window when a waveform output device is opened.

WOM_CLOSE

Sent to a low-level callback function when a waveform output device is closed.

WOM_DONE

Sent to a low-level callback function when a data block has been played and is being returned to the application.

WOM_OPEN

Sent to a low-level callback function when a waveform output device is opened.


Waveform Input Messages

Waveform input messages are sent by audio device drivers to an application to inform the application about the status of waveform input operations. By specifying flags with the waveInOpen function, applications may choose to have messages sent either to a window or to a low-level callback function. Use these messages to manage waveform audio recording:

MM_WIM_CLOSE

Sent to a window when a waveform input device is closed.

MM_WIM_DATA

Sent to a window when an input data buffer is full and is being returned to the application.

MM_WIM_OPEN

Sent to a window when a waveform input device is opened.

WIM_CLOSE

Sent to a low-level callback function when a waveform input device is closed.

WIM_DATA

Sent to a low-level callback function when an input data buffer is full and is being returned to the application.

WIM_OPEN

Sent to a low-level callback function when a waveform input device is opened.


MIDI Output Messages

 $€«
€
¬€
€
€
‚ÿ
MIDI output messages are sent by audio device drivers to an application to inform the application about the status of MIDI output operations. By specifying flags with the
midiOutOpen
 function, applications may choose to have messages sent either to a window or to a low-level callback function. Use these message
MIM_LONGDATA

Sent to a low-level callback function when a MIDI system exclusive message is received by the device. The parameters to this message include a timestamp specifying the time that the MIDI message was received.


Media Control Interface Messages

Media Control Interface (MCI) messages control MCI devices, obtain information about a device's configuration and capabilities, and notifies a window function when a device completes a command. Applications use the mciSendCommand function to send MCI command messages to MCI device. MCI has the following groups of command messages:

System Command Messages

Required Command Messages

Basic Command Messages

Extended Command Messages

Window Notification Messages


System Command Messages

System command messages are interpreted directly by MCI. These messages do not rely on the abililty of a device to respond to them.

MCI_BREAK

Sent by an application to set a break key for a specified device.

MCI_SOUND

Sent by an application to play sounds identified by entries in the [sounds] section of WIN.INI.

MCI_SYSINFO

Sent by an application to query system-related information about a device.


Required Command Messages

Required command messages are supported by all MCI devices. These messages  open and close devices, and obtains information about devices.

MCI_CLOSE

Sent by an application to request that a specified device be closed.

MCI_GETDEVCAPS

Sent by an application to query a device about its capabilities.

MCI_INFO

Sent by an application to query information about a device. The information is returned in string format.

MCI_OPEN

Sent by an application to open a device and get an MCI device identifier for use with other commands.

MCI_STATUS

Sent by an application to query status information about a device.


Basic Command Messages

Basic command messages are recognized by all MCI devices. Although every device will recognize these commands, a particular device may not be able to respond to a command. If a device can not respond to a command, it returns MCIERR_UNSUPPORTED_FUNCTION.

MCI_PAUSE

Sent by an application to pause a device.

MCI_PLAY

Sent by an application to start a device playing.

MCI_RECORD

Sent by an application to start recording with a device.

MCI_SAVE

Sent by an application to save the current file.

MCI_SEEK

Sent by an application to change locations within a media element.

MCI_SET

Sent by an application to set parameters for a device.

MCI_STOP

Sent by an application to stop a device from playing or recording.


Extended Command Messages

Extended command messages apply to particular device types such as animation devices. Device types with extended commands have capabilities that are not present in most types of MCI devices. MCI has the following types of extended commands:

Extended Commands for Working with MCI Element Files

Extended Commands for Device Operation and Positioning

Extended Command for Windowed Video Devices


Extended Commands for Working with MCI Element Files

MCI devices that let you edit MCI data can have extended commands for manipulating data. The following commands apply to devices that support editing:

MCI_COPY

Sent by an application to copy data from the MCI element.

MCI_CUT

Sent by an application to remove a data segment from the MCI element.

MCI_LOAD

Sent by an application to load a file.

MCI_PASTE

Sent by an application to paste data into an the MCI element.


Extended Commands for Device Operation and Positioning

MCI devices can have operating capabilities that apply only to a device type or that apply to a device with unique features. The following commands apply to devices that have specialized operating capabilities:

MCI_CUE

Sent by an application to cue a device for playback.

MCI_ESCAPE

Sent by an application to send a string command to a device handler.

MCI_SPIN

Sent by an application to start or stop spinning a rotating media device such as a laserdisc.

MCI_STEP

Sent by an application to step a device one or more frames.


Extended Command for Windowed Video Devices

Video devices that display data in a window on the computer display can have MCI commands for controlling the video display and window. These devices include animation movie players, graphic devices, and video overlay devices. The following commands apply to windowed video devices:

MCI_FREEZE

Sent by an application to stop motion in the window during play.

MCI_PUT

Sent by an application to define a source or destination clipping rectangle.

MCI_REALIZE

Sent by an application to tell a graphic device to realize its palette.

MCI_UNFREEZE

Sent by an application to restore motion frozen during play.

MCI_UPDATE

Sent by an application to tell a graphic device to update or paint the current frame.

MCI_WHERE

Sent by an application to determine the extent of a clipping rectangle.

MCI_WINDOW

Sent by an application to specify a window and the characteristics of the window for a graphic device to use for its display.


Window Notification Messages

Window notification messages are sent by MCI to a window function when an application wants to be notified of the completion of a command. Specify the window function in the data structure sent with mciSendCommand.

MM_MCINOTIFY

Notifies the window function of the command status. The wParam parameter of this message contains the status of the command.


Joystick Messages

Joystick messages are sent to an application to notify the application that a joystick has moved or that one of its buttons has been pressed or released. Use these messages to get input from a joystick:

MM_JOY1BUTTONDOWN

Sent to a window that has captured joystick 1 when a button has been pressed.

MM_JOY1BUTTONUP

Sent to a window that has captured joystick 1 when a button has been released.

MM_JOY1MOVE

Sent to a window that has captured joystick 1 when the joystick position has changed.

MM_JOY1ZMOVE

Sent to a window that has captured joystick 1 when the joystick z-axis position has changed.

MM_JOY2BUTTONDOWN

Sent to a window that has captured joystick 2 when a button has been pressed.

MM_JOY2BUTTONUP

Sent to a window that has captured joystick 2 when a button has been released.

MM_JOY2MOVE

Sent to a window that has captured joystick 2 when the joystick position has changed.

MM_JOY2ZMOVE

Sent to a window that has captured joystick 2 when the joystick z-axis position has changed.


File I/O Messages

File I/O messages are sent to custom I/O procedures to request I/O operations on a file. I/O procedures must respond to all of the following messages:

MMIOM_CLOSE

Sent to an I/O procedure to request that a file be closed.

MMIOM_OPEN

Sent to an I/O procedure to request that a file be opened.

MMIOM_READ

Sent to an I/O procedure to request that data be read from a file.

MMIOM_SEEK

Sent to an I/O procedure to request that the current position for reading and writing be changed.

MMIOM_WRITE

Sent to an I/O procedure to request that data be written to a file.

MMIOM_WRITEFLUSH

Sent to an I/O procedure to request that an I/O buffer be flushed to disk.


Movie Player Messages

Movie Player messages are sent to a frame callback function to notify the application that a movie frame has been advanced and to send script-channel text to an application. Use these messages to get frame-advance information:

MMP_PROCESS_FRAME

Sent to a frame callback function after the Movie Player completes screen updates for the frame or subframe.

MMP_PROCESS_SCRIPT

Sent to a frame callback function before the Movie Player processes the script-channel text for the frame.


Screen Saver Messages

A screen saver message is sent when the screen saver is invoked. Use this message to prevent the screen saver from blanking the screen:

WM_SYSCOMMAND

Sent to an application when the screen saver is preparing to blank the screen.


Data Types and Structures

This chapter describes data types and data structures used in the Multimedia extensions to Windows. For information about standard Windows data types, see the Microsoft Windows Software Development Kit Reference Volume 2. This chapter contains three parts:

An alphabetical list of all Multimedia extensions data types

An overview of all data structures, organized by category. This overview includes brief descriptions of all data structures.

Detailed descriptions of all data structures, organized alphabetically. These descriptions list the structure definition and the type and contents of each field in the structure.

You can also refer to the MMSYSTEM.H and MMP.H header files to see the actual data structure definitions.


Data Types

The Multimedia extensions use the following data types:

FOURCC

A 32-bit value representing a four-character code.

HPSTR

A huge pointer to a character string.

HMIDIIN

A handle to a MIDI input device.

HMIDIOUT

A handle to a MIDI output device.

HMMIO

A handle to an open file.

HWAVEIN

A handle to a waveform input device.

HWAVEOUT

A handle to a waveform output device.

LPAUXCAPS

A far pointer to an AUXCAPS data structure.

LPHMIDIIN

A far pointer to an HMIDIIN handle.

LPHMIDIOUT

A far pointer to an HMIDIOUT handle.

LPHWAVEIN

A far pointer to an HWAVEIN handle.

LPHWAVEOUT

A far pointer to an HWAVEOUT handle.

LPJOYCAPS

A far pointer to a JOYCAPS data structure.

LPJOYINFO

A far pointer to a JOYINFO data structure.

LPMCI_ANIM_OPEN_PARMS

A far pointer to an MCI_ANIM_OPEN_PARMS data structure.

LPMCI_ANIM_PLAY_PARMS

A far pointer to an MCI_ANIM_PLAY_PARMS data structure.

LPMCI_ANIM_RECT_PARMS

A far pointer to an MCI_ANIM_RECT_PARMS data structure.

LPMCI_ANIM_SET_PARMS

A far pointer to an MCI_ANIM_SET_PARMS data structure.

LPMCI_ANIM_STEP_PARMS

A far pointer to an MCI_ANIM_STEP_PARMS data structure.

LPMCI_ANIM_UPDATE_PARMS

A far pointer to an MCI_ANIM_UPDATE_PARMS data structure.

LPMCI_ANIM_WINDOW_PARMS

A far pointer to an MCI_ANIM_WINDOW_PARMS data structure.

LPMCI_BREAK_PARMS

A far pointer to an MCI_BREAK_PARMS data structure.

LPMCI_GENERIC_PARMS

A far pointer to an MCI_GENERIC_PARMS data structure.

LPMCI_GETDEVCAPS_PARMS

A far pointer to an MCI_GETDEVCAPS_PARMS data structure.

LPMCI_INFO_PARMS

A far pointer to an MCI_INFO_PARMS data structure.

LPMCI_LOAD_PARMS

A far pointer to an MCI_LOAD_PARMS data structure.

LPMCI_OPEN_PARMS

A far pointer to an MCI_OPEN_PARMS data structure.

LPMCI_OVLY_OPEN_PARMS

A far pointer to an MCI_OVLY_OPEN_PARMS data structure.

LPMCI_OVLY_RECT_PARMS

A far pointer to an MCI_OVLY_RECT_PARMS data structure.

LPMCI_OVLY_UPDATE_PARMS

A far pointer to an MCI_OVLY_UPDATE_PARMS data structure.

LPMCI_OVLY_WINDOW_PARMS

A far pointer to an MCI_OVLY_WINDOW_PARMS data structure.

LPMCI_PLAY_PARMS

A far pointer to an MCI_PLAY_PARMS data structure.

LPMCI_RECORD_PARMS

A far pointer to an MCI_RECORD_PARMS data structure.

LPMCI_SAVE_PARMS

A far pointer to an MCI_SAVE_PARMS data structure.

LPMCI_SEEK_PARMS

A far pointer to an MCI_SEEK_PARMS data structure.

LPMCI_SEQ_SET_PARMS

A far pointer to an MCI_SEQ_SET_PARMS data structure.

LPMCI_SET_PARMS

A far pointer to an MCI_SET_PARMS data structure.

LPMCI_SOUND_PARMS

A far pointer to an MCI_SOUND_PARMS data structure.

LPMCI_STATUS_PARMS

A far pointer to an MCI_STATUS_PARMS data structure.

LPMCI_SYSINFO_PARMS

A far pointer to an MCI_SYSINFO_PARMS data structure.

LPMCI_VD_ESCAPE_PARMS

A far pointer to an MCI_VD_ESCAPE_PARMS data structure.

LPMCI_VD_PLAY_PARMS

A far pointer to an MCI_VD_PLAY_PARMS data structure.

LPMCI_VD_STEP_PARMS

A far pointer to an MCI_VD_STEP_PARMS data structure.

LPMCI_WAVE_CUT_PARMS

A far pointer to an MCI_WAVE_CUT_PARMS data structure.

LPMCI_WAVE_OPEN_PARMS

A far pointer to an MCI_WAVE_OPEN_PARMS data structure.

LPMCI_WAVE_SET_PARMS

A far pointer to an MCI_WAVE_SET_PARMS data structure.

LPMIDIHDR

A far pointer to a MIDIHDR structure.

LPMIDIINCAPS

A far pointer to a MIDIINCAPS structure.

LPMIDIOUTCAPS

A far pointer to a MIDIOUTCAPS structure.

LPMMIOPROC

A far pointer to an MMIOPROC function.

LPMMPFRAMEHOOK

A far pointer to a Multimedia Movie Player frame-hook callback function.

LPMMPMOVIEINFO

A far pointer to an MMPMOVIEINFO structure.

LPMMTIME

A far pointer to an MMTIME data structure.

LPTIMECALLBACK

A far pointer to a timer callback function.

LPTIMECAPS

A far pointer to a TIMECAPS data structure.

LPWAVEFORMAT

A far pointer to a WAVEFORMAT data structure.

LPWAVEHDR

A far pointer to a WAVEHDR data structure.

LPWAVEINCAPS

A far pointer to a WAVEINCAPS data structure.

LPWAVEOUTCAPS

A far pointer to a WAVEOUTCAPS data structure.

MMPID

An instance identifier for the Multimedia Movie Player.


Data Structure Overview

The Multimedia extensions use the following types of data structures:

Media Control Interface (MCI) Data Structures

Waveform Audio Data Structures

MIDI Audio Data Structures

Auxiliary Audio Data Structures

Movie Playback Data Structure

Timer Data Structures

Joystick Data Structures

File I/O Data Structures


Media Control Interface (MCI) Data Structures

The MCI data structures are divided into the following categories:

System Command Data Structures

Required Command Data Structures

Basic Command Data Structures

Extended Command Data Structures for Working with MCI Element Files

Extended Command Data Structures for Device Operation

Extended Command Data Structures for Windowed Video Devices


System Command Data Structures

The following data structures are used to specify parameter blocks for system command messages:

MCI_BREAK_PARMS

A data structure that specifies a parameter block for the MCI_BREAK command.

MCI_SOUND_PARMS

A data structure that specifies a parameter block for the MCI_SOUND command.

MCI_SYSINFO_PARMS

A data structure that specifies a parameter block for the MCI_SYSINFO command.


Required Command Data Structures

The following data structures are used to specify parameter blocks for command messages that apply to all MCI devices:

MCI_GETDEVCAPS_PARMS

A data structure that specifies a parameter block for the MCI_GETDEVCAPS command.

MCI_INFO_PARMS

A data structure that specifies a parameter block for the MCI_INFO command.

MCI_OPEN_PARMS

A data structure that specifies a parameter block for the MCI_OPEN command.

MCI_ANIM_OPEN_PARMS

A data structure that specifies a parameter block for the MCI_OPEN command when used with animation devices.

MCI_OVLY_OPEN_PARMS

A data structure that specifies a parameter block for the MCI_OPEN command when used with video overlay devices.

MCI_WAVE_OPEN_PARMS

A data structure that specifies a parameter block for the MCI_OPEN command when used with wave audio devices.

MCI_STATUS_PARMS

A data structure that specifies a parameter block for the MCI_STATUS command.


Basic Command Data Structures

The following data structures are used to specify parameter blocks for command messages that all devices must recognize:

MCI_GENERIC_PARMS

A data structure that specifies the parameters of a command which does not have message-specific parameters.

MCI_PLAY_PARMS

A data structure that specifies a parameter block for the MCI_PLAY command.

MCI_ANIM_PLAY_PARMS<$IMovie Player;MCI movie playback data structuresD¬$

A data structure that specifies a parameter block for the MCI_PLAY command used to play back movie files.

MCI_VD_PLAY_PARMS

A data structure that specifies a parameter block for the MCI_PLAY command used with videodisc players.

MCI_RECORD_PARMS

A data structure that specifies a parameter block for the MCI_RECORD command.

MCI_SAVE_PARMS

A data structure that specifies a parameter block for the MCI_SAVE command.

MCI_SEEK_PARMS

A data structure that specifies a parameter block for the MCI_SEEK command.

MCI_SET_PARMS

A data structure that specifies a parameter block for the MCI_SET command.

MCI_ANIM_SET_PARMS

A data structure that specifies a parameter block for the MCI_SET command used to configure animation devices.

MCI_SEQ_SET_PARMS

A data structure that specifies a parameter block for the MCI_SET command when used with the MCI MIDI sequencer.

MCI_WAVE_SET_PARMS

A data structure that specifies a parameter block for the MCI_SET command used with waveform audio devices.


Extended Command Data Structures for Working with MCI Element Files

The following data structures are used to specify parameter blocks for extended command messages that operate on MCI data:

MCI_LOAD_PARMS

A data structure that specifies a parameter block for the MCI_LOAD command.

MCI_WAVE_CUT_PARMS

A data structure that specifies a parameter block for the MCI_CUT command used with waveform audio devices.


Extended Command Data Structures for Device Operation

The following data structures are used to specify parameter blocks for command messages for devices that have specialized operating capabilities:

MCI_ANIM_STEP_PARMS

A data structure that specifies a parameter block for the MCI_STEP command when used with animation devices.

MCI_VD_ESCAPE_PARMS

A data structure that specifies a parameter block for the MCI_ESCAPE command.

MCI_VD_STEP_PARMS

A data structure that specifies a parameter block for the MCI_STEP command used with videodisc players.


Extended Command Data Structures for Windowed Video Devices

The following data structures are used to specify parameter blocks for command messages for windowed video devices:

MCI_ANIM_RECT_PARMS

A data structure that specifies a parameter block for the MCI_PUT and MCI_WHERE commands for animation devices.

MCI_OVLY_RECT_PARMS

A data structure that specifies a parameter block for the MCI_PUT and MCI_WHERE commands for video overlay devices.

MCI_ANIM_UPDATE_PARMS

A data structure that specifies a parameter block for the MCI_UPDATE command used with animation devices.

MCI_OVLY_UPDATE_PARMS

A data structure that specifies a parameter block for the MCI_UPDATE command used with video overlay devices.

MCI_ANIM_WINDOW_PARMS<$IStage window;MCI_ANIM_WINDOW_PARMS data strD¬$

A data structure that specifies a parameter block for the MCI_WINDOW command used to play back movie files.

MCI_OVLY_WINDOW_PARMS

A data structure that specifies a parameter block for the MCI_WINDOW command used with video overlay devices.


Waveform Audio Data Structures

The following data structures are used with waveform functions:

PCMWAVEFORMAT

A data structure representing the format of PCM waveform data.

WAVEFORMAT

A data structure representing generic format information common to all types of waveform data.

WAVEHDR

A data structure representing a header for waveform input and output data blocks.

WAVEINCAPS

A data structure that describes the capabilities of a waveform input device.

WAVEOUTCAPS

A data structure that describes the capabilities of a waveform output device.


MIDI Audio Data Structures

The following data structures are used with MIDI functions:

MIDIHDR

A data structure representing a header for MIDI input and output data blocks.

MIDIINCAPS

A data structure that describes the capabilities of a MIDI input device.

MIDIOUTCAPS

A data structure that describes the capabilities of a MIDI output device.

MMTIME

A data structure that represents time in one of several different formats.


Auxiliary Audio Data Structures

The following data structure is used with auxiliary audio devices:

AUXCAPS

A data structure that describes the capabilities of an auxiliary audio device.


Movie Playback Data Structure

The following data structure is used with movie playback functions:

MMPMOVIEINFO

A data structure that describes a multimedia movie file.


Timer Data Structures

The following data structures are used with timer functions:

MMTIME

A data structure that represents time in one of several different formats.

TIMECAPS

A data structure that defines timer capabilities.


Joystick Data Structures

The following data structures are used with joystick functions:

JOYCAPS

A data structure that defines joystick capabilities.

JOYINFO

A data structure for joystick information.


File I/O Data Structures

The following data structures are used with the multimedia file I/O functions:

MMIOINFO

A data structure for information about an open file.

MMCKINFO

A data structure for information about a RIFF chunk in an open file.


Data Structures Reference

The following section lists the Multimedia extensions data structures alphabetically. Each structure description shows the definition of the structure type and a description of each field in the structure.


MCI_BREAK

This MCI command message sets a break key for an MCI device. MCI supports this message directly rather than passing it to the device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices:

MCI_BREAK_KEY

Indicates the nVirtKeyfield of the data structure identified by lpBreak specifies the virtual key code used for the break key. This flag is required.

MCI_BREAK_HWND

Indicates the hwndBreakfield of the data structure identified by lpBreak contains a window handle which must be the current window in order to enable break detection for that MCI device. This is usually the application's main window.

MCI_BREAK_OFF

Used to disable any existing break key for the indicated device

LPMCI_BREAK_PARMS  lpBreak

Specifies a far pointer to the MCI_BREAK_PARMS data structure.

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	You might have to press the break key multiple times to interrupt a wait operation. Pressing the break key after a device wait is broken can send the break to the application. If you use the default definition of the break key (CTRL+BREAK),this might inadvertently close the application since CTRL+BREAK is also the Windows command to close an application.


MCI_CLOSE

This MCI command message realeases access to a device or device element. All devices respond to this message.

Parameters  	DWORD  dwFlags

The following flags apply to all devices:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpDefault when this command completes.

MCI_WAIT

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

LPMCI_GENERIC_PARMS  lpDefault

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	Exiting an application without closing any MCI devices it has opened can leave the device opened  and unaccessible. Your application should explicitly close each device or device element when it is finished with it. MCI unloads the device when all instances of the device or all device elements are closed.

See Also	MCI_OPEN, MM_MCINOTIFY


MCI_COPY

This MCI command message copies data from the MCI element. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_COPY:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpCopy when this command completes.

MCI_WAIT

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

LPMCI_GENERIC_PARMS  lpCopy

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command is not used by the device drivers supplied with the Multimedia Extensions 1.0.

See Also	MCI_CUT, MCI_PASTE, MM_MCINOTIFY


MCI_CUE

This MCI command message cues a device so that playback or recording begins with minimum delay. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_CUE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpDefault when this command completes.

MCI_WAIT

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

LPMCI_GENERIC_PARMS  lpDefault

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

Wave Audio Extensions

DWORD  dwFlags

The following additional flags apply to wave audio devices:

MCI_WAVE_INPUT

Specifies that a wave input device should be cued.

MCI_WAVE_OUTPUT

Specifies that a wave output device should be cued. This is the default flag if a flag is not specified.

LPMCI_GENERIC_PARMS  lpDefault

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

See Also	MCI_SEEK, MCI_PLAY, MCI_RECORD, MM_MCINOTIFY


MCI_CUT

This MCI command message removes data from the MCI element. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_CUT:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpCut when this command completes.

MCI_WAIT

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

MCI_FROM

Specifies that a beginning position is included in the dwFrom field of the data structure identified by lpCut. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_TO

Specifies that an ending position is included in the dwTo field of the data structure identified by lpCut. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

LPMCI_WAVE_CUT_PARMS  lpCut

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	The wave audio device uses this command.

See Also	MCI_COPY, MCI_PASTE, MM_MCINOTIFY


MCI_ESCAPE

This MCI command message sends a string directly to the device. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_COMMAND:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpEscape when this command completes.

MCI_WAIT

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

MCI_VD_ESCAPE_STRING

Indicates a command string is specified in the lpstrCommand field of the data structure identified by lpEscape.

LPMCI_VD_ESCAPE_PARMS  lpEscape

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	The data sent with MCI_ESCAPE is device dependent and is usually passed directly to the hardware associated with the device.


MCI_FREEZE

This MCI command message freezes motion on the display. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_FREEZE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpFreeze when this command completes.

MCI_WAIT

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

MCI_OVLY_RECT

Specifies that the rcfield of the data structure identified by lpFreezecontains a valid display rectangle. This is a required parameter.

LPMCI_OVLY_RECT_PARMS  lpFreeze

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	The video overlay device uses this command.

See Also	MCI_UNFREEZE, MM_MCINOTIFY


MCI_GETDEVCAPS

This MCI command message is used to return static information about a device. All devices respond to this message. The parameters and flags available for this message depend on the selected device. Information is returned in the dwReturn field of the data structure identified by lpCapsParms.

Parameters  	DWORD  dwFlags

The following standard and command specific flags apply to all devices:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpCapsParms when this command completes.

MCI_WAIT

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

MCI_GETDEVCAPS_ITEM

Indicates that the dwItem field of the data structure identified by lpCapsParmscontains a constant specifying the device capabilities in question. The following constants are defined:

MCI_GETDEVCAPS_CAN_EJECT returns MCI_TRUE if the device can eject the media; otherwise returns MCI_FALSE.

MCI_GETDEVCAPS_CAN_PLAY returns MCI_TRUE if the device can play the media; otherwise returns MCI_FALSE. If a device returns MCI_TRUE to this constant, it implies the device supports MCI_PAUSE and MCI_STOP as well as MCI_PLAY.

MCI_GETDEVCAPS_CAN_RECORD returns MCI_TRUE if the device supports recording; otherwise returns MCI_FALSE. If a device returns MCI_TRUE to this constant, it implies the device supports MCI_PAUSE and MCI_STOP as well as MCI_RECORD.

MCI_GETDEVCAPS_CAN_SAVE returns MCI_TRUE if the device can save a file; otherwise returns MCI_FALSE.

MCI_GETDEVCAPS_COMPOUND_DEVICE returns MCI_TRUE if the device uses device elements; otherwise returns MCI_FALSE.

MCI_GETDEVCAPS_DEVICE_TYPE returns MCI_DEVTYPE_ANIMATION,MCI_DEVTYPE_CD_AUDIO, MCI_DEVTYPE_DAT, MCI_DEVTYPE_DIGITAL_VIDEO,MCI_DEVTYPE_OTHER, MCI_DEVTYPE_OVERLAY, MCI_DEVTYPE_SCANNER,MCI_DEVTYPE_SEQUENCER, MCI_DEVTYPE_VIDEODISC, MCI_DEVTYPE_VIDEOTAPE,or MCI_DEVTYPE_WAVEFORM_AUDIO for the device type.

MCI_GETDEVCAPS_HAS_AUDIO returns MCI_TRUE if the device plays audio; otherwise returns MCI_FALSE.

MCI_GETDEVCAPS_HAS_VIDEO returns MCI_TRUE if the device plays video; otherwise returns MCI_FALSE. For example, devices which support the graphic or videodisc command set return MCI_TRUE.

MCI_GETDEVCAPS_USES_FILES returns MCI_TRUE if the device requires a filename as its element name; otherwise returns MCI_FALSE.

LPMCI_GETDEVCAPS_PARMS  lpCapsParms

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

Animation Extensions

DWORD  dwFlags

The following extensions apply to animation devices:

MCI_GETDEVCAPS_ITEM

Indicates that the dwItem field of the data structure identified by lpCapsParmscontains a constant specifying the device capabilities in question. The following additional constants are defined for animation devices:

MCI_ANIM_GETDEVCAPS_CAN_REVERSE returns MCI_TRUE if the movie player can play in reverse; otherwise returns MCI_FALSE.

MCI_ANIM_GETDEVCAPS_CAN_STRETCH returns MCI_TRUE if the device can stretch the image to fill the frame. Returns MCI_FALSE if it cannot. (MCIMMP returns MCI_FALSE.)

MCI_ANIM_GETDEVCAPS_FAST_RATE returns the standard fast play rate in frames per second. (MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.)

MCI_ANIM_GETDEVCAPS_MAX_WINDOWS returns the maximum number of windows that the device can handle simultaneously.

MCI_ANIM_GETDEVCAPS_NORMAL_RATE returns the normal rate of play in frames per second. (MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.)

MCI_ANIM_GETDEVCAPS_PALETTES returns MCI_TRUE if the device can return a palette handle. Returns MCI_FALSE if the device cannot return a palette handle. (MCIMMP returns MCI_TRUE.)

MCI_ANIM_GETDEVCAPS_SLOW_RATE returns the standard slow play rate in frames per second. (MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.)

LPMCI_GETDEVCAPS_PARMS  lpCapsParms

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

Videodisc Extensions

DWORD  dwFlags

The following extensions apply to videodisc devices:

MCI_GETDEVCAPS_ITEM

Indicates that the dwItem field of the data structure identified by lpCapsParmscontains a constant specifying the device capabilities in question. The following additional constants are defined for videodisc devices:

MCI_VD_GETDEVCAPS_CAN_REVERSE returns MCI_TRUE if the videodisc player can play in reverse; otherwise returns MCI_FALSE. (Some players can play CLV discs in reverse as well as CAV discs.)

MCI_VD_GETDEVCAPS_FAST_RATE returns the standard fast play rate in frames per second.

MCI_VD_GETDEVCAPS_NORMAL_RATE returns the normal rate of play in frames per second.

MCI_VD_GETDEVCAPS_SLOW_RATE returns the standard slow play rate in frames per second.

MCI_VD_GETDEVCAPS_CLV

Indicates the information requested applies to CLV format discs.

MCI_VD_GETDEVCAPS_CAV

Indicates the information requested applies to CAV format discs. This is the default.

LPMCI_GETDEVCAPS_PARMS  lpCapsParms

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

Video Overlay Extensions

DWORD  dwFlags

The following extensions apply to video overlay devices:

MCI_GETDEVCAPS_ITEM

Indicates that the dwItem field of the data structure identified by lpCapsParmscontains a constant specifying the device capabilities in question. The following additional constants are defined for animation devices:

MCI_OVLY_GETDEVCAPS_CAN_FREEZE returns MCI_TRUE if the device can freeze the image. Returns MCI_FALSE if it cannot.

MCI_OVLY_GETDEVCAPS_CAN_STRETCH returns MCI_TRUE if the device can stretch the image to fill the frame. Returns MCI_FALSE if it cannot.

MCI_OVLY_GETDEVCAPS_MAX_WINDOWS returns the maximum number of windows that the device can handle simultaneously. (MCIMMP returns 8.)

LPMCI_GETDEVCAPS_PARMS  lpCapsParms

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

Wave Audio Extensions

DWORD  dwFlags

The following extended flag applies to wave audio devices:

MCI_GETDEVCAPS_ITEM

Indicates that the dwItem field of the data structure identified by lpCapsParms contains a constant specifying the device capabilities in question. The following additional constants are defined for wave audio devices:

MCI_WAVE_GETDEVCAPS_INPUT returns the total number of waveform input (recording) devices.

MCI_WAVE_GETDEVCAPS_OUTPUT returns the total number of waveform output (playback) devices.

LPMCI_GETDEVCAPS_PARMS  lpCapsParms

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

See Also	MCI_INFO, MCI_STATUS, MCI_SYSINFO, MCI_WHERE, MM_MCINOTIFY


MCI_INFO

This MCI command message returns string information from a device. All devices respond to this message. The parameters and flags available for this message depend on the selected device. Information is returned in the lpstrReturnfield of the data structure identified by lpInfo. The dwReturnSize field specifies the buffer length for the return data.

Parameters  	DWORD  dwFlags

The following standard and command specific flags apply to all devices:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpInfo when this command completes.

MCI_WAIT

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

MCI_INFO_PRODUCT

Returns a description of the hardware associated with a device. Compound devices should return a description that identifies both the driver and the hardware used.

LPMCI_INFO_PARMS  lpInfo

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

Animation Extensions

DWORD  dwFlags

The following additional flags apply to wave audio devices:

MCI_INFO_FILE

Returns the filename of the current file. This flag is only supported by devices which return MCI_TRUE to the MCI_GETDEVCAPS_USES_FILES query.

MCI_ANIM_INFO_TEXT

Returns the caption of the window.

LPMCI_INFO_PARMS  lpInfo

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

Video Overlay Extensions

DWORD  dwFlags

The following additional flags apply to wave audio devices:

MCI_INFO_FILE

Returns the filename of the current file. This flag is only supported by devices which return MCI_TRUE to the MCI_GETDEVCAPS_USES_FILES query.

MCI_OVLY_INFO_TEXT

Returns the caption of the window associated with the overlay device.

LPMCI_INFO_PARMS  lpInfo

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

Wave Audio Extensions

DWORD  dwFlags

The following additional flags apply to wave audio devices:

MCI_INFO_FILE

Returns the filename of the current file. This flag is supported by devices which return MCI_TRUE to the MCI_GETDEVCAPS_USES_FILES query.

MCI_WAVE_INPUT

Returns the number of inputs.

MCI_WAVE_OUTPUT

Returns the number of outputs.

LPMCI_INFO_PARMS  lpInfo

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

See Also	MCI_GETDEVCAPS, MCI_STATUS, MCI_SYSINFO, MCI_WHERE, MM_MCINOTIFY


MCI_LOAD

This MCI command message loads a file. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_LOAD:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpLoadwhen this command completes.

MCI_WAIT

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

MCI_LOAD_FILE

Indicates the lpfilenamefield of the data structure identified by lpLoadcontains a pointer to a buffer containing the file name.

LPMCI_LOAD_PARMS  lpLoad

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command applies to video overlay devices.

See Also	MCI_SAVE, MM_MCINOTIFY


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.

Parameters  	DWORD  dwFlags

The following flags apply to all devices:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpOpenwhen this command completes.

MCI_WAIT

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

MCI_OPEN_ALIAS

Indicates 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 is shareable.

MCI_OPEN_TYPE

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

MCI_OPEN_TYPE_ID

Indicates the low-order word of the lpstrDeviceType field of the associated data structure specifies a standard MCI device type ID and the high-order word specifies the ordinal index for the device. Combine this flag with the MCI_OPEN_TYPE flag.

LPMCI_OPEN_PARMS  lpOpen

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  dwFlags

The following flags apply to compound devices:

MCI_OPEN_ELEMENT

For compound devices, indicates an element name is included in the lpstrElementfield of the data structure identified by lpOpen.

MCI_OPEN_ELEMENT_ID

For compound devices, specifies that the lpstrElementName field of the data structure identified by lpOpen is interpreted as a DWORD and has meaning internal to the device.

LPMCI_OPEN_PARMS  lpOpen

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  dwFlags

The following flags apply to animation devices:

MCI_ANIM_OPEN_NOSTATIC

Indicates that the animation should reduce the number of static (system) colors in the palette. With MCIMMP, the number of static colors is reduced to two.

MCI_ANIM_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParentfield of the data structure identified by lpOpen. 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 lpOpen. The dwStylevalue 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  lpOpen

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

Video Overlay Extensions

DWORD  dwFlags

The following flags apply to video overlay devices:

MCI_OVLY_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParentfield of the data structure identified by lpOpen.

MCI_OVLY_OPEN_WS

Indicates a window style is specified in the dwStyle field of the data structure identified by lpOpen. The dwStylevalue 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_OVLY_OPEN_PARMS  lpOpen

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

Wave Audio Extensions

DWORD  dwFlags

The following flags apply to wave audio devices:

MCI_WAVE_OPEN_BUFFER

Indicates a buffer size is specified in the dwBuffer field of the data structure identified by lpOpen.

LPMCI_WAVE_OPEN_PARMS  lpOpen

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_DEVICE_OPEN

Indicates that the device is already open and is not shareable.

MCIERR_CANNOT_LOAD_DRIVER

Indicates that the device could not be loaded.

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 MCIMMP, 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 lpstrDeviceName field, and set the MCI_OPEN_ELEMENT flag.

See Also	MCI_CLOSE, MM_MCINOTIFY


MCI_PASTE

This MCI command message pastes data into a device element.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_PASTE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpPaste when this command completes.

MCI_WAIT

Specifies that the device should complete the operation before MCI returns control to the application.

LPMCI_GENERIC_PARMS  lpPaste

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command is not used by the MCI device drivers supplied with the Multimedia Extensions 1.0.

See Also	MCI_CUT, MCI_COPY, MM_MCINOTIFY


MCI_PAUSE

This MCI command message pauses the current action.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_PAUSE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpDefault when this command completes.

MCI_WAIT

Specifies that the device should be paused before MCI returns control to the application.

LPMCI_GENERIC_PARMS  lpDefault

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	The difference between MCI_STOP and MCI_PAUSE depends upon the device. If possible, MCI_PAUSE suspends device operation but leaves the device ready to resume play immediately.

See Also	MCI_STOP, MM_MCINOTIFY


MCI_PLAY

This MCI command message signals the device to begin transmitting output data. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_PLAY:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpPlaywhen this command completes.

MCI_WAIT

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

MCI_FROM

Specifies that a beginning position is included in the dwFrom field of the data structure identified by lpPlay. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_TO

Specifies that an ending position is included in the dwTo field of the data structure identified by lpPlay. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

LPMCI_PLAY_PARMS  lpPlay

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

Animation Extensions

DWORD  dwFlags

The following additional flags apply to animation devices:

MCI_ANIM_PLAY_FAST

Specifies to play fast.

MCI_ANIM_PLAY_REVERSE

Specifies to play in reverse.

MCI_ANIM_PLAY_SCAN

Specifies to scan quickly. (MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.)

MCI_ANIM_PLAY_SLOW

Specifies to play slowly.

MCI_ANIM_PLAY_SPEED

Specifies that the play speed is included in the dwSpeed field in the data structure identified by lpPlay. (MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.)

LPMCI_ANIM_PLAY_PARMS  lpPlay

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

Videodisc Extensions

DWORD  dwFlags

The following additional flags apply to videodisc devices:

MCI_VD_PLAY_FAST

Specifies to play fast.

MCI_VD_PLAY_REVERSE

Specifies to play in reverse.

MCI_VD_PLAY_SCAN

Specifies to scan quickly.

MCI_VD_PLAY_SLOW

Specifies to play slowly.

MCI_VD_PLAY_SPEED

Specifies that the play speed is included in the dwSpeed field in the data structure identified by lpPlay.

LPMCI_VD_PLAY_PARMS  lpPlay

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

Return Value	Returns zero if successful. Otherwise, it returns error information.


MCI_PUT

This MCI command message sets the source, destination, and frame rectangles. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_PUT:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpDest when this command completes.

MCI_WAIT

Specifies that the palette should be realized before MCI returns control to the application.

DWORD  lpDest

Specifies a far pointer to a device specific data structure. For a description of this parameter, see the lpDest description included with the device extensions.

Animation Extensions

DWORD  dwFlags

The following flags additional flags apply to animation devices supporting MCI_PUT:

MCI_ANIM_RECT

Specifies that the rcfield of the data structure identified by lpDestcontains a valid display rectangle. This is a required parameter.

MCI_ANIM_PUT_DESTINATION

Indicates that the rc field of the data structure identified by lpDest contains a display rectangle specifying the offset and visible extent of the animation within the client area of the window. The destination rectangle specifies a clipping rectangle for frames relative to the window origin.

MCI_ANIM_PUT_SOURCE

Indicates that the rc field of the data structure identified by lpDest contains a display rectangle specifying the offset and size of a clipping rectangle for the animation image. The source rectangle specifies the display rectangle relative to the animation origin.

LPMCI_ANIM_RECT_PARMS  lpDest

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

Video Overlay Extensions

DWORD  dwFlags

The following flags additional flags apply to video overlay devices supporting MCI_PUT:

MCI_OVLY_RECT

Specifies that the rcfield of the data structure identified by lpDest contains a valid display rectangle. This is a required parameter.

MCI_OVLY_PUT_DESTINATION

Indicates that the rc field of the data structure identified by lpDest contains a display rectangle specifying the offset and visible extent of the animation within the client area of the window. The destination rectangle specifies a clipping rectangle for frames relative to the window origin.

MCI_OVLY_PUT_FRAME

Indicates that the rc field of the data structure identified by lpDest  contains a display rectangle specifying the offset and size of the video buffer to be updated by the analog video. The frame rectangle specifies the display rectangle for frames relative to the video buffer origin.

MCI_OVLY_PUT_SOURCE

Indicates that the rc field of the data structure identified by lpDest contains a display rectangle specifying the offset and size of the clipping rectangle of the image. The source rectangle specifies the display rectangle for relative to the window origin.

LPMCI_OVLY_RECT_PARMS  lpDest

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	MCIMMP does not stretch the animation since it does not support stretching.

See Also	MCI_WHERE, MM_MCINOTIFY


MCI_REALIZE

This MCI command message tells a graphic device to realize its palette into a device context. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_REALIZE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpRealize when this command completes.

MCI_WAIT

Specifies that the palette should be realized before MCI returns control to the application.

MCI_ANIM_PAL_BKGD

If this flag is set, the palette is realized as a background palette.

MCI_ANIM_PAL_NORM

If this flag is set, the palette is realized normally. This is the default action.

LPMCI_GENERIC_PARMS  lpRealize

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

Return Value	Returns zero if successful. Otherwise, it returns error information. (MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.)

Comments    	This command supported by devices that return true to the MCI_GETDEVCAPS_PALETTES query.


MCI_RECORD

This MCI command message starts recording from the current position or from the specified position until the specified position. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_RECORD:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpRecordwhen this command completes.

MCI_WAIT

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

MCI_RECORD_INSERT

Indicates that newly recorded information should be inserted or pasted into the existing data. (Some devices may not support this.) If supported, this is the default.

MCI_FROM

Indicates a beginning position is included in the dwFrom field of the data structure identified by lpRecord. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_RECORD_OVERWRITE

Indicates that data should overwrite existing data.

MCI_TO

Indicates an ending position is included in the dwTo field of the data structure identified by lpRecord. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

LPMCI_RECORD_PARMS  lpRecord

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

Return Value	Returns zero if successful. Otherwise, it returns error information. MCIWAVE returns MCIERR_UNSUPPORTED_FUNCTION for MCI_RECORD_OVERWRITE. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION for this command.

Comments    	This command supported by devices that return true to the MCI_GETDEVCAPS_CAN_RECORD query.

See Also	MCI_CUE, MCI_SEEK, MCI_PLAY, MM_MCINOTIFY


MCI_SAVE

This MCI command message saves the current file. Devices which modify files should not destroy the original copy until they receive the save message. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_SAVE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpSave when this command completes.

MCI_WAIT

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

MCI_SAVE_FILE

Indicates the lpfilenamefield of the data structure identified by lpSave contains a pointer to a buffer containing the destination file name.

LPMCI_SAVE_PARMS  lpSave

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

Return Value	Returns zero if successful. Otherwise, it returns error information. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION.

Comments    	This command supported by devices that return true to the MCI_GETDEVCAPS_CAN_SAVE query. MCIWAVE supports this command.

See Also	MCI_LOAD, MM_MCINOTIFY


MCI_SEEK

This MCI command message initiates a seek. Support of this message by a device is optional. The parameters  * and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_SEEK:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpSeekwhen this command completes.

MCI_WAIT

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

MCI_SEEK_END

Specifies to seek to the end of the media.

MCI_SEEK_START

Specifies to seek to the start of the media.

MCI_TO

Specifies a position is included in the dwTo field of the MCI_SEEK_PARMS data structure. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. Do not use this flag with MCI_SEEK_END or MCI_SEEK_START.

LPMCI_SEEK_PARMS  lpSeek

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

Videodisc Extensions

DWORD  dwFlags

The following additional flag applies to videodisc devices.

MCI_VD_SEEK_REVERSE

Specifies to seek backward.

LPMCI_SEEK_PARMS  lpSeek

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

See Also	MCI_CUE, MCI_PLAY, MCI_RECORD, MM_MCINOTIFY


MCI_SET

This MCI command message sets device information. Support of this message by a device is optional. The parameters  * and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_SET:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the data structure identified by lpSet when this command completes.

MCI_WAIT

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

MCI_SET_AUDIO

Specifies an audio channel number is included in the dwAudio field of the data structure identified by lpSet. The constants MCI_SET_AUDIO_ALL,MCI_SET_AUDIO_LEFT, and MCI_SET_AUDIO_RIGHT indicate the applicable channel. This flag must be used with MCI_SET_ON or MCI_SET_OFF. (MCICDA and MCISEQ return MCIERR_UNSUPPORTED_FUNCTION.)

MCI_SET_DOOR_CLOSED

Instructs the device to close the media cover (if any).

MCI_SET_DOOR_OPEN

Instructs the device to open the media cover (if any).

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat field of the data structure identified by lpSet. Specifying MCI_FORMAT_MILLISECONDS indicates that subsequent commands that specify time will use milliseconds for both input and output. Other units are device dependent.

MCI_SET_VIDEO

Sets the video signal on or off. This flag must be used with either MCI_SET_ON or MCI_SET_OFF. (MCIMMP and devices that do not have video return MCIERR_UNSUPPORTED_FUNCTION.)

MCI_SET_ON

Sets the specified audio channel or turns the video on.

MCI_SET_OFF

Sets the specified channel or turns the video off.

LPMCI_SET_PARMS  lpSet

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

Animation Extensions

DWORD  dwFlags

The following additional flags apply to animation devices:

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormatfield of the data structure identified by lpSet. The following constants are defined:

MCI_FORMAT_MILLISECONDS changes the time format to milliseconds. (MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION if the time format is set to MCI_FORMAT_MILLISECONDS.)

MCI_FORMAT_FRAMES changes the time format to frames.

LPMCI_ANIM_SET_PARMS  lpSet

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

CD Audio Extensions

DWORD  dwFlags

The following additional flags apply to videodisc devices:

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat field of the data structure identified by lpSet. The following constants are defined:

MCI_FORMAT_MILLISECONDS changes the time format to milliseconds.

MCI_FORMAT_MSF changes the time format to minutes, seconds, and frames.

MCI_FORMAT_TMSF changes the time format to tracks, minutes,seconds, and frames. MCI uses continuous track numbers.

LPMCI_SET_PARMS  lpSet

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

Sequencer Extensions

DWORD  dwFlags

The following additional flags apply to MIDI sequencer devices:

MCI_SEQ_SET_MASTER

Sets the sequencer as a source of synchronization data and indicates that the type of synchronization is specified in the dwMaster field of the data structure identified by lpSet. (MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION.) The following constants are defined:

MCI_SEQ_MIDI specifies that the sequencer will send MIDI format synchronization data.

MCI_SEQ_SMPTE specifies that the sequencer will send SMPTE format synchronization data.

MCI_SEQ_NONE specifies that the sequencer will not send synchronization data.

MCI_SEQ_SET_OFFSET

Changes the SMPTE offset of a sequence to that specified by the dwOffset field of the data structure identified by lpSet. This only affects sequences with a SMPTE division type.

MCI_SEQ_SET_PORT

Sets the output MIDI port of a sequence to that specified by the MIDI device ID in the dwPort field of the data structure identified by lpSet. The device will close the previous port (if any), and attempt to open and use the new port. If it fails, it will return an error and re-open the previously used port (if any). The following constants are defined:

MCI_SEQ_MAPPER sets the port opened to the MIDI Mapper.

MCI_SEQ_NONE closes the previously used port (if any). The sequencer will behave exactly the same as if a port were open,except no MIDI message will be sent.

MCI_SEQ_SET_SLAVE

Sets the sequencer to receive synchronization data and indicates that the type of synchronization is specified in the dwSlave field of the data structure identified by lpSet. (MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION.)The following constants are defined:

MCI_SEQ_FILE sets the sequencer to receive synchronization data contained in the MIDI file.

MCI_SEQ_SMPTE sets the sequencer to receive SMPTE synchronization data.

MCI_SEQ_MIDI sets the sequencer to receive MIDI synchronization data.

MCI_SEQ_NONE sets the sequencer to ignore synchronization data in a MIDI stream.

MCI_SEQ_SET_TEMPO

Changes the tempo of the MIDI sequence to that specified by the dwTempofield of the structure pointed to by lpSet. For sequences with division type PPQN, tempo is specified in beats per minute;for sequences with division type SMPTE, tempo is specified in frames per second.

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormatfield of the data structure identified by lpSet. The following constants are defined:

MCI_FORMAT_MILLISECONDS changes the time format to milliseconds for both input and output.

MCI_FORMAT_SMPTE_24 sets the time format to 24 frame SMPTE.

MCI_FORMAT_SMPTE_25 sets the time format to 25 frame SMPTE.

MCI_FORMAT_SMPTE_30 sets the time format to 30 frame SMPTE.

MCI_FORMAT_SMPTE_30DROP sets the time format to 30 drop-frame SMPTE.

MCI_SEQ_FORMAT_SONGPTR sets the time format to song-pointer units.

LPMCI_SEQ_SET_PARMS  lpSet

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

Videodisc Extensions

DWORD  dwFlags

The following additional flags apply to videodisc devices:

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat field of the data structure identified by lpSet. The following constants are defined:

MCI_FORMAT_CHAPTERS changes the time format to chapters.

MCI_FORMAT_FRAMES changes the time format to frames.

MCI_FORMAT_HMS changes the time format to hours, minutes, and seconds.

MCI_FORMAT_MILLISECONDS changes the time format to milliseconds for both input and output.

MCI_VD_FORMAT_TRACK changes the time format to tracks. MCI uses continuous track numbers.

LPMCI_VD_SET_PARMS  lpSet

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

Wave Audio Extensions

DWORD  dwFlags

The following additional flags apply to waveform audio devices:

MCI_WAVE_INPUT

Sets the input used for recording to the wInput field of the data structure identified by lpSet.

MCI_WAVE_OUTPUT

Sets the output used for playing to the wOutput field of the data structure identified by lpSet.

MCI_WAVE_SET_ANYINPUT

Specifies that any wave input compatible with the current format can be used for recording if the current input is in use or incompatible with the current format.

MCI_WAVE_SET_ANYOUTPUT

Specifies that any wave output compatible with the current format can be used for playing if the current output is in use or incompatible with the current format.

MCI_WAVE_SET_AVGBYTESPERSEC

Sets the bytes per second used for playing, recording, and saving to the nAvgBytesPerSec field of the data structure identified by lpSet. For additional information, see the RIFF WAVE section of Chapter 8, "File Formats."

MCI_WAVE_SET_BITSPERSAMPLE

Sets the bits per sample used for playing, recording, and saving to the nBitsPerSample field of the data structure identified by lpSet. For additional information, see the RIFF WAVE format section of Chapter 8, "File Formats."

MCI_WAVE_SET_BLOCKALIGN

Sets the block alignment used for playing, recording, and saving to the nBlockAlign field of the data structure identified by lpSet. For additional information,see the RIFF WAVE format section of Chapter 8, "File Formats."

MCI_WAVE_SET_CHANNELS

Specifies the number of channels is indicated in the nChannels field of the data structure identified by lpSet.

MCI_WAVE_SET_FORMATTAG

Sets the format type used for playing, recording, and saving to the wFormatTag field of the data structure identified by lpSet. Specifying WAVE_FORMAT_PCM changes the format to PCM. For additional information, see the RIFF WAVE format section of Chapter 8, "File Formats."

MCI_WAVE_SET_SAMPLESPERSEC

Sets the samples per second used for playing, recording, and saving to the nSamplesPerSec field of the data structure identified by lpSet. For additional information,see the RIFF WAVE section of Chapter 8, "File Formats."

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat field of the data structure identified by lpSet. The following constants are defined:

MCI_FORMAT_BYTES changes the time format to bytes for input or output.

MCI_FORMAT_MILLISECONDS changes the time format to milliseconds for input or output.

MCI_FORMAT_SAMPLE changes the time format to samples for input or output.

LPMCI_WAVE_SET_PARMS  lpSet

Specifies a far pointer to the MCI_WAVE_SET_PARMS data structure. This parameter replaces the standard default parameter data structure identified by lpDefault. (Devices with additional parameters might replace this data structure with a device-specific data structure.)

Return Value	Returns zero if successful. Otherwise, it returns error information.


MCI_SOUND

This MCI command message plays system sounds identified in the [sounds] section of the WIN.INI file. MCI supports this message directly rather than passing it to the device. The name of the sound is specified in the buffer pointed to by the lpstrSoundName field of the data structure identified by lpInfo.

Parameters  	DWORD  dwFlags

The following standard and command specific flags apply to all devices:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpInfo when this command completes.

MCI_WAIT

Specifies that the playing of the sound should finish before MCI returns control to the application.

MCI_SOUND_NAME

Indicates that the name of a sound to play is included in the lpstrSoundNameof the data structure identified by lpSound.

LPMCI_SOUND_PARMS  lpInfo

Specifies a far pointer to the MCI_SOUND_PARMS data structure.

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command will only play files that fit into available memory. Use the MCI wave audio device to play longer waveform files.


MCI_SPIN

This MCI command message starts the device spinning up or down. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_SPIN:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpDefault when this command completes.

MCI_WAIT

Specifies that the spin up or spin down operation should finish before MCI returns control to the application.

MCI_VD_SPIN_UP

Starts the disc spinning.

MCI_VD_SPIN_DOWN

Stops the disc from spinning.

LPMCI_GENERIC_PARMS  lpDefault

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command applies to videodisc devices.


MCI_STATUS

This MCI command message is used to obtain information about an MCI device. All devices respond to this message. The parameters and flags available for this message depend on the selected device. Note that status information is returned in the dwReturn field of the data structure identified by lpStatus.

Parameters  	DWORD  dwFlags

The following standard and command specific flags apply to all devices:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallbackfield of the lpStatus structure when this command completes.

MCI_WAIT

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

MCI_STATUS_ITEM

Indicates that the dwItem field of the data structure identified by lpStatus contains a constant specifying the status item in question. The following constants are defined:

MCI_STATUS_CURRENT_TRACK returns the current track number. MCI uses continuous track numbers.

MCI_STATUS_LENGTH returns the total media length.

MCI_STATUS_MODE returns the current mode of the device. All devices can return MCI_MODE_NOT_READY, MCI_MODE_PAUSE,MCI_MODE_PLAY, and MCI_MODE_STOP. The modes MCI_MODE_OPEN,MCI_MODE_RECORD, and MCI_MODE_SEEK are device dependant.

MCI_STATUS_NUMBER_OF_TRACKS returns the total number of playable tracks.

MCI_STATUS_POSITION returns the current position.

MCI_STATUS_READY returns MCI_TRUE if the device is ready;otherwise, returns MCI_FALSE.

MCI_STATUS_TIME_FORMAT returns the current time format of the device. The time formats include:MCI_FORMAT_BYTES, MCI_FORMAT_FRAMES, MCI_FORMAT_HMS,MCI_FORMAT_MILLISECONDS, MCI_FORMAT_MSF, MCI_FORMAT_SAMPLES,and MCI_FORMAT_TMSF.

MCI_STATUS_START

Indicates that the start of the media should be returned. To get the start value, combine this flag with MCI_STATUS_ITEM and set the dwItemfield of the data structure identified by lpStatusto MCI_STATUS_POSITION.

MCI_TRACK

Indicates a status track parameter is included in the dwTrack field of the data structure identified by lpStatus. This flag must be used with MCI_STATUS_POSITION or MCI_STATUS_LENGTH. When used with MCI_STATUS_POSITION, returns the starting position of the specified track. When used with MCI_STATUS_LENGTH, returns the length of the specified track. MCI uses continuous track numbers.

LPMCI_STATUS_PARMS  lpStatus

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

Animation Extensions

DWORD  dwFlags

The following extensions apply to animation devices:

MCI_STATUS_ITEM

Indicates that the dwItemfield of the data structure identified by lpStatus contains a constant specifying the status item in question. The following constants are defined:

MCI_ANIM_STATUS_FORWARD returns MCI_TRUE if playing forward; MCI_FALSE otherwise.

MCI_ANIM_STATUS_HPAL returns the handle of the movie palette.

MCI_ANIM_STATUS_HWND returns the handle of the playback window.

MCI_ANIM_STATUS_SPEED returns the animation speed.

MCI_STATUS_MEDIA_PRESENT returns MCI_TRUE if the device has no actual media; otherwise returns MCI_FALSE.

LPMCI_STATUS_PARMS  lpStatus

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

CD Audio Extensions

DWORD  dwFlags

The following extensions applies to CD audio devices:

MCI_STATUS_ITEM

Indicates that the dwItemfield of the data structure identified by lpStatuscontains a constant specifying the status item in question. The following constants are defined:

MCI_STATUS_MEDIA_PRESENT returns MCI_TRUE if the device has no actual media; otherwise returns MCI_FALSE.

LPMCI_STATUS_PARMS  lpStatus

Specifies a far pointer to the MCI_STATUS_PARMS data structure. This parameter replaces the standard default parameter data structure. (Devices with additional parameters might replace this data structure with a device-specific data structure.)

Sequencer Extensions

DWORD  dwFlags

The following extensions apply to sequencers:

MCI_STATUS_ITEM

Indicates that the dwItemfield of the data structure identified by lpStatus contains a constant specifying the status item in question. The following constants are defined:

MCI_SEQ_STATUS_DIVTYPE returns one of the following values as the current division type of a sequence: MCI_SEQ_DIV_PPQN,MCI_SEQ_DIV_SMPTE_24, MCI_SEQ_DIV_SMPTE_25, MCI_SEQ_DIV_SMPTE_30,or MCI_SEQ_DIV_SMPTE_30DROP.

MCI_SEQ_STATUS_MASTER returns the synchronization type used for master operation.

MCI_SEQ_STATUS_OFFSET returns the current SMPTE offset of a sequence.

MCI_SEQ_STATUS_PORT returns the MIDI device ID for the current port used by the sequence.

MCI_SEQ_STATUS_SLAVE returns the synchronization type used for slave operation.

MCI_SEQ_STATUS_TEMPO returns the current tempo of a MIDI sequence in beats-per-minute for PPQN files, or frames-per-second for SMPTE files.

MCI_STATUS_MEDIA_PRESENT returns MCI_TRUE if the device has no actual media; otherwise returns MCI_FALSE.

LPMCI_STATUS_PARMS  lpStatus

Specifies a far pointer to the MCI_STATUS_PARMS data structure. This parameter replaces the standard default parameter data structure. (Devices with additional parameters might replace this data structure with a device-specific data structure.)

Videodisc Extensions

DWORD  dwFlags

The following additional flags apply to videodisc devices:

MCI_STATUS_ITEM

Indicates that the dwItemfield of the data structure identified by lpStatuscontains a constant specifying the status item in question. The following constants are defined:

MCI_STATUS_MEDIA_PRESENT returns MCI_TRUE if the device has no actual media; otherwise returns MCI_FALSE.

MCI_VD_STATUS_DISC_SIZE returns the size of the loaded disc in inches (8 or 12).

MCI_VD_STATUS_FORWARD returns MCI_TRUE if playing forward;MCI_FALSE otherwise.

MCI_VD_STATUS_MEDIA_TYPE returns MCI_VD_MEDIA_CAV, MCI_VD_MEDIA_CLV,or MCI_VD_MEDIA_OTHER.

MCI_STATUS_MODE returns the current mode of the device. All devices can return MCI_MODE_NOT_READY, MCI_MODE_PAUSE,MCI_MODE_PLAY, and MCI_MODE_STOP. Video disc devices can also return MCI_VD_SCAN, MCI_VD_OPEN, MCI_VD_PARK.

MCI_VD_STATUS_SIDE returns 1 or 2 to indicate which side of the disc is loaded.

MCI_VD_STATUS_SPEED returns the play speed in frames per second. (MCIPIONR returns MCIERR_UNSUPPORTED_FUNCTION.)

LPMCI_STATUS_PARMS  lpStatus

Specifies a far pointer to the MCI_STATUS_PARMS data structure. This parameter replaces the standard default parameter data structure. (Devices with additional parameters might replace this data structure with a device-specific data structure.)

Wave Audio Extensions

DWORD  dwFlags

The following additional flags apply to wave audio devices:

MCI_STATUS_ITEM

Indicates that the dwItemfield of the data structure identified by data structure identified by lpStatuscontains a constant specifying the status item in question. The following constants are defined:

MCI_STATUS_MEDIA_PRESENT returns MCI_TRUE if the device has no actual media; otherwise returns MCI_FALSE.

MCI_WAVE_INPUT returns the wave input device used for recording. If no device is in use and no device has been explicitly set, then the error return is MCI_WAVE_INPUTUNSPECIFIED.

MCI_WAVE_OUTPUT returns the wave output device used for playing. If no device is in use and no device has been explicitly set, then the error return is MCI_WAVE_OUTPUTUNSPECIFIED.

MCI_WAVE_STATUS_AVGBYTESPERSEC returns the current bytes per second used for playing, recording, and saving.

MCI_WAVE_STATUS_BITSPERSAMPLE returns the current bits per sample used for playing, recording, and saving.

MCI_WAVE_STATUS_BLOCKALIGN returns the current block alignment used for playing, recording, and saving.

MCI_WAVE_STATUS_CHANNELS returns the current channel count used for playing, recording, and saving.

MCI_WAVE_FORMATTAG returns the current format tag used for playing, recording, and saving.

MCI_WAVE_STATUS_LEVEL returns the current record or playback level. The value is returned as an 8- or 16-bit value, depending on the sample size used. The right or mono channel level is returned in the low-order word. The left channel level is returned in the high-order word.

MCI_WAVE_STATUS_SAMPLESPERSEC returns the current samples per second used for playing, recording, and saving.

LPMCI_STATUS_PARMS  lpStatus

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

Video Overlay Extensions

DWORD  dwFlags

The following additional flags apply to video overlay devices:

MCI_OVLY_STATUS_HWND

Returns the handle of the window associated with the video overlay device.

MCI_STATUS_MEDIA_PRESENT returns MCI_TRUE if the device has no actual media; otherwise returns MCI_FALSE.

LPMCI_STATUS_PARMS  lpStatus

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

See Also	MCI_GETDEVCAPS, MCI_STATUS, MCI_SYSINFO, MCI_WHERE, MM_MCINOTIFY


EÀ
Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	The difference between MCI_STOP and MCI_PAUSE depends upon the device. If possible, MCI_PAUSE suspends device operation but leaves the device ready to resume play immediately.

See Also	MCI_PAUSE, MM_MCINOTIFY


MCI_SYSINFO

This MCI command message returns information about MCI devices. MCI supports this message directly rather than passing it to the devices. Note that string information is returned in the application supplied buffer indicated by in the lpstrReturn field of the data structure identified by lpSysInfo. The dwReturnSize field specifies the buffer length.

Parameters  	DWORD  dwFlags

The following standard and command-specific flags apply to all devices:

MCI_SYSINFO_INSTALLNAME

Specifies that MCI will return the name used in the SYSTEM.INI file to install the device.

MCI_SYSINFO_NAME

Specifies a number parameter is included in the dwNumberField of the data structure identified by lpSysInfo. The number corresponds to the device that MCI will return the name of a device.

MCI_SYSINFO_OPEN

Specifies that the number or name of open devices will be returned.

LPMCI_SYSINFO_PARMS  lpSysInfo

Specifies a far pointer to the MCI_SYSINFO_PARMS structure.

MCI_SYSINFO_QUANTITY

Specifies that MCI will return the number of devices of the specified type that are listed in the [mci] section of the SYSTEM.INI file. If the MCI_SYSINFO_OPEN flag is set then the number of open devices will be returned.

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	The wDeviceType element of the lpSysInfo structure is used to indicate the device type of the query. If the wDeviceID parameter is set to MCI_ALL_DEVICE_ID it will override the value of wDeviceType. Any other value in wDeviceID is ignored.

All integer return values are DWORDS returned in the buffer addressed by the lpstrReturn field of MCI_SYSINFO_PARMS. The string return value produced by the MCI_SYSINFO_NAME flag is also returned in the location address by the lpstrReturn field. Information returned in the buffer is returned as a null-terminated string.

See Also	MCI_GETDEVCAPS, MCI_INFO, MCI_STATUS, MCI_WHERE, MM_MCINOTIFY


MCI_UNFREEZE

This MCI command message restores motion to an area of the display frozen with MCI_FREEZE. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_UNFREEZE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpFreeze when this command completes.

MCI_WAIT

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

MCI_OVLY_RECT

Specifies that the rcfield of the data structure identified by lpFreeze contains a valid display rectangle. This is a required parameter.

LPMCI_OVLY_RECT_PARMS  lpFreeze

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command applies to video overlay devices.

See Also	MCI_FREEZE, MM_MCINOTIFY


MCI_UPDATE

This MCI command message updates the display rectangle. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_UPDATE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpDest when this command completes.

MCI_WAIT

Specifies that the palette should be realized before MCI returns control to the application.

DWORD  lpDest

Specifies a far pointer to a device specific  . For a description of this parameter, see the lpDest description included with the device extensions.

Animation Extensions

DWORD  dwFlags

The following flags additional flags apply to animation devices supporting MCI_UPDATE:

MCI_ANIM_RECT

Specifies that the rcfield of the data structure identified by lpDestcontains a valid display rectangle. If this flag is not specified, the entire window is updated.

MCI_ANIM_UPDATE_HDC

Specifies that the hDC field of the data structure identified by lpDest contains a handle to the display context. This flag is required.

LPMCI_ANIM_UPDATE_PARMS  lpDest

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

Video Overlay Extensions

DWORD  dwFlags

The following flags additional flags apply to video overlay devices supporting MCI_UPDATE:

MCI_OVLY_RECT

Specifies that the rcfield of the  structure identified by lpDest contains a valid display rectangle. If this flag is not specified,the entire window is updated.

MCI_OVLY_UPDATE_HDC

Specifies that the hDC field of the data structure identified by lpDest contains a handle to the display context.

LPMCI_OVLY_UPDATE_PARMS  lpDest

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

See Also	MCI_PUT, MCI_WHERE, MM_MCINOTIFY


MCI_WHERE

This MCI command message returns the extent of a clipping rectangle. The top and left fields of the returned rectangle are always zero. The right and bottom fields of the returned rectangle give the width and height of the image displayed. The parameters and flags for this message vary according to the selected device. Note that a pointer to the rectangle is returned in the rc field of the data structure identified by lpQuery.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_WHERE:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the data structure identified by lpQuery when this command completes.

MCI_WAIT

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

DWORD  lpQuery

Specifies a far pointer to a device specific data structure. For a description of this parameter, see the lpQuery description included with the device extensions.

Animation Extensions

DWORD  dwFlags

The following flags additional flags apply to animation devices supporting MCI_WHERE:

MCI_ANIM_WHERE_DESTINATION

Indicates that the destination display rectangle should be placed in the rc field of the data structure identified by lpQuery.

MCI_ANIM_WHERE_SOURCE

Indicates that the animation source rectangle should be placed in the rc field of the data structure identified by lpQuery.

LPMCI_ANIM_RECT_PARMS  lpQuery

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

Video Overlay Extensions

DWORD  dwFlags

The following flags additional flags apply to video overlay devices supporting MCI_WHERE:

MCI_OVLY_WHERE_DESTINATION

Indicates that the destination display rectangle should be placed in the rc field of the data structure identified by lpQuery.

MCI_OVLY_WHERE_FRAME

Indicates that the overlay frame rectangle should be placed in the rc field of the data structure identified by lpQuery.

MCI_OVLY_WHERE_SOURCE

Indicates that the animation source rectangle should be placed in the rc field of the data structure identified by lpQuery.

LPMCI_OVLY_RECT_PARMS  lpQuery

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command applies to animation and video overlay devices.

See Also	MCI_GETDEVCAPS, MCI_INFO, MCI_PUT, MCI_STATUS, MCI_SYSINFO, MM_MCINOTIFY


MCI_WINDOW

This MCI command message specifies the window and the window characteristics a graphic device should use for display. By default, graphic devices should create a window when a device is opened but should not display it until they receive the play command. The window command tells a graphic device to use a specified window to display frames instead of the default window created by the device. Applications which supply window handles should be prepared to update an invalid rectangle on the window.

Several flags are provided to allow users to manipulate the window. Since the status command can be used to obtain the current window handle, you might use the standard window functions instead. The flags are provided to allow applications which use the string interface to perform standard operations.

Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameters  	DWORD  dwFlags

The following flags apply to all devices supporting MCI_WINDOW:

MCI_NOTIFY

Specifies that MCI should post a notification message to the window specified in the dwCallback field of the MCI_ANIM_WINDOW_PARMSdata structure when this command completes.

MCI_WAIT

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

DWORD  lpRealize

Specifies a far pointer to a device specific data structure. For a description of this parameter, see the lpRealize description included with the device extensions.

Animation Extensions

DWORD  dwFlags

The following flags additional flags apply to animation devices supporting MCI_WINDOW:

MCI_ANIM_WINDOW_HWND

Indicates the handle of the window to use for the destination is included in the hWndfield of the data structure identified by lpRealize. Set this to MCI_ANIM_WINDOW_DEFAULT to return to the default window.

MCI_ANIM_WINDOW_STATE

Indicates the nCmdShow field of the MCI_ANIM_WINDOW_PARMSdata structure contains parameters for setting the window state. This flag is equivalent to calling ShowWindow with the state parameter. The constants are the same as the ones in WINDOWS.H (such as SW_HIDE, SW_MINIMIZE, SW_SHOW,SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, SW_SHOWMINNOACTIVE, SW_SHOWNA,SW_SHOWNOACTIVATE, or SW_SHOWNORMAL.)

MCI_ANIM_WINDOW_TEXT

Indicates the lpstrText field of the MCI_ANIM_WINDOW_PARMSdata structure contains a pointer to a buffer containing the caption used for the window.

LPMCI_ANIM_WINDOW_PARMS  lpRealize

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

Video Overlay Extensions

DWORD  dwFlags

The following flags additional flags apply to video overlay devices supporting MCI_WINDOW:

MCI_OVLY_WINDOW_HWND

Indicates the handle of the window used for the destination is included in the hWnd field of the MCI_OVLY_WINDOW_PARMSdata structure. Set this to MCI_OVLY_WINDOW_DEFAULT to return to the default window.

MCI_OVLY_WINDOW_STATE

Indicates the nCmdShow field of the lpRealizedata structure contains parameters for setting the window state. This flag It is equivalent to calling showwindowwith the state parameter. The constants are the same as the ones in WINDOWS.H (such as SW_HIDE, SW_MINIMIZE, SW_SHOW,SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, SW_SHOWMINNOACTIVE, SW_SHOWNA,SW_SHOWNOACTIVATE, or SW_SHOWNORMAL.)

MCI_OVLY_WINDOW_TEXT

Indicates the lpstrTextfield of the MCI_OVLY_WINDOWS_PARMS data structure contains a pointer to buffer containing the caption used for the window.

LPMCI_OVLY_WINDOW_PARMS  lpRealize

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

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command applies to animation, and video overlay devices.


MIM_CLOSE

This message is sent to a low-level callback function when a MIDI input device is closed.  The device handle is no longer valid once this message has been sent.

Parameters  	DWORD  dwParam1

Currently unused.

DWORD  dwParam2

Currently unused.

Return Value	None

See Also	MM_MIM_CLOSE


MIM_DATA

This message is sent to a low-level callback function when a MIDI message is received by a MIDI input device.

Parameters  	DWORD  dwParam1

Specifies the MIDI message that was received.  The message is packed into a DWORD with the first byte of the message in the low-order byte.

DWORD  dwParam2

Specifies the time that the message was received by the input device driver.  The timestamp is specified in milliseconds,beginning at 0 when midiInStart was called.

Return Value	None

Comments    	The received message is raw; running status is not expanded. Therefore, messages may not include a MIDI status byte.

This message is not sent when a MIDI system-exclusive message is received.

See Also	MM_MIM_DATA, MIM_LONGDATA


MIM_ERROR

This message is sent to a low-level callback function when an invalid MIDI message is received.

Parameters  	DWORD  dwParam1

Specifies the invalid MIDI message that was received.  The message is packed into a DWORD with the first byte of the message in the low-order byte.

DWORD  dwParam2

Specifies the time that the message was received by the input device driver.  The timestamp is specified in milliseconds,beginning at 0 when midiInStart was called.

Return Value	None

See Also	MM_MIM_ERROR


MIM_LONGDATA

This message is sent to a low-level callback function when an input buffer has been filled with MIDI system-exclusive data and is being returned to the application.

Parameters  	DWORD  dwParam1

Specifies a far pointer to a MIDIHDR structure identifying the input buffer.

DWORD  dwParam2

Specifies the time that the data was received by the input device driver.  The timestamp is specified in milliseconds,beginning at 0 when midiInStart was called.

Return Value	None

Comments    	The returned buffer may not be full.  Use the dwBytesRecordedfield of the MIDIHDR structure specified by dwParam1 to determine the number of bytes recorded into the returned buffer.

See Also	MIM_DATA, MM_MIM_LONGDATA


MIM_LONGERROR

This message is sent to a low-level callback function when an invalid MIDI system-exclusive message is received.

Parameters  	DWORD  dwParam1

Specifies a pointer to a MIDIHDR structure identifying the buffer containing the invalid message.

DWORD  dwParam2

Specifies the time that the data was received by the input device driver.  The timestamp is specified in milliseconds,beginning at 0 when midiInStart was called.

Return Value	None

See Also	MM_MIM_LONGERROR


MIM_OPEN

This message is sent to a low-level callback function when a MIDI input device is opened.

Parameters  	DWORD  dwParam1

Currently unused.

DWORD  dwParam2

Currently unused.

Return Value	None

See Also	MM_MIM_OPEN


MM_JOY1BUTTONDOWN

This message is passed to the window function that has captured joystick 1 when a button is pressed.

Parameters  	WORD  wParam

Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

DWORD  lParam

The low word contains the current X position of the joystick. The high word contains the current Y position.


MM_JOY1BUTTONUP

This message is passed to the window function that has captured joystick 1 when a button is released.

Parameters  	WORD  wParam

Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

DWORD  lParam

The low word contains the current X position of the joystick. The high word contains the current Y position.


MM_JOY1MOVE

This message is passed to the window function that has captured joystick 1 when the joystick position changes.

Parameters  	WORD  wParam

Indicates which joystick buttons are pressed. It can be any combination of the following values:

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

DWORD  lParam

The low word contains the current X position of the joystick. The high word contains the current Y position.


MM_JOY1ZMOVE

This message is passed to the window function that has captured joystick 1 when the z-axis position changes.

Parameters  	WORD  wParam

Indicates which joystick buttons are pressed. It can be any combination of the following values:

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

DWORD  lParam

The low word contains the current Z position of the joystick.


MM_JOY2BUTTONDOWN

This message is passed to the window function that has captured joystick 2 when a button is pressed.

Parameters  	WORD  wParam

Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

DWORD  lParam

The low word contains the current X position of the joystick. The high word contains the current Y position.


MM_JOY2BUTTONUP

This message is passed to the window function that has captured joystick 2 when a button is released.

Parameters  	WORD  wParam

Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

DWORD  lParam

The low word contains the current X position of the joystick. The high word contains the current Y position.


MM_JOY2MOVE

This message is passed to the window function that has captured joystick 2 when the joystick position changes.

Parameters  	WORD  wParam

Indicates which joystick buttons are pressed. It can be any combination of the following values:

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

DWORD  lParam

The low word contains the current X position of the joystick. The high word contains the current Y position.


MM_JOY2ZMOVE

This message is passed to the window function that has captured joystick 2 when the z-axis position changes.

Parameters  	WORD  wParam

Indicates which joystick buttons are pressed. It can be any combination of the following values:

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

DWORD  lParam

The low word contains the current Z position of the joystick.


MM_MCINOTIFY

This MCI command message is sent by a device to notify a window function when the device completes an action. Devices will send this message only when the MCI_NOTIFY flag is sent with an MCI command.

Parameters  	WORD  wParam

Contains one of the following messages:

MCI_NOTIFY_ABORTED

Specifies that the device received a command that prevented the conditions initiating the callback from being met.

MCI_NOTIFY_SUCCESSFUL

Specifies that the conditions initiating the callback have been met.

MCI_NOTIFY_SUPERSEDED

Specifies that the device received another command with the MCI_NOTIFY flag and the current conditions for initiating the callback have been superseded.

MCI_NOTIFY_FAILURE

Specifies that a device error occurred while the device was executing the command.

LONG  lParam

The low-order word specifies the ID of the device initiating the callback.

Return Value	Returns zero if successful. Otherwise, it returns error information.

Comments    	This command applies to videodisc devices.


MM_MIM_CLOSE

This message is sent to a window when a MIDI input device is closed.  The device handle is no longer valid once this message has been sent.

Parameters  	WORD  wParam

Specifies a handle to the MIDI input device that was closed.

LONG  lParam

Currently unused.

Return Value	None

See Also	MIM_CLOSE


MM_MIM_DATA
&
 €
€
€
MM_MIM_OPEN

This message is sent to a window when a MIDI input device is opened.

Parameters  	WORD  wParam

Specifies the handle to the MIDI input device that was opened.

LONG  lParam

Currently unused.

Return Value	None

See Also	MIM_OPEN


MM_MOM_CLOSE

This message is sent to a window when a MIDI output device is closed.  The device handle is no longer valid once this message has been sent.

Parameters  	WORD  wParam

Specifies the handle to the MIDI output device.

LONG  lParam

Currently unused.

Return Value	None

See Also	MOM_CLOSE


MM_MOM_DONE

This message is sent to a window when the specified system-exclusive buffer has been played and is being returned to the application.

Parameters  	WORD  wParam

Specifies a handle to the MIDI output device that played the buffer.

LONG  lParam

Specifies a far pointer to a MIDIHDR structure identifying the buffer.

Return Value	None

See Also	MOM_DONE


MM_MOM_OPEN

This message is sent to a window when a MIDI output device is opened.

Parameters  	WORD  wParam

Specifies the handle to the MIDI output device.

LONG  lParam

Currently unused.

Return Value	None

See Also	MOM_OPEN


MM_WIM_CLOSE

This message is sent to a window when a waveform input device is closed.  The device handle is no longer valid once this message has been sent.

Parameters  	WORD  wParam

Specifies a handle to the waveform input device that was closed.

LONG  lParam

Currently unused.

Return Value	None

See Also	WIM_CLOSE


MM_WIM_DATA

This message is sent to a window when waveform data is present in the input buffer and the buffer is being returned to the application.  The message can be sent either when the buffer is full, or after the waveInReset function is called.

Parameters  	WORD  wParam

Specifies a handle to the waveform input device that received the waveform data.

LONG  lParam

Specifies a far pointer to a WAVEHDR structure identifying the buffer containing the waveform data.

Return Value	None

Comments    	The returned buffer may not be full.  Use the dwBytesRecordedfield of the WAVEHDR structure specified by lParam to determine the number of bytes recorded into the returned buffer.

See Also	WIM_DATA


MM_WIM_OPEN

This message is sent to a window when a waveform input device is opened.

Parameters  	WORD  wParam

Specifies a handle to the waveform input device that was opened.

LONG  lParam

Currently unused.

Return Value	None

See Also	WIM_OPEN


MM_WOM_CLOSE

This message is sent to a window when a waveform output device is closed.  The device handle is no longer valid once this message has been sent.

Parameters  	WORD  wParam

Specifies a handle to the waveform output device that was closed.

LONG  lParam

Currently unused.

Return Value	None

See Also	WOM_CLOSE


MM_WOM_DONE

This message is sent to a window when the specified output buffer is being returned to the application.  Buffers are returned to the application when they have been played, or as the result of a call to waveOutReset.

Parameters  	WORD  wParam

Specifies a handle to the waveform output device that played the buffer.

LONG  lParam

Specifies a far pointer to a WAVEHDR structure identifying the buffer.

Return Value	None

See Also	WOM_DONE


MM_WOM_OPEN

This message is sent to a window when a waveform output device is opened.

Parameters  	WORD  wParam

Specifies a handle to the waveform output device that was opened.

LONG  lParam

Currently unused.

Return Value	None

See Also	WOM_OPEN


MMIOM_CLOSE

This message is sent to an I/O procedure by mmioClose to request that a file be closed.

Parameters  	LONG  lParam1

Specifies options contained in the wFlags parameter of mmioClose.

LONG  lParam2

Is not used.

Return Value	The return value is zero if the file is successfully closed. Otherwise, the return value specifies an error code.

See Also	mmioClose, MMIOM_OPEN


MMIOM_OPEN

This message is sent to an I/O procedure by mmioOpento request that a file be opened or deleted.

Parameters  	LONG  lParam1

Specifies a null-terminated string containing the name of the file to open.

LONG  lParam2

Is not used.

Return Value	The return value is zero if the operation is successful. Otherwise, the return value specifies an error value. Possible error returns are:

MMIOM_CANNOTOPEN

Specified file could not be opened.

MMIOM_OUTOFMEMORY

Not enough memory to perform operation.

Comments    	The dwFlags field of the MMIOINFO structure contains option flags passed to the mmioOpen function.

The lDiskOffset field of the MMIOINFOstructure is initialized to zero. If this value is incorrect, then the I/O procedure must correct it.

If the caller passed a MMIOINFO structure to mmioOpen,the return value will be returned in the wErrorRetfield.

See Also	mmioOpen, MMIOM_CLOSE


MMIOM_READ

This message is sent to an I/O procedure by mmioReadto request that a specified number of bytes be read from an open file.

Parameters  	LONG  lParam1

Specifies a huge pointer to the buffer to be filled with data read from the file.

LONG  lParam2

Specifies the number of bytes to read from the file.

Return Value	The return value is the number of bytes actually read from the file. If no more bytes can be read, the return value is zero. If there is an error, the return value is -1.

Comments    	The I/O procedure is responsible for updating the lDiskOffset field of the MMIOINFO structure to reflect the new file position after the read operation.

See Also	mmioRead, MMIOM_WRITE, MMIOM_WRITEFLUSH


MMIOM_SEEK

This message is sent to an I/O procedure by mmioSeekto request that the current file position be moved.

Parameters  	LONG  lParam1

Specifies the new file position according to the option flag specified in lParam2.

LONG  lParam2

Specifies how the file position is changed. Only one of the following flags can be specified:

SEEK_SET

Move the file position to be lParam1 bytes from the beginning of the file.

SEEK_CUR

Move the file position to be lParam1 bytes from the current position.  lParam1 may be positive or negative.

SEEK_END

Move the file position to be lParam1 bytes from the end of the file.

Return Value	The return value is the new file position. If there is an error, the return value is -1.

Comments    	The I/O procedure is responsible for maintaining the current file position in the lDiskOffset field of the MMIOINFO structure.

See Also	mmioSeek


MMIOM_WRITE

This message is sent to an I/O procedure by mmioWrite to request that data be written to an open file.

Parameters  	LONG  lParam1

Specifies a huge pointer to a buffer containing the data to write to the file.

LONG  lParam2

Specifies the number of bytes to write to the file.

Return Value	The return value is the number of bytes actually written to the file. If there is an error, the return value is -1.

Comments    	The I/O procedure is responsible for updating the lDiskOffset field of the MMIOINFO structure to reflect the new file position after the write operation.

See Also	mmioWrite, MMIOM_READ, MMIOM_WRITEFLUSH


MMIOM_WRITEFLUSH

This message is sent to an I/O procedure by mmioWrite to request that data be written to an open file,and then, if possible, that a hardware flush command be sent.

Parameters  	LONG  lParam1

Specifies a huge pointer to a buffer containing the data to write to the file.

LONG  lParam2

Specifies the number of bytes to write to the file.

Return Value	The return value is the number of bytes actually written to the file. If there is an error, the return value is -1.

Comments    	The I/O procedure is responsible for updating the lDiskOffset field of the MMIOINFO structure to reflect the new file position after the write operation.

Note that this message is equivalent to the MMIOM_WRITEmessage except that it additionally requests that the I/O procedure flush its internal buffers, if any.  Unless an I/O procedure performs internal buffering, this message can be handled exactly like the MMIOM_WRITEmessage.

See Also	mmioWrite, mmioFlush, MMIOM_READ, MMIOM_WRITE


MMP_PROCESS_FRAME

This message is passed to a Movie Player frame-hook callback function after the Movie Player completes screen updates for the specified frame or subframe.

Parameters  	WORD  wParam

Specifies the frame index.

LONG  lParam

Specifies the subframe index.

Return Value	Not used.

See Also	mmpSetFrameHook, mmpGetFrameHook, MMP_PROCESS_SCRIPT


MMP_PROCESS_SCRIPT

This message is passed to a Movie Player frame-hook callback function before the Movie Player processes the text in the movie script channel.

Z
¨¬!�ã~€
€
ƒ€

€
‚ÿ
Paramete
Specifies the requested minimum resolution value.

LONG  lParam2

Not used (NULL).

Return Value	Not used.

Comments    	Application programmers are told to match timeBeginPeriod calls with equivalent timeEndPeriod calls, so your driver can assume that TDD_BEGINMINPERIOD messages will be matched with equivalent TDD_ENDMINPERIOD messages.

See Also	TDD_ENDMINPERIOD


TDD_GETDEVCAPS

This message is sent to request the capabilities of the timer device.

Parameters  	DWORD  dwParam1

Specifies a far pointer to a TIMECAPSdata structure.  The driver fills this structure with the capabilities of the timer device.

DWORD  dwParam2

Size in bytes of the data structure pointed to by dwParam1.

Return Value	The return value is zero if successful.  Otherwise, it specifies a non-zero error code.

Comments    	The driver should only write dwParam2 or less bytes to the location pointed to by dwParam1.  If dwParam2 is zero, nothing should be written and MMSYSERR_NOERROR should be returned.


TDD_GETSYSTEMTIME

This message is sent to obtain the system time in milliseconds.

Parameters  	LONG  lParam1

Not used (NULL).

LONG  lParam2

Not used (NULL).

Return Value	Return a DWORD value containing the number of milliseconds elapsed since Windows was started.

Comments    	Your driver should return a value that is accurate to approximately one millisecond.


TDD_KILLTIMEREVENT

This message is sent to cancel a pending timer event.

Parameters  	WORD  wID

Specifies the ID of the timer event to cancel.

LONG  lParam1

Not used (set to NULL).

LONG  lParam2

Not used (set to NULL).

Return Value	Return TRUE if the timer event destroyed. Return FALSE if the specified event was not registered.

Comments    	In response to this message, your driver should cancel the periodic or one-time timer event. This is the only way to discontinue a periodic timer event.

See Also	TDD_SETTIMEREVENT


TDD_SETTIMEREVENT

This message is sent to create a one-time or periodic timer-interrupt event.

Parameters  	LONG  lParam1

Specifies a far pointer to a TIMEREVENT structure containing the parameters for the timer event.

LONG  lParam2

Not used (set to NULL).

Return Value	Return a WORD-sized timer ID code that an application can use to identify the event. Return NULL if the parameters for the requested event are invalid.

Comments    	In response to this message, your driver should place a periodic or one-time interrupt timer event in the system timer event queue. The driver should call the specified callback function after the requested delay period. All time values listed in the TIMEREVENT structure are given in milliseconds.

See Also	TDD_KILLTIMEREVENT


WIM_CLOSE

This message is sent to a low-level callback function when a  waveform input device is closed.  The device handle is no longer valid once this message has been sent.

Parameters  	DWORD  dwParam1

Currently unused.

DWORD  dwParam2

Currently unused.

Return Value	None

See Also	MM_WIM_CLOSE


WIM_DATA

This message is sent to a low-level callback function when waveform data is present in the input buffer and the buffer is being returned to the application.  The message can be sent either when the buffer is full, or after the waveInReset function is called.

Parameters  	DWORD  dwParam1

Specifies a far pointer to a WAVEHDR structure identifying the buffer containing the waveform data.

DWORD  dwParam2

Currently unused.

Return Value	None

Comments    	The returned buffer may not be full.  Use the dwBytesRecordedfield of the WAVEHDR structure specified by dwParam1 to determine the number of bytes recorded into the returned buffer.

See Also	MM_WIM_DATA


WIM_OPEN

This message is sent to a low-level callback function when a waveform input device is opened.

Parameters  	DWORD  dwParam1

Currently unused.

DWORD  dwParam2

Currently unused.

Return Value	None

See Also	MM_WIM_OPEN


WM_SYSCOMMAND

This message is sent when the user selects a command from the System menu, when the user selects the minimize or maximize box, or when the screen saver is preparing to blank the screen.

Parameters  	WORD  wParam

Specifies the type of system command. Windows defines a series of system-command types. The Multimedia extensions add the following system-command type:

SC_SCREENSAVE

Screen saver will be invoked. Return a nonzero value to prevent the screen saver from being invoked; otherwise,pass the message on to DefWindowProc.

DWORD  lParam

Not used with the SC_SCREENSAVE command.

Comments    	Refer to the Windows SDK documentation for a description of the other WM_SYSCOMMAND command types.


WOM_CLOSE

This message is sent to a low-level callback function when a waveform output device is closed.  The device handle is no longer valid once this message has been sent.

Parameters  	DWORD  dwParam1

Currently unused.

DWORD  dwParam2

Currently unused.

Return Value	None

See Also	MM_WOM_CLOSE


WOM_DONE

This message is sent to a low-level callback function when the specified output buffer is being returned to the application.  Buffers are returned to the application when they have been played, or as the result of a call to waveOutReset.

Parameters  	DWORD  dwParam1

Specifies a far pointer to a WAVEHDR structure identifying the buffer.

DWORD  dwParam2

Currently unused.

Return Value	None

See Also	MM_WOM_DONE


WOM_OPEN

This message is sent to a low-level callback function when a waveform output device is opened.

Parameters  	DWORD  dwParam1

Currently unused.

DWORD  dwParam2

Currently unused.

Return Value	None

See Also	MM_WOM_OPEN


auxGetDevCaps

Syntax      	WORD auxGetDevCaps(wDeviceID, lpCaps, wSize)

This function queries a specified auxiliary output device to determine its capabilities.

Parameters  	WORD  wDeviceID

Identifies the auxiliary output device to be queried.

LPAUXCAPS  lpCaps

Specifies a far pointer to an AUXCAPS structure.  This structure is filled with information about the capabilities of the device.

WORD  wSize

Specifies the size of the AUXCAPS structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device id is out of range.

Comments    	Use auxGetNumDevs to determine the number of auxiliary output devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.

See Also	auxGetNumDevs


auxGetNumDevs

Syntax      	WORD auxGetNumDevs()

This function retrieves the number of auxiliary output devices present in the system.

Return Value	Returns the number of auxiliary output devices present in the system.

See Also	auxGetDevCaps


auxGetVolume

Syntax      	WORD auxGetVolume(wDeviceID, lpdwVolume)

This function returns the current volume setting of an auxiliary output device.

Parameters  	WORD  wDeviceID

Identifies the auxiliary output device to be queried.

LPDWORD  lpdwVolume

Specifies a far pointer to a location that will be filled with the current volume setting.  The high-order word of this location contains the left channel volume setting and the low-order word contains the right channel setting.  A value of 0xFFFF represents full volume and a value of 0x0000 is silence.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device id is out of range.

Comments    	Use auxGetNumDevs to determine the number of auxiliary output devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.

Use the AUXCAPS_VOLUME flag to test the dwSupport field of the AUXCAPS structure filled by auxGetDevCaps to see if the device supports volume control.  Use the AUXCAPS_LRVOLUME flag to test to see if the device supports volume control on both the left and right channels.  If a device does not support both left and right volume control, only the right channel value is valid.

See Also	auxSetVolume


auxSetVolume

Syntax      	WORD auxSetVolume(wDeviceID, dwVolume)

This function sets the volume in an auxiliary output device.

Parameters  	WORD  wDeviceID

Identifies the auxiliary output device to be queried.  Device IDs are determined implicitly from the number of devices present in the system.  Device ID values range from zero to one less than the number of devices present.  Use auxGetNumDevsto determine the number of auxiliary devices in the system.

DWORD  dwVolume

Specifies the new volume setting.  The high-order word of dwVolume specifies the left channel volume setting and the low-order word specifies the right channel setting.  A value of 0xFFFF represents full volume and a value of 0x0000 is silence.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device id is out of range.

Comments    	Use auxGetNumDevs to determine the number of auxiliary output devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.

Use the AUXCAPS_VOLUME flag to test the dwSupport field of the AUXCAPS structure filled by auxGetDevCaps to see if the device supports volume control.  Use the AUXCAPS_LRVOLUME flag to test to see if the device supports volume control on both the left and right channels.  If a device does not support both left and right volume control, only the right channel value is used.

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also	auxGetVolume


DefScreenSaverProc

Syntax      	LONG DefScreenSaverProc(hWnd, msg, wParam, lParam)

This function performs the default actions for the screen savers.

Parameters  	HWND  hWnd

Specifies a handle to the screen saver window.

unsigned  msg

Specifies the message being passed to the window.

WORD  wParam

Specifies a word being passed to the window.

LONG  lParam

Specifies a long integer being passed to the window.

Return Value	The return value is a value specifying if Windows has taken the default action for the message.

Comments    	You should use this function rather than DefWindowProc in your ScreenSaverProc function of a screen saver to process messages that ScreenSaverProc does not trap. This function passes any messages that do not affect screen saver operation to DefWindowProc. The following list describes how DefScreenSaverProc interprets the messages that affect screen saver operation:

WM_ACTIVATE,WM_ACTIVATE_APP:If wParam is FALSE, the window is losing its focus and the screen saver shell terminates.

WM_LBUTTTONDOWN, WM_RBUTTONDOWN, WM_MBUTTONDOWN:The screen saver shell changes the mouse coordinates. The screen saver shell terminates in response to the resulting WM_MOUSEMOVE message.

WM_KEYDOWN, WM_SYSKEYDOWN:The screen saver shell terminates on this message.

WM_MOUSEMOVE:The shell determines if the mouse has moved, or if it is just being placed on the window again. If the mouse has moved, the screen saver shell terminates.

WM_DESTROY:When the window gets closed, the program should terminate, and the screen saver shell terminates when it receives this message.

If any special action is required for these messages, then your screen saver should process these messages and not call DefScreenSaverProc for that message.

See Also	ScreenSaverProc


joyGetDevCaps

Syntax      	WORD joyGetDevCaps(wId, lpCaps, wSize)

This function queries a joystick device to determine its capabilities.

Parameters  	WORD  wId

Identifies the device to be queried. This value is either JOYSTICKID1 or JOYSTICKID2.

LPJOYCAPS  lpCaps

Specifies a far pointer to a JOYCAPSdata structure.  This structure is filled with information about the capabilities of the joystick device.

WORD  wSize

Specifies the size of the JOYCAPS structure.

Return Value	Returns zero if successful.  Otherwise, returns an error number.

Comments    	Use joyGetNumDevs to determine the number of joystick devices supported by the driver.

See Also	joyGetNumDevs


joyGetNumDevs

Syntax      	WORD joyGetNumDevs()

This function returns the number of joystick devices supported by the joystick driver.

Return Value	Returns the number of joystick devices supported by the joystick driver.  If no driver is present, the function returns zero.

Comments    	Use joyGetPos to determine whether a given joystick is actually attached to the system. This function returns a JOYERR_UNPLUGGED error code if the specified joystick is not connected.

See Also	joyGetDevCaps, joyGetPos


joyGetPos

Syntax      	WORD joyGetPos(wId, lpInfo)

This function queries for the position and button activity of a joystick device.

Parameters  	WORD  wId

Identifies the joystick device to be queried. This value is either JOYSTICKID1 or JOYSTICKID2.

LPJOYINFO  lpInfo

Specifies a far pointer to a JOYINFOdata structure.  This structure is filled with information about the position and button activity of the joystick device.

Return Value	Returns zero if successful.  Otherwise, returns an error number.


joyGetThreshold

Syntax      	WORD joyGetThreshold(wId, lpwThreshold)

This function queries for the current movement threshold of a joystick device.

Parameters  	WORD  wId

Identifies the joystick device to be queried. This value is either JOYSTICKID1 or JOYSTICKID2.

LPWORD  lpwThreshold

Specifies a far pointer to a WORD variable that is filled with the movement threshold value.

Return Value	Returns zero if successful.  Otherwise, returns an error number.

Comments    	The movement threshold is the number of pixels that the joystick must be moved before a WM_JOYMOVE message is sent to the window that has captured the device.  The threshold is initially zero.

See Also	joySetThreshold


joyReleaseCapture

Syntax      	WORD joyReleaseCapture(wId)

This function releases the capture set by joySetCapture on the specified joystick device.

Parameters  	WORD  wId

Identifies the joystick device to be released. This value is either JOYSTICKID1 or JOYSTICK2.

Return Value	Returns zero if successful.  Otherwise, returns an error number.

See Also	joySetCapture


joySetCapture

Syntax      	WORD joySetCapture(hWnd, wId, wPeriod, bChanged)

This function directs the joystick driver to send joystick messages to the window procedure function for the specified window.

Parameters  	HWND  hWnd

Specifies a handle to the window to which messages are to be sent.

WORD  wId

Identifies the joystick device to be captured. This value is either JOYSTICKID1 or JOYSTICKID2.

WORD  wPeriod

Specifies the polling rate, in milliseconds.

BOOL  bChanged

If this parameter is set to TRUE, then messages are sent only when the position changes by a value greater than the joystick movement threshold.

Return Value	Returns zero if successful.  Otherwise, returns an error number.

Comments    	This function will fail if the specified joystick device is currently captured.  You must call the joyReleaseCapture function when the joystick capture is no longer needed.  If the window is destroyed,the joystick will be automatically released.

See Also	joyReleaseCapture, joySetThreshold, joyGetThreshold


joySetThreshold

Syntax      	WORD joySetThreshold(wId, wThreshold)

This function sets the movement threshold of a joystick device.

Parameters  	WORD  wId

Identifies the joystick device.  This value is either JOYSTICKID1 or JOYSTICKID2.

WORD  wThreshold

Specifies the new movement threshold.

Return Value	Returns zero if successful.  Otherwise, returns an error number.

Comments    	The movement threshold is the distance the joystick must be moved before a WM_JOYMOVE message is sent to a window that has captured the device.

See Also	joyGetThreshold, joySetCapture


MCI_HMS_HOUR

Syntax      	BYTE MCI_HMS_HOUR(dwHMS)

This macro returns the hours value from a time value given in HMS format.

Parameters  	DWORD  dwHMS

Specifies the time in HMS format.

Return Value	The return value is the hours value of the given time.

Comments    	Time in HMS format is expressed as a DWORD with the least significant byte containing hours, the next least significant byte containing minutes, and the next least significant byte containing seconds. The most significant byte is unused.

See Also	MCI_HMS_MINUTE, MCI_HMS_SECOND, MCI_MAKE_HMS


MCI_HMS_MINUTE

Syntax      	BYTE MCI_HMS_MINUTE(dwHMS)

'
 €œ
€
œ¬!�€
‚ÿ
This macro returns the minutes value from a time valu


MCI_MAKE_TMSF

Syntax      	DWORD MCI_MAKE_TMSF(tracks, minutes, seconds, frames)

This macro returns a time value in TMSF format from the given tracks, minutes, seconds, and frames values.

Parameters  	BYTE  tracks

Specifies the number of tracks.

BYTE  minutes

Specifies the number of minutes.

BYTE  seconds

Specifies the number of seconds.

BYTE  frames

Specifies the number of frames.

Return Value	The return value is the time in TMSF format.

Comments    	Time in TMSF format is expressed as a DWORD with the least significant byte containing tracks, the next least significant byte containing minutes, the next least significant byte containing seconds, and the most significant byte containing frames.

See Also	MCI_TMSF_MINUTE, MCI_TMSF_SECOND, MCI_TMSF_FRAME


MCI_MSF_FRAME

Syntax      	BYTE MCI_MSF_FRAME(dwMSF)

This macro returns the frames value from a time value given in MSF format.

Parameters  	DWORD  dwMSF

Specifies the time in MSF format.

Return Value	The return value is the frames value of the given time.

Comments    	Time in MSF format is expressed as a DWORD with the least significant byte containing minutes, the next least significant byte containing seconds, and the next least significant byte containing frames. The most significant byte is unused.

See Also	MCI_MSF_MINUTE, MCI_MSF_SECOND, MCI_MAKE_MSF


MCI_MSF_MINUTE

Syntax      	BYTE MCI_MSF_MINUTE(dwMSF)

This macro returns the minutes value from a time value given in MSF format.

Parameters  	DWORD  dwMSF

Specifies the time in MSF format.

Return Value	The return value is the minutes value of the given time.

Comments    	Time in MSF format is expressed as a DWORD with the least significant byte containing minutes, the next least significant byte containing seconds, and the next least significant byte containing frames. The most significant byte is unused.

See Also	MCI_MSF_SECOND, MCI_MSF_FRAME, MCI_MAKE_MSF


MCI_MSF_SECOND

Syntax      	BYTE MCI_MSF_SECOND(dwMSF)

This macro returns the seconds value from a time value given in MSF format.

Parameters  	DWORD  dwMSF

Specifies the time in MSF format.

ƒã{-%Ž‰ã:Pm‰ãseÓ4‰‚‚ÿ
Return Value
The return value is the seconds value of the given time.
Comments
Time in MSF format is expressed as a DWORD with the least significant byte containing minutes, the next least significant byte containing seconds, and the next least significant byte containing frames. The most significant byte is unused.
See Also
MCI_MSF_MINUTE
,
MCI_MSF_FR
Return Value	The return value is the tracks value of the given time.

Comments    	Time in TMSF format is expressed as a DWORD with the least significant byte containing tracks, the next least significant byte containing minutes, the next least significant byte containing seconds, and the most significant byte containing frames.

See Also	MCI_TMSF_MINUTE, MCI_TMSF_SECOND, MCI_TMSF_FRAME, MCI_MAKE_TMSF


mciExecute

Syntax      	BOOL mciExecute(lpstrCommand)

This function is a simplified version of the mciSendString function.  It does not take a buffer for return information, and displays a dialog box when errors occur.

Parameters  	LPSTR  lpstrCommand

Points to an MCI command string of the form:[command] [device] [parameters].

Return Value	TRUE if successful, FALSE if unsuccessful.

Comments    	This function provides a simple interface to MCI from scripting languages.  For debugging, set the "mciexecute" entry in the [mmdebug] section of WIN.INI to 1 and detailed error information will be displayed in a dialog box.  If "mmcmd" is set to 0, only user-correctable error information will be displayed.

See Also	mciSendString


mciGetDeviceID

Syntax      	WORD FAR PASCAL mciGetDeviceID(lpstrName)

This function retrieves the device ID corresponding to the name of an opened device.

Parameters  	LPSTR  lpstrName

Points to the device name from SYSTEM.INI.

Return Value	Returns the device ID assigned when it was opened and used in the mciSendCommand function.  Returns zero if the device name was not known,if the device was not open, or if there was not enough memory to complete the operation.  Each compound device element has a unique device ID. The ID of the "all" device is MCI_ALL_DEVICE_ID

See Also	MCI_OPEN


mciGetErrorString

Syntax      	WORD mciGetErrorString(dwError, lpstrBuffer, wLength)

This function returns a textual description of the specified MCI error.

Parameters  	DWORD  dwError

Specifies the error code returned by mciSendCommand or mciSendString.

LPSTR  lpstrBuffer

Specifies a pointer to a buffer that is filled with a textual description of the specified error.

WORD  wLength

Specifies the length of the buffer pointed to by lpstrBuffer.

Return Value	Returns TRUE if successful.  Otherwise, the given error code was not known.


mciSendCommand

Syntax      	DWORD mciSendCommand(wDeviceID, wMessage, dwParam1, dwParam2)

This function sends a command message to the specified media device.

Parameters  	WORD  wDeviceID

Specifies a device ID for the media device that the command is being sent to.  This parameter is not used with the MCI_OPEN command.

WORD  wMessage

Specifies the command message.

DWORD  dwParam1

Specifies flags for the command.

DWORD  dwParam2

Specifies a pointer to a parameter block for the command.

Return Value	Returns zero if the function was successful.  Otherwise, it returns error information.  To get a textual description of the error,pass the returned DWORD to mciGetErrorString.  To check the error code yourself, test only the low-order WORD of the returned DWORD value.

Comments    	Use the MCI_OPEN command to obtain the device ID specified by wDeviceID.

See Also	mciGetErrorString, mciSendString


mciSendString

Syntax      	DWORD mciSendString(lpstrCommand, lpstrReturnString, wReturnLength, hCallback)

This function sends a command string to an MCI device.  The device that the command is sent to is specified in the command string.

Parameters  	LPSTR  lpstrCommand

Points to an MCI command string of the form:[command] [device] [parameters].

LPSTR  lpstrReturnString

Specifies a buffer for return information.  May be NULL if no return information is desired.

WORD  wReturnLength

Specifies the size of the return buffer specified by lpstrReturnString.

HANDLE  hCallback

Specifies a handle to a window to call back if "notify" was specified in the command string.

Return Value	Returns zero if the function was successful.  Otherwise, it returns error information.  To get a textual description of the error,pass the returned DWORD to mciGetErrorString.  To check the error code yourself, test only the low-order WORD of the returned DWORD value.

See Also	mciExecute, mciGetErrorString, mciSendCommand


mciSetYieldProc

Syntax      	WORD FAR mciSetYieldProc(wDeviceID, fpYieldProc, dwYieldData)

This function sets the address of a procedure to be called periodically when an MCI device is waiting for a command to complete because the WAIT parameter was specified.

Parameters  	WORD  wDeviceID

Specifies the device ID to assign a procedure to.

YIELDPROC  fpYieldProc

Specifies the procedure to call when yielding for the given device.  Set to NULL to disable any existing yield proc.

DWORD  dwYieldData

Specifies the data sent to the yield procedure when it is called for the given device.

Return Value	Returns TRUE if successful. Returns FALSE for an invalid device ID.

Comments    	This call overides any previous yield procedure for this device.


MessageBeep

Syntax      	void MessageBeep(wAlert)

This function plays a waveform sound corresponding to a given system alert level.  The sound for each alert level is identified by an entry in the [sounds]section of WIN.INI.

Parameters  	WORD  wAlert

If wAlert is 0, MessageBeep plays the default sound identified by the "SystemDefault" entry in the [sounds] section of WIN.INI. If wAlert is -1, it uses the computer speaker to produce a standard beep sound. Otherwise, wAlert specifies the alert level using one of the following flags:

MB_ICONASTERISK

Plays the sound identified by the "SystemAsterisk" entry in the [sounds] section of WIN.INI.

MB_ICONEXCLAMATION

Plays the sound identified by the "SystemExclamation" entry in the [sounds] section of WIN.INI.

MB_ICONHAND

Plays the sound identified by the "SystemHand" entry in the [sounds] section of WIN.INI.

MB_ICONQUESTION

Plays the sound identified by the "SystemQuestion" entry in the [sounds] section of WIN.INI.

Return Value	None

Comments    	MessageBeep returns control to the caller after queuing the sound and plays the sound asynchronously.

If the specified alert sound can't be played, MessageBeep tries to play the system default sound. If the system default sound can't be played, it produces a standard beep sound using the computer speaker.

See Also	sndPlaySound


midiInAddBuffer

Syntax      	WORD midiInAddBuffer(hMidiIn, lpMidiInHdr, wSize)

This function sends an input buffer to a specified opened MIDI input device.  When the buffer is filled,it is sent back to the application.  Input buffers are used only for system exclusive messages.

Parameters  	HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device which receives the buffer.

LPMIDIHDR  lpMidiInHdr

Specifies a far pointer to a MIDIHDRstructure that identifies the buffer.

WORD  wSize

Specifies the size of the MIDIHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MIDIERR_UNPREPARED

lpMidiInHdr hasn't been prepared.

Comments    	The data buffer must be prepared with midiInPrepareHeader before it is passed to midiInAddBuffer.  The MIDIHDR data structure and the data buffer pointed to by its lpData field must be allocated with GlobalAlloc using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with GlobalLock.

See Also	midiInPrepareHeader


midiInClose

Syntax      	WORD midiInClose(hMidiIn)

This function closes the specified MIDI input device.

Parameters  	HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device to be closed.  If the function is successful, the handle is no longer valid after this call.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MIDIERR_STILLPLAYING

There are still buffers in the queue.

Comments    	If there are input buffers that have been sent with midiInAddBuffer and haven't been returned to the application,the close operation will fail.  Call midiInReset to mark all pending buffers as being done.

See Also	midiInOpen, midiInReset


midiInGetDevCaps

Syntax      	WORD midiInGetDevCaps(wDeviceID, lpCaps, wSize)

This function queries a specified MIDI input device to determine its capabilities.

Parameters  	WORD  wDeviceID

Identifies the input device to be queried.

LPMIDIINCAPS  lpCaps

Specifies a far pointer to a MIDIINCAPSdata structure.  This structure is filled with information about the capabilities of the device.

WORD  wSize

Specifies the size of the MIDIINCAPS structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device ID is out of range.

Comments    	Use midiInGetNumDevs to determine the number of MIDI input devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.  Only wSize bytes (or less) of information will be copied to the location pointed to by lpCaps.  If wSize is 0, nothing will be copied and MMSYSERR_NOERROR is returned.

See Also	midiInGetNumDevs


midiInGetErrorText

Syntax      	WORD midiInGetErrorText(wError, lpText, wSize)

This function retrieves a textual description of the error identified by the specified error number.

Parameters  	WORD  wError

Specifies the error number.

LPSTR  lpText

Specifies a far pointer to the buffer which is filled with the textual error description.

WORD  wSize

Specifies the length of buffer pointed to by lpText.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADERRNUM

Specified error number is out of range.

Comments    	If the textual error description is longer than the specified buffer,the description is truncated.  The returned error string is always null-terminated. If wSize is 0, nothing is copied and MMSYSERR_NOERROR is returned.  All error descriptions are less than 80 characters long.


midiInGetNumDevs

Syntax      	WORD midiInGetNumDevs()

This function retrieves the number of MIDI input devices in the system.

Return Value	Returns the number of MIDI input devices present in the system.

See Also	midiInGetDevCaps


midiInOpen

Syntax      	WORD midiInOpen(lphMidiIn, wDeviceID, dwCallback, dwCallbackInstance, dwFlags)

This function opens a specified MIDI input device.

Parameters  	LPHMIDIIN  lphMidiIn

Specifies a far pointer to an HMIDIIN handle. This location is filled with a handle identifying the opened MIDI input device.  Use the handle to identify the device when calling other MIDI input functions.

WORD  wDeviceID

Identifies the MIDI input device that is to be opened.

DWORD  dwCallback

Specifies the address of a callback function or a handle to a window that is called with information about incoming MIDI messages.

DWORD  dwCallbackInstance

Specifies 32 bits of user instance data that is passed to the callback function.  This parameter is not used with window callbacks.

DWORD  dwFlags

Specifies a callback flag for opening the device.

CALLBACK_WINDOW

If this flag is specified, dwCallback is assumed to be a window handle.

CALLBACK_FUNCTION

If this flag is specified, dwCallback is assumed to be a callback procedure address.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device ID is out of range.

MMSYSERR_ALLOCATED

Specified resource is already allocated.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

Comments    	Use midiInGetNumDevs to determine the number of MIDI input devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.

If a window is chosen to receive callback information, the following messages are sent to the window procedure function to indicate the progress of MIDI input:  MM_MIM_OPEN, MM_MIM_CLOSE,MM_MIM_DATA, MM_MIM_LONGDATA, MM_MIM_ERROR,MM_MIM_LONGERROR.

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of MIDI input:  MIM_OPEN, MIM_CLOSE, MIM_DATA, MIM_LONGDATA,MIM_ERROR, MIM_LONGERROR.  The callback function must reside in a DLL.  You do not have to use MakeProcInstance to get a procedure-instance address for the callback function.

Callback	void FAR PASCAL MidiInFunc(hMidiIn, wMsg, dwInstance, dwParam1, dwParam2)

MidiInFunc is a placeholder for the application-supplied function name.  The actual name must be exported by including it in an EXPORTS statement in the DLL's module definition file.

Parameters

HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device.

WORD  wMsg

Identifies the message.

DWORD  dwInstance

Specifies the 32 bits of instance data specified with midiInOpen.

DWORD  dwParam1

Specifies a parameter for the message.

DWORD  dwParam2

Specifies a parameter for the message.

Comments

Because the callback is accessed at interrupt time, it must reside in a DLL and its code segment must be specified as FIXED in the module-definition file for the DLL.  Any data that the callback accesses must be in a FIXED data segment as well.  The callback may not make any system calls except for PostMessage, timeGetSystemTime,timeGetTime, midiOutShortMsg, midiOutLongMsg, and OutputDebugStr.

See Also	midiInClose


midiInPrepareHeader

Syntax      	WORD midiInPrepareHeader(hMidiIn, lpMidiInHdr, wSize)

This function prepares a buffer for MIDI input.

Parameters  	HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device to receive data from.

LPMIDIHDR  lpMidiInHdr

Specifies a pointer to a MIDIHDRstructure that identifies the buffer to be prepared.

WORD  wSize

Specifies the size of the MIDIHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

Comments    	The MIDIHDR data structure and the data block pointed to by its lpData field must be allocated with GlobalAlloc using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with GlobalLock. Preparing a header that has already been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	midiInUnprepareHeader


midiInReset

Syntax      	WORD midiInReset(hMidiIn)

This function terminates MIDI input on the specified MIDI input device and marks all pending input buffers as done.

Parameters  	HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

See Also	midiInStart, midiInStop, midiInAddBuffer, midiInClose


midiInStart

Syntax      	WORD midiInStart(hMidiIn)

This function initiates MIDI input on the specified MIDI input device.

Parameters  	HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	This function resets timestamps to 0; the timestamp values for received messages are relative to the time this function was called.

All messages other than system exclusive messages are sent directly to the client when received.  System exclusive messages are placed in the buffer;  if there are no buffers in the queue,the data is thrown away without notification to the client and input will continue.  Buffers are returned to the client either when full, when a complete system exclusive message has been received,or when midiInReset is called (the dwBytesRecorded field in the header will contain the actual length of data).  Calling this function when input is already started will have no effect and MMSYSERR_NOERROR will be returned.

See Also	midiInStop, midiInReset


midiInStop

Syntax      	WORD midiInStop(hMidiIn)

This function terminates MIDI input on the specified MIDI input device.

Parameters  	HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	Current status (running status, parsing state, etc.) is maintained. If there are any system exclusive message buffers in the queue,the current buffer will be marked as done (the dwBytesRecorded field in the header will contain the actual length of data), but any empty buffers in the queue will remain there.  Calling this function when input is not started will have no effect and MMSYSERR_NOERROR will be returned.

See Also	midiInStart, midiInReset


midiInUnprepareHeader

Syntax      	WORD midiInUnprepareHeader(hMidiIn, lpMidiInHdr, wSize)

This function is the complementary function to midiInPrepareHeader.  It must be called after the device driver has filled a data buffer and returned it to the application to clean up the preparation done by midiInPrepareHeader.

Parameters  	HMIDIIN  hMidiIn

Specifies a handle to the MIDI input device from which the data was received.

LPMIDIHDR  lpMidiInHdr

Specifies a pointer to a MIDIHDRstructure identifying the data buffer that is to be cleaned up.

WORD  wSize

Specifies the size of the MIDIHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MIDIERR_STILLPLAYING

lpMidiInHdr is still in the queue.

Comments    	This function must be called before a data buffer can be freed. After passing a buffer to the device driver with midiInAddBuffer, you must wait until the driver is finished with the buffer before calling midiInUnprepareHeader.  Unpreparing a buffer that has not been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	midiInPrepareHeader


midiOutCacheDrumPatches

Syntax      	WORD midiOutCacheDrumPatches(hMidiOut, wBank, lpKeyArray, wFlags)

This function requests that an internal MIDI synthesizer device preload a specified set of key-based percussion patches. Some synthesizers are not capable of keeping all percussion patches loaded simultaneously. Caching patches ensures specified patches are available.

Parameters  	HMIDIOUT  hMidiOut

Specifies a handle to the opened MIDI output device. This device must be an internal MIDI synthesizer.

WORD  wBank

Specifies which bank of patches should be used. Currently, this parameter must be set to zero.

LPKEYARRAY  lpKeyArray

Specifies a pointer to a KEYARRAYarray indicating the key-based percussion patches to be cached or uncached.

WORD  wFlags

Specifies options for the cache operation. Only one of the following flags can be specified:

MIDI_CACHE_ALL

Cache all of the specified patches. If they can't all be cached, cache none and return MMSYSERR_NOMEM.

MIDI_CACHE_BESTFIT

Cache all of the specified patches. If all patches can't be cached, cache as many patches as possible, change the KEYARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM.

MIDI_CACHE_QUERY

Change the KEYARRAY array to indicate which patches are currently cached.

MIDI_UNCACHE

Uncache the specified patches.

Return Value	Returns zero if the function was successful.  Otherwise, it returns one of the following error codes:

MMSYSERR_INVALHANDLE

The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

The specified device does not support patch caching.

MMSYSERR_NOMEM

The device does not have enough memory to cache all of the requested patches.

Comments    	The KEYARRAY data type is defined as:

typedef WORD KEYARRAY[128];

Each element of the array represents one of the 128 key-based percussion patches and has bits set for each of the 16 MIDI channels that use that particular patch. The least-significant bit represents physical channel 0; the most-significant bit represents physical channel 15. For example, if the patch on key number 60 is used by physical channels 9 and 15, element 60 would be set to 0x8200.

This function only applies to internal MIDI synthesizer devices. Not all internal synthesizers support patch caching. Use the MIDICAPS_CACHE flag to test the dwSupport field of the MIDIOUTCAPS structure filled by midiOutGetDevCaps to see if the device supports patch caching.

See Also	midiOutCachePatches


midiOutCachePatches

Syntax      	WORD midiOutCachePatches(hMidiOut, wBank, lpPatchArray, wFlags)

This function requests that an internal MIDI synthesizer device preload a specified set of patches. Some synthesizers are not capable of keeping all patches loaded simultaneously and must load data from disk when they receive MIDI program change messages. Caching patches ensures specified patches are immediately available.

Parameters  	HMIDIOUT  hMidiOut

Specifies a handle to the opened MIDI output device. This device must be an internal MIDI synthesizer.

WORD  wBank

Specifies which bank of patches should be used. Currently, this parameter must be set to zero.

LPPATCHARRAY  lpPatchArray

Specifies a pointer to a PATCHARRAYarray indicating the patches to be cached or uncached.

WORD  wFlags

Specifies options for the cache operation. Only one of the following flags can be specified:

MIDI_CACHE_ALL

Cache all of the specified patches. If they can't all be cached, cache none and return MMSYSERR_NOMEM.

MIDI_CACHE_BESTFIT

Cache all of the specified patches. If all patches can't be cached, cache as many patches as possible, change the PATCHARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM.

MIDI_CACHE_QUERY

Change the PATCHARRAY array to indicate which patches are currently cached.

MIDI_UNCACHE

Uncache the specified patches.

Return Value	Returns zero if the function was successful.  Otherwise, it returns one of the following error codes:

MMSYSERR_INVALHANDLE

The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

The specified device does not support patch caching.

MMSYSERR_NOMEM

The device does not have enough memory to cache all of the requested patches.

Comments    	The PATCHARRAY data type is defined as:

typedef WORD PATCHARRAY[128];

Each element of the array represents one of the 128 patches and has bits set for each of the 16 MIDI channels that use that particular patch. The least-significant bit represents physical channel 0; the most-significant bit represents physical channel 15 (0x0F). For example, if patch 0 is used by physical channels 0 and 8, element 0 would be set to 0x0101.

This function only applies to internal MIDI synthesizer devices. Not all internal synthesizers support patch caching. Use the MIDICAPS_CACHE flag to test the dwSupport field of the MIDIOUTCAPS structure filled by midiOutGetDevCaps to see if the device supports patch caching.

See Also	midiOutCacheDrumPatches


midiOutClose

Syntax      	WORD midiOutClose(hMidiOut)

This function closes the specified MIDI output device.

Parameters  	HMIDIOUT  hMidiOut

Specifies a handle to the MIDI output device to be closed.  If the function is successful, the handle is no longer valid after this call.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MIDIERR_STILLPLAYING

There are still buffers in the queue.

Comments    	If there are output buffers that have been sent with midiOutLongMsg and haven't been returned to the application,the close operation will fail.  Call midiOutReset to mark all pending buffers as being done.

See Also	midiOutOpen, midiOutReset


midiOutGetDevCaps

Syntax      	WORD midiOutGetDevCaps(wDeviceID, lpCaps, wSize)

This function queries a specified MIDI output device to determine its capabilities.

Parameters  	WORD  wDeviceID

Identifies the MIDI output device to be queried.

LPMIDIOUTCAPS  lpCaps

Specifies a far pointer to a MIDIOUTCAPSstructure.  This structure is filled with information about the capabilities of the device.

WORD  wSize

Specifies the size of the MIDIOUTCAPS structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device id is out of range.

Comments    	Use midiOutGetNumDevs to determine the number of MIDI output devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.  Only wSize bytes (or less) of information will be copied to the location pointed to by lpCaps.  If wSize is 0, nothing will be copied and MMSYSERR_NOERROR is returned.

See Also	midiOutGetNumDevs


midiOutGetErrorText

Syntax      	WORD midiOutGetErrorText(wError, lpText, wSize)

This function retrieves a textual description of the error identified by the specified error number.

Parameters  	WORD  wError

Specifies the error number.

LPSTR  lpText

Specifies a far pointer to a buffer which is filled with the textual error description.

WORD  wSize

Specifies the length of the buffer pointed to by lpText.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADERRNUM

Specified error number is out of range.

Comments    	If the textual error description is longer than the specified buffer,the description is truncated.  The returned error string is always null-terminated. If wSize is 0, nothing is copied and MMSYSERR_NOERROR is returned.  All error descriptions are less than 80 characters long.


midiOutGetNumDevs

Syntax      	WORD midiOutGetNumDevs()

This function retrieves the number of MIDI output devices present in the system.

Return Value	Returns the number of MIDI output devices present in the system.

See Also	midiOutGetDevCaps


midiOutGetVolume

Syntax      	WORD midiOutGetVolume(wDeviceID, lpdwVolume)

This function returns the current volume setting of a MIDI output device.  The device must be opened before the volume can be queried.

Parameters  	WORD  wDeviceID

Identifies the MIDI output device to be queried.

LPDWORD  lpdwVolume

Specifies a far pointer to a location that will be filled with the current volume setting.  The high-order word of this location contains the left channel volume setting and the low-order word contains the right channel setting.  A value of 0xFFFF represents full volume and a value of 0x0000 is silence.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

Comments    	Not all devices support volume changes.  Use the MIDICAPS_VOLUME flag to test the dwSupport field of the MIDIOUTCAPS structure filled by midiOutGetDevCaps to see if the device supports volume control.  Use the MIDICAPS_LRVOLUME flag to test if the device supports volume control on both the left and right channels.  If a device does not support both left and right volume control, only the right channel value is valid.

See Also	midiOutSetVolume


midiOutLongMsg

Syntax      	WORD midiOutLongMsg(hMidiOut, lpMidiOutHdr, wSize)

This function sends a long MIDI message to the specified MIDI output device.  Use this function to send system exclusive messages.

Parameters  	HMIDIOUT  hMidiOut

Specifies a handle to the MIDI output device that the message is sent to.

LPMIDIHDR  lpMidiOutHdr

Specifies a far pointer to a MIDIHDRstructure that describes the long MIDI message.

WORD  wSize

Specifies the size of the MIDIHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MIDIERR_UNPREPARED

lpMidiOutHdr hasn't been prepared.

MIDIERR_NOTREADY

The hardware is busy with other data.

Comments    	The data buffer must be prepared with midiOutPrepareHeader before it is passed to midiOutLongMsg.  The MIDIHDR data structure and the data buffer pointed to by its lpData field must be allocated with GlobalAlloc using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with GlobalLock. This function may not return until the data block has been sent to the output device.

See Also	midiOutShortMsg, midiOutPrepareHeader


midiOutOpen

Syntax      	WORD midiOutOpen(lphMidiOut, wDeviceID, dwCallback, dwCallbackInstance, dwFlags)

This function opens a specified MIDI output device for playback.

Parameters  	LPHMIDIOUT  lphMidiOut

Specifies a far pointer to an HMIDIOUT handle.  This location is filled with a handle identifying the opened MIDI output device.  Use the handle to identify the device when calling other MIDI output functions.

WORD  wDeviceID

Identifies the MIDI output device that is to be opened.

DWORD  dwCallback

Specifies the address of a callback function or a handle to a window that is called during MIDI playback to process messages related to the progress of the playback.  Specify NULL for this parameter if no callback is desired.

DWORD  dwCallbackInstance

Specifies 32 bits of user instance data that is passed to the callback.  This parameter is not used with window callbacks.

DWORD  dwFlags

Specifies a callback flag for opening the device.

CALLBACK_WINDOW

If this flag is specified, dwCallback is assumed to be a window handle.

CALLBACK_FUNCTION

If this flag is specified, dwCallback is assumed to be a callback procedure address.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are (MIDIERR_NOMAP and MIDIERR_NODEVICE apply only when opening the mapper):

MMSYSERR_BADDEVICEID

Specified device ID is out of range.

MMSYSERR_ALLOCATED

Specified resource is already allocated.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

MIDIERR_NOMAP

There is no current map setup.

MIDIERR_NODEVICE

A port in the current map setup doesn't exist.

Comments    	Use midiOutGetNumDevs to determine the number of MIDI output devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present. You may also specify MIDIMAPPER as the device ID to open the MIDI mapper.

If a window is chosen to receive callback information, the following messages are sent to the window procedure function to indicate the progress of MIDI output:  MM_MOM_OPEN, MM_MOM_CLOSE,MM_MOM_DONE.

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of MIDI output: MOM_OPEN, MOM_CLOSE, MOM_DONE.  The callback function must reside in a DLL.  You do not have to use MakeProcInstance to get a procedure-instance address for the callback function.

Callback	void FAR PASCAL MidiOutFunc(hMidiOut, wMsg, dwInstance, dwParam1, dwParam2)

MidiOutFunc is a placeholder for the application-supplied function name.  The actual name must be exported by including it in an EXPORTS statement in the DLL's module-definition file.

Parameters

HMIDIOUT  hMidiOut

Specifies a handle to the MIDI device associated with the callback.

WORD  wMsg

Specifies a MIDI output message.

DWORD  dwInstance

Specifies the 32 bits of instance data specified with midiOutOpen.

DWORD  dwParam1

Specifies a parameter for the message.

DWORD  dwParam2

Specifies a parameter for the message.

Comments

Because the callback is accessed at interrupt time, it must reside in a DLL and its code segment must be specified as FIXED in the module-definition file for the DLL.  Any data that the callback accesses must be in a FIXED data segment as well.  The callback may not make any system calls except for PostMessage, timeGetSystemTime,timeGetTime, midiOutShortMsg, midiOutLongMsg, and OutputDebugStr.

See Also	midiOutClose


midiOutPrepareHeader

Syntax      	WORD midiOutPrepareHeader(hMidiOut, lpMidiOutHdr, wSize)

This function prepares a MIDI system exclusive data block for output.

Parameters  	HMIDIOUT  hMidiOut

Specifies a handle to the MIDI output device that the data block will be sent to.

LPMIDIHDR  lpMidiOutHdr

Specifies a far pointer to a MIDIHDRstructure that identifies the data block to be prepared.

WORD  wSize

Specifies the size of the MIDIHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

Comments    	The MIDIHDR data structure and the data block pointed to by its lpData field must be allocated with GlobalAlloc using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with GlobalLock. Preparing a header that has already been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	midiOutUnprepareHeader


midiOutReset

Syntax      	WORD midiOutReset(hMidiOut)

This function turns off all notes on all MIDI channels for the specified MIDI output device.

Parameters  	HMIDIOUT  hMidiOut

Specifies a handle to the MIDI output device that is to be reset.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	If the specified MIDI output device is an output port, a note off message for each note of each channel is sent.  In addition, a sustain (damper pedal) off controller message is sent for each channel.

See Also	midiOutLongMsg, midiOutClose


Parameters  	HMIDIOUT  hMidiOut

Specifies a handle to the MIDI output device that sent the data block to the device.

LPMIDIHDR  lpMidiOutHdr

Specifies a pointer to a MIDIHDRstructure identifying the device that played the data block.

WORD  wSize

Specifies the size of the MIDIHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MIDIERR_STILLPLAYING

lpMidiOutHdr is still in the queue.

Comments    	This function must be called before a data buffer can be freed. After passing a buffer to the device driver with midiOutLongMsg, you must wait until the driver is finished with the buffer before calling midiOutUnprepareHeader.  Unpreparing a buffer that has not been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	midiOutPrepareHeader


mmioAdvance

Syntax      	WORD mmioAdvance(hmmio, lpmmioinfo, wFlags)

This function advances the I/O buffer of a file set up for direct I/O buffer access with mmioGetInfo. If the file is opened for reading, the I/O buffer is filled from the disk.  If the file is opened for writing and the MMIO_DIRTY flag is set in the dwFlags field of the MMIOINFO structure,the buffer is written to disk.  The pchNext,pchEndRead, and pchEndWrite fields of the MMIOINFO structure are updated to reflect the new state of the I/O buffer.

Parameters  	HMMIO  hmmio

Specifies the file handle for a file opened with mmioOpen.

LPMMIOINFO  lpmmioinfo

Specifies a far pointer to the MMIOINFO structure obtained with mmioGetInfo.

WORD  wFlags

Specifies options for the operation. Contains exactly one of the following two flags:

MMIO_READ

The buffer is filled from the file.

MMIO_WRITE

The buffer is written to the file.

Return Value	The return value is zero if the operation is successful. Otherwise, the return value specifies an error code.

The error code may be one of the following:

MMIOERR_CANNOTWRITE

The contents of the buffer could not be written to disk.

MMIOERR_CANNOTREAD

An error occurred while re-filling the buffer.

MMIOERR_UNBUFFERED

The specified file is not opened for buffered I/O.

MMIOERR_CANNOTEXPAND

The specified memory file cannot be expanded, probably because the adwInfo[0] field was set to zero in the initial call to mmioOpen.

MMIOERR_OUTOFMEMORY

There was not enough memory to expand a memory file for further writing.

Comments    	If the specified file is opened for writing or for both reading and writing, the I/O buffer will be flushed to disk before the next buffer is read. If the I/O buffer cannot be written to disk because the disk is full, then mmioAdvance will return MMIOERR_CANNOTWRITE.

If the specified file is only open for writing, the MMIO_WRITE flag must be specified.

If you have written to the I/O buffer, you must set the MMIO_DIRTY flag in the dwFlags field of the MMIOINFO structure before calling mmioAdvance. Otherwise, the buffer will not be written to disk.

If the end of file is reached, mmioAdvance will still return success, even though no more data can be read.  Thus, to check for the end of the file, it is necessary to see if the pchNext and pchEndRead fields of the MMIOINFO structure are equal after calling mmioAdvance.

See Also	mmioGetInfo, MMIOINFO


mmioAscend

Syntax      	WORD mmioAscend(hmmio, lpck, wFlags)

This function ascends out of a chunk in a RIFF file descended into with mmioDescend or created with mmioCreateChunk.

Parameters  	HMMIO  hmmio

Specifies the file handle of an open RIFF file.

LPMMCKINFO  lpck

Specifies a far pointer to a caller-supplied MMCKINFO structure previously filled by mmioDescend or mmioCreateChunk.

WORD  wFlags

Is not used and should be set to zero.

Return Value	The return value is zero if the function is successful. Otherwise, the return value specifies an error code.

Comments    	If the chunk was descended into using mmioDescend, then mmioAscend seeks to the location following the end of the chunk (past the extra pad byte, if any).

If the chunk was created and descended into using mmioCreateChunk, or if the MMIO_DIRTY flag is set in the dwFlags field of the MMCKINFO structure referenced by lpck, then the current file position is assumed to be the end of the data portion of the chunk. If the chunk size is not the same as the value stored in the cksize of lpck before mmioCreateChunkwas called, then mmioAscend corrects the chunk size in the file before ascending from the chunk. If the chunk size is odd, mmioAscend writes a null pad byte at the end of the chunk. After ascending from the chunk, the current file position is the location following the end of the chunk (past the extra pad byte,if any).

See Also	mmioDescend, mmioCreateChunk, MMCKINFO


mmioClose

Syntax      	WORD mmioClose(hmmio, wFlags)

This function closes a file opened with mmioOpen.

Parameters  	HMMIO  hmmio

Specifies the file handle of the file to close.

WORD  wFlags

Specifies options for the close operation.

MMIO_FHOPEN

If the file was opened by passing the DOS file handle of an already-opened file to mmioOpen, then using this flag tells mmioClose to close the MMIO file handle, but not the DOS file handle.

Return Value	The return value is zero if the function is successful. Otherwise, the return value is an error code, either from mmioFlush or from the I/O procedure.

See Also	mmioOpen, mmioFlush


mmioCreateChunk

Syntax      	WORD mmioCreateChunk(hmmio, lpck, wFlags)

This function creates a chunk in a RIFF file opened with mmioOpen. The new chunk is created at the current file position. After the new chunk is created, the current file position is the beginning of the data portion of the new chunk.

Parameters  	HMMIO  hmmio

Specifies the file handle of an open RIFF file.

LPMMCKINFO  lpck

Specifies a pointer to a caller-supplied MMCKINFO structure containing information about the chunk to be created. The MMCKINFO structure should be set up as follows:

-- The ckid field specifies the chunk ID of the chunk. If wFlags includes MMIO_CREATERIFF or MMIO_CREATELIST,this field will be filled by mmioCreateChunk.

-- The cksize field specifies the size of the data portion of the chunk, including the form type or list type (if any). If this value is not correct when mmioAscend is called to mark the end of the chunk, them mmioAscend will correct the chunk size.

-- The fccType field specifies the form type or list type is the chunk is a "RIFF" or "LIST" chunk. If the chunk is not a "RIFF" or "LIST" chunk, this field need not filled in.

-- The dwDataOffset field need not be filled in. The mmioCreateChunk function will fill this field with the file offset of the data portion of the chunk.

-- The dwFlags field need not be filled in. The mmioCreateChunk function will set the MMIO_DIRTY flag in dwFlags.

WORD  wFlags

Specifies flags to optionally create either a "RIFF" chunk or a "LIST" chunk. Contains up to one of the following flags:

MMIO_CREATERIFF

Creates a "RIFF" chunk.

MMIO_CREATELIST

Creates a "LIST" chunk.

Return Value	The return value is zero if the function is successful. Otherwise, the return value specifies an error code.

Comments    	This function does not insert a chunk into the middle of a file. If a chunk is created anywhere but the end of a file,mmioCreateChunk will overwrite existing information in the file.


mmioDescend

Syntax      	WORD mmioDescend(hmmio, lpck, lpckParent, wFlags)

This function descends into a chunk of a RIFF file opened with mmioOpen. It can also search for a given chunk.

Parameters  	HMMIO  hmmio

Specifies the file handle of an open RIFF file.

LPMMCKINFO  lpck

Specifies a far pointer to a caller-supplied  MMCKINFO structure that mmioDescend fills with the following information:

-- The ckid field is the chunk ID of the chunk.

-- The cksize field is the size of the data portion of the chunk. The data size includes the form type or list type (if any), but does not include the 8-byte chunk header or the pad byte at the end of the data (if any).

-- The fccType field is the form type if ckid is "RIFF", or the list type if ckid is "LIST". Otherwise, it is NULL.

-- The dwDataOffset field is the file offset of the beginning of the data portion of the chunk. If the chunk is a "RIFF" chunk or a "LIST" chunk, then dwDataOffsetis the offset of the form type or list type.

-- The dwFlags contains other information about the chunk. Currently, this information is not used and is set to zero.

If the MMIO_FINDCHUNK, MMIO_FINDRIFF, or MMIO_FINDLIST flag is specified for wFlags, then the MMCKINFO structure is also used to pass parameters to mmioDescend:

-- The ckid field specifies the four-character code of the chunk ID, form type, or list type to search for.

LPMMCKINFO  lpckParent

Specifies a far pointer to an optional caller-supplied MMCKINFO structure identifying the parent of the chunk being searched for. A parent of a chunk is the enclosing chunk--only "RIFF" and "LIST"chunks may be parents.  If lpckParent is not NULL, then mmioDescend assumes the MMCKINFO structure it refers to was filled when mmioDescend was called to descend into the parent chunk, and mmioDescend will only search for a chunk within the parent chunk. Set lpckParent to NULL if no parent chunk is being specified.

WORD  wFlags

Specifies search options. Contains up to one of the following flags. If no flags are specified,mmioDescend descends into the chunk beginning at the current file position.

MMIO_FINDCHUNK

Searches for a chunk with the specified chunk ID.

MMIO_FINDRIFF

Searches for a chunk with chunk ID "RIFF"and with the specified form type.

MMIO_FINDLIST

Searches for a chunk with chunk ID "LIST"and with the specified form type.

Return Value	The return value is zero if the function is successful. Otherwise, the return value specifies an error code. If the end of the file (or the end of the parent chunk, if given) is reached before the desired chunk is found, the return value is MMIOERR_CHUNKNOTFOUND.

Comments    	A RIFF chunk consists of a four-byte chunk ID (type FOURCC),followed by a four-byte chunk size (type DWORD), followed by the data portion of the chunk, followed by a null pad byte if the size of the data portion is odd. If the chunk ID is "RIFF" or "LIST", the first four bytes of the data portion of the chunk are a form type or list type (type FOURCC).

If mmioDescend is used to search for a chunk, and no parent chunk is specified, the file position should be at the beginning of a chunk before calling mmioDescend. The search begins at the current file position and continues to the end of the file. If a parent chunk is specified, the file position should be somewhere within the parent chunk before calling mmioDescend. In this case,the search begins at the current file position and continues to the end of the parent chunk.

If mmioDescend is unsuccessful in searching for a chunk, the current file position is undefined. If mmioDescend is successful, the current file position is changed. If the chunk is a "RIFF" or "LIST" chunk, the new file position will be just after the form type or list type (12 bytes from the beginning of the chunk). For other chunks, the new file position will be the start of the data portion of the chunk (8 bytes from the beginning of the chunk).

For efficient RIFF file I/O, use buffered I/O.

See Also	mmioAscend, MMCKINFO


mmioFlush

Syntax      	WORD mmioFlush(hmmio, wFlags)

This function writes the I/O buffer of a file to disk, if the I/O buffer has been written to.

Parameters  	HMMIO  hmmio

Specifies the file handle of a file opened with mmioOpen.

WORD  wFlags

Is not used and should be set to zero.

Return Value	The return value is zero if the function is successful. Otherwise, the return value specifies an error code.

The error code may be one of the following:

MMIOERR_CANNOTWRITE

The contents of the buffer could not be written to disk.

Comments    	Closing a file with mmioClose will automatically flush its buffer.

If there is insufficient disk space to write the buffer, mmioFlush will fail, even if the preceding mmioWritecalls were successful.


mmioFOURCC

Syntax      	FOURCC mmioFOURCC(ch0, ch1, ch2, ch3)

This macro converts four characters to to a four-character code.

Parameters  	CHAR  ch0

The first character of the four-character code.

CHAR  ch1

The second character of the four-character code.

CHAR  ch2

The third character of the four-character code.

CHAR  ch3

The fourth character of the four-character code.

Return Value	The return value is the four-character code created from the given characters.

Comments    	This macro does not check to see if the four character code follows any conventions regarding which characters to include in a four-character code.

See Also	mmioStringToFOURCC


mmioGetInfo

Syntax      	WORD mmioGetInfo(hmmio, lpmmioinfo, wFlags)

This function retrieves information about a file opened with mmioOpen. This information allows the caller to directly access the I/O buffer, if the file is opened for buffered I/O.

Parameters  	HMMIO  hmmio

Specifies the file handle of the file.

LPMMIOINFO  lpmmioinfo

Specifies a far pointer to a caller-allocated MMIOINFO structure that mmioGetInfofills with information about the file. See the MMIOINFO structure and the mmioOpen function for information about the fields in this structure.

WORD  wFlags

Is not used and should be set to zero.

Return Value	The return value is zero if the function is successful. Otherwise, the return value is an error code.

Comments    	To directly access the I/O buffer of a file opened for buffered I/O, use the following fields of the MMIOINFO structure filled by mmioGetInfo:

-- The pchNext field points to the next byte in the buffer that can be read or written. When you read or write, increment pchNext by the number of bytes read or written.

-- The pchEndRead field points to one byte past the last valid byte in the buffer that can be read.

-- The pchEndWrite field points to one byte past the last location in the buffer that can be written.

Once you read or write to the buffer and modify pchNext, do not call any MMIO function except mmioAdvance until you call mmioSetInfo. Call mmioSetInfowhen you are finished directly accessing the buffer.

When you reach the end of the buffer specified by pchEndRead or pchEndWrite, call mmioAdvance to fill the buffer from the disk, or write the buffer to the disk. The mmioAdvance function will update the pchNext, pchEndRead, and pchEndWrite fields in the MMIOINFO structure for the file.

Before calling mmioAdvance or mmioSetInfo to flush a buffer to disk, set the MMIO_DIRTY flag in the dwFlagsfield of the MMIOINFO structure for the file. Otherwise, the buffer will not get written to disk.

Do not decrement pchNext or modify any fields in the MMIOINFO structure other than pchNext and dwFlags. Do not set any flags in dwFlagsexcept MMIO_DIRTY.

See Also	mmioSetInfo, MMIOINFO


mmioInstallIOProc

Syntax      	LPMMIOPROC mmioInstallIOProc(fccIOProc, pIOProc, dwFlags)

This function installs or removes a custom I/O procedure. It will also locate an installed I/O procedure, given its corresponding four-character code.

Parameters  	FOURCC  fccIOProc

Specifies a four-character code identifying the I/O procedure to install, remove, or locate. All characters in this four-character code should be uppercase characters.

LPMMIOPROC  pIOProc

Specifies the address of the I/O procedure to install. To remove or locate an I/O procedure, set this parameter to NULL.

DWORD  dwFlags

Specifies one of the following flags indicating whether the I/O procedure is being installed, removed, or located:

MMIO_INSTALLPROC

Installs the specified I/O procedure.

MMIO_REMOVEPROC

Removes the specified I/O procedure.

MMIO_FINDPROC

Searches for the specified I/O procedure.

Return Value	The return value is the address of the I/O procedure installed, removed, or located. If there is an error, the return value is NULL.

Comments    	If the I/O procedure resides in the application, use MakeProcInstance to get a procedure-instance address and specify this address for pIOProc. You don't need to get a procedure-instance address if the I/O procedure resides in a DLL.

Callback	LONG FAR PASCAL IOProc(lpmmioinfo, wMsg, lParam1, lParam2)

IOProc is a placeholder for the application-supplied function name. The actual name must be exported by including it in a EXPORTS statement in the application's module-definitions file.

Parameters

LPSTR  lpmmioinfo

Specifies a far pointer to an MMIOINFO structure containing information about the open file.  The I/O procedure must maintain the lDiskOffsetfield in this structure to indicate the file offset to the next read or write location. The I/O procedure can use the adwInfo[] field to store state information. The I/O procedure should not modify any other fields of the MMIOINFO structure.

WORD  wMsg

Specifies a message indicating the requested I/O operation. Messages that can be received include MMIOM_OPEN, MMIOM_CLOSE, MMIOM_READ, MMIOM_WRITE,and MMIOM_SEEK.

LONG  lParam1

Specifies a parameter for the message.

LONG  lParam2

Specifies a parameter for the message.

Return Value

The return value depends on the message specified by  wMsg>. If the I/O procedure does not recognize a message, it should return zero.

Comments

The four-character code specified by the fccIOProc field in the MMIOINFO structure associated with a file identifies a filename extension for a custom storage system. When an application calls mmioOpen with a filename such as "foo.xyz!bar", the I/O procedure associated with the four-character code "XYZ " is called to open the "bar" element of the file "foo.xyz".

The mmioInstallIOProc function maintains a separate list of installed I/O procedures for each Windows application. Therefore,different applications can use the same I/O procedure identifier for different I/O procedures without conflict.

To share an I/O procedure among applications, the I/O procedure must reside in a DLL called by each application using it. Each application using the shared I/O procedure must call mmioInstallIOProc to install the procedure (or call the DLL to install the procedure on behalf of the application). Each application must call mmioInstallIOProc to remove the I/O procedure before terminating.

If an application calls mmioInstallIOProc more than once to register the same I/O procedure, then it must call mmioInstallIOProc to remove the procedure once for each time it installed the procedure.

mmioInstallIOProc will not prevent an application from installing two different I/O procedures with the same identifier, or installing an I/O procedure with one of the predefined identifiers ("DOS ", "MEM ", or "BND "). The most recently installed procedure takes precedence, and the most recently installed procedure is the first one to get removed.

See Also	mmioOpen


mmioOpen

Syntax      	HMMIO mmioOpen(szFilename, lpmmioinfo, dwOpenFlags)

This function opens a file for unbuffered or buffered I/O. The file may be a DOS file, a memory file, or an element of a custom storage system.

Parameters  	LPSTR  szFilename

Specifies a far pointer to a string containing the filename of the file to open. If no I/O procedure is specified to open the file, then the filename determines how the file is opened, as follows:

-- If the filename does not contain "+", then it is assumed to be the name of a DOS file.

-- If the filename is of the form "foo.ext+bar", then the extension "EXT " is assumed to identify an installed I/O procedure which is called to perform I/O on the file (see mmioInstallIOProc). -- If the filename is NULL and no I/O procedure is given, then adwInfo[0] is assumed to be the DOS file handle of a currently open file.

The filename should not be longer than 128 bytes, including the terminating NULL.

When opening a memory file, set szFilename to NULL.

LPMMIOINFO  lpmmioinfo

Specifies a far pointer to an MMIOINFO structure containing extra parameters used by mmioOpen. Unless you are opening a memory file, specifying the size of a buffer for buffered I/O, or specifying an uninstalled I/O procedure to open a file, this parameter should be NULL.

If lpmmioinfo is not NULL, all unused fields of the MMIOINFO structure it references must be set to zero, including the reserved fields.

DWORD  dwOpenFlags

Specifies option flags for the open operation. The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive--only one should be specified. The MMIO_COMPAT,MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD, and MMIO_DENYNONE flags are DOS file-sharing flags, and can only be used after the DOS command SHARE has been executed.

MMIO_READ

Opens the file for reading only.  This is the default, if MMIO_WRITE and MMIO_READWRITE are not specified.

MMIO_WRITE

Opens the file for writing.  You should not read from a file opened in this mode.

MMIO_READWRITE

Opens the file for both reading and writing.

MMIO_CREATE

Creates a new file. If the file already exists, it is truncated to zero length. For memory files, MMIO_CREATE indicates the end of the file is initially at the start of the buffer.

MMIO_DELETE

Deletes a file. If this flag is specified,szFilename should not be NULL. The return value will be TRUE (cast to HMMIO) if the file was deleted successfully, FALSE otherwise.  Do not call mmioClosefor a file that has been deleted.  If this flag is specified,all other flags are ignored.

MMIO_ALLOCBUF

Opens a file for buffered I/O. To allocate a buffer larger or smaller than the default buffer size (8K), set the cchBuffer field of the MMIOINFO structure to the desired buffer size. If cchBuffer is zero, then the default buffer size is used. If you are providing your own I/O buffer, then the MMIO_ALLOCBUF flag should not be used.

MMIO_COMPAT

Opens the file with compatibility mode,allowing any process on a given machine to open the file any number of times.  mmioOpen fails if the file has been opened with any of the other sharing modes.

MMIO_EXCLUSIVE

Opens the file with exclusive mode,denying other processes both read and write access to the file. mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current process.

MMIO_DENYWRITE

Opens the file and denies other processes write access to the file.  mmioOpen fails if the file has been opened in compatibility or for write access by any other process.

MMIO_DENYREAD

Opens the file and denies other processes read access to the file.  mmioOpen fails if the file has been opened in compatibility mode or for read access by any other process.

MMIO_DENYNONE

Opens the file without denying other processes read or write access to the file.  mmioOpenfails if the file has been opened in compatibility mode by any other process.

Return Value	The return value is a handle to the opened file. This handle is not a DOS file handle--do not use it with any file I/O functions other than MMIO functions.

If the file cannot be opened, the return value is NULL.  If lpmmioinfo is not NULL, then its wError field will contain extended error information returned by the I/O procedure.

Comments    	If lpmmioinfo references an MMIOINFO structure, set up the fields as described below. All unused fields must be set to zero, including reserved fields.

-- To request that a file be opened with an installed I/O procedure, set the fccIOProc field to the four-character code of the I/O procedure,and set the pIOProc field to NULL.

-- To request that a file be opened with an uninstalled I/O procedure,set the pIOProc field to point to the I/O procedure, and set fccIOProc to NULL.

-- To request that mmioOpen determine which I/O procedure to use to open the file based on the filename contained in szFilename,set both fccIOProc and pIOProc to NULL. This is the default behavior if no MMIOINFO structure is specified.

-- To open a memory file using an internally allocated and managed buffer, set the pchBuffer field to NULL,fccIOProc to FOURCC_MEM,cchBuffer to the initial size of the buffer, and adwInfo[0] to the incremental expansion size of the buffer. This memory file will automatically be expanded in increments of adwInfo[0] bytes when necessary. Specify the MMIO_CREATE flag for the dwOpenFlags parameter to initially set the end of the file to be the beginning of the buffer.

-- To open a memory file using a caller-supplied buffer, set the pchBuffer field to point to the memory buffer,fccIOProc to FOURCC_MEM,cchBuffer to the size of the buffer, and adwInfo[0] to the incremental expansion size of the buffer. The expansion size in adwInfo[0] should only be non-zero if pchBuffer is a pointer obtained by calling GlobalAlloc and GlobalLock, since GlobalReAlloc will be called to expand the buffer.  In particular, if pchBuffer points to a local or global array, a block of memory in the local heap, or a block of memory allocated by GlobalDosAlloc, adwInfo[0] must be zero. Specify the MMIO_CREATE flag for the dwOpenFlags parameter to initially set the end of the file to be the beginning of the buffer;otherwise, the entire block of memory will be considered readable.

-- To use a currently open DOS file handle with MMIO, set the fccIOProc field to FOURCC_DOS,pchBuffer to NULL, and adwInfo[0] to the DOS file handle.  Note that offsets within the file will be relative to the beginning of the file, and will not depend on the DOS file position at the time mmioOpen is called; the initial MMIO offset will be the same as the DOS offset when mmioOpen is called. Later, to close the MMIO file handle without closing the DOS file handle, pass the MMIO_FHOPEN flag to mmioClose.

You must call mmioClose to close a file opened with mmioOpen. Open files are not automatically closed when an application exits.

See Also	mmioClose


mmioRead

Syntax      	LONG mmioRead(hmmio, pch, cch)

This function reads a specified number of bytes from a file opened with mmioOpen.

Parameters  	HMMIO  hmmio

Specifies the file handle of the file to be read.

HPSTR  pch

Specifies a huge pointer to a buffer to contain the data read from the file.

LONG  cch

Specifies the number of bytes to read from the file.

Return Value	The return value is the number of bytes actually read. If the end of the file has been reached and no more bytes can be read, the return value is zero. If there is an error reading from the file, the return value is -1.

See Also	mmioWrite


mmioSeek

Syntax      	LONG mmioSeek(hmmio, lOffset, iOrigin)

This function changes the current file position in a file opened with mmioOpen. The current file position is the location in the file where data is read or written.

Parameters  	HMMIO  hmmio

Specifies the file handle of the file to seek in.

LONG  lOffset

Specifies an offset to change the file position.

int  iOrigin

Specifies how the offset specified by lOffset is interpreted. Contains one of the following flags:

SEEK_SET

Seeks to lOffset bytes from the beginning of the file.

SEEK_CUR

Seeks to lOffset bytes from the current file position.

SEEK_END

Seeks to lOffset bytes from the end of the file.

Return Value	The return value is the new file position in bytes, relative to the beginning of the file. If there is an error, the return value is -1.

Comments    	Seeking to an invalid location in the file, such as past the end of the file, may not cause mmioSeek to return an error,but may cause subsequent I/O operations on the file to fail.

To locate the end of a file, call mmioSeek with lOffsetset to zero and iOrigin set to SEEK_END.


mmioSendMessage

Syntax      	LONG mmioSendMessage(hmmio, wMsg, lParam1, lParam2)

This function sends a message to the I/O procedure associated with the specified file.

Parameters  	HMMIO  hmmio

Specifies the file handle for a file opened with mmioOpen.

WORD  wMsg

Specifies the message to send to the I/O procedure.

LONG  lParam1

Specifies a parameter for the message.

LONG  lParam2

Specifies a parameter for the message.

Return Value	The return value depends on the message. If the I/O procedure does not recognize the message, the return value is zero.

Comments    	Use this function to send custom user-defined messages. Do not use it to send the MMIOM_OPEN, MMIOM_CLOSE,MMIOM_READ, MMIOM_WRITE, and MMIOM_SEEK messages. Define custom messages to be greater than or equal to the MMIOM_USER constant.

See Also	mmioInstallIOProc


mmioSetBuffer

Syntax      	WORD mmioSetBuffer(hmmio, pchBuffer, cchBuffer, wFlags)

This function enables or disables buffered I/O, or changes the buffer or buffer size for a file opened with mmioOpen.

Parameters  	HMMIO  hmmio

Specifies the file handle of the file.

LPSTR  pchBuffer

Specifies a far pointer to a caller-supplied buffer to use for buffered I/O. If NULL,mmioSetBuffer allocates an internal buffer for buffered I/O.

LONG  cchBuffer

Specifies the size of the caller-supplied buffer, or the size of the buffer for mmioSetBuffer to allocate.

WORD  wFlags

Is not used and should be set to zero.

Return Value	The return value is zero if the function is successful. Otherwise, the return value specifies an error code. If an error occurs, the file handle remains valid.

The error code may be one of the following:

MMIOERR_CANNOTWRITE

The contents of the old buffer could not be written to disk, so the operation was aborted.

MMIOERR_OUTOFMEMORY

The new buffer could not be allocated,probably due to a lack of available memory.

Comments    	To enable buffering using an internal buffer, set pchBuffer to NULL and cchBuffer to the desired buffer size.

To supply your own buffer, set pchBuffer to point to the buffer,and set cchBuffer to the size of the buffer.

To disable buffered I/O, set pchBuffer to NULL and cchBuffer to zero.

If buffered I/O is already enabled using an internal buffer, you can reallocate the buffer to a different size by setting pchBuffer to NULL and cchBuffer to the new buffer size. The contents of the buffer is not changed, unless the buffer is shrunk and the current file position is in the truncated part of the buffer.


mmioSetInfo

Syntax      	WORD mmioSetInfo(hmmio, lpmmioinfo, wFlags)

This function updates the information retrieved by mmioGetInfo about a file opened with mmioOpen. Use this function to terminate direct buffer access of a file opened for buffered I/O.

Parameters  	HMMIO  hmmio

Specifies the file handle of the file.

LPMMIOINFO  lpmmioinfo

Specifies a far pointer to an MMIOINFO structure filled with information with mmioGetInfo.

WORD  wFlags

Is not used and should be set to zero.

Return Value	The return value is zero if the function is successful. Otherwise, the return value specifies an error code.

Comments    	If you have written to the file I/O buffer, set the MMIO_DIRTY flag in the dwFlags field of the MMIOINFOstructure before calling mmioSetInfo to terminate direct buffer access. Otherwise, the buffer will not get flushed to disk.

See Also	mmioGetInfo, MMIOINFO


mmioStringToFOURCC

Syntax      	FOURCC mmioStringToFOURCC(sz, wFlags)

This function converts a null-terminated string to a four-character code.

Parameters  	LPSTR  sz

Specifies a far pointer to a null-terminated string to a four-character code.

WORD  wFlags

Specifies options for the conversion:

MMIO_TOUPPER

Converts all characters to uppercase.

Return Value	The return value is the four character code created from the given string.

Comments    	This function does not check to see if the string referenced by sz follows any conventions regarding which characters to include in a four-character code.  The string is simply copied to a four-character code, padding with blanks to the right if required, and truncated to four characters if required.

See Also	mmioFOURCC


mmioWrite

Syntax      	LONG mmioWrite(hmmio, pch, cch)

This function writes a specified number of bytes to a file opened with mmioOpen.

Parameters  	HMMIO  hmmio

Specifies the file handle of the file.

HPSTR  pch

Specifies a huge pointer to the buffer to be written to the file.

LONG  cch

Specifies the number of bytes to write to the file.

Return Value	The return value is the number of bytes actually written. If there is an error writing to the file, the return value is -1.

Comments    	The current file position is incremented by the number of bytes written.

See Also	mmioRead


mmpAnimate

Syntax      	int mmpAnimate(idMovie)

This function performs the transition to the next frame in the movie. If sufficient time has elapsed for the display of the current frame, it prepares the next frame, displays the frame,and plays any embedded audio or MCI commands for the frame.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns zero if unsuccessful, or one of the following values if successful:

MMP_ANIM_DRAW

The frame was advanced.

MMP_TEMPO_WAIT

The frame was not advanced. The current frame has not been displayed long enough. The Movie Player is waiting for the frame's display period (defined by its tempo setting) to expire.

MMP_MOUSE_WAIT

The frame was not advanced. The current frame's tempo value specifies a wait for a mouse click. The Movie Player is waiting for the stage window to receive a mouse-button message.

MMP_DEVICE_WAIT

The frame was not advanced. As a result of encountering an mciWait command in the script channel, the Movie Player is waiting for the last MCI command sent to the specified device to finish.

MMP_ANIM_STOPPED

The frame was not advanced. The Movie Player instance is not in the animation state. Possible reasons are that mmpStartAnimating has not been called,that mmpStopAnimating was called, or that the movie has reached the last frame.

Comments    	When calling mmpAnimate from the message loop, you should call WaitMessage if mmpAnimate returns a negative value.

To notify the Movie Player that animation is to begin,you must call mmpStartAnimating once before calling this function.

See Also	mmpStartAnimating, mmpStopAnimating, mmpAnimStatus, mmpAnimStopped


mmpAnimStatus

Syntax      	int mmpAnimStatus(idMovie)

This function returns the animation status. Its return values are identical to those used by the mmpAnimate function; however,calling mmpAnimStatus does not advance the movie frame.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns one of the following values:

MMP_ANIM_STOPPED

The Movie Player instance is not in the animation state. Possible reasons are that mmpStartAnimating has not been called,that mmpStopAnimating was called, or that the movie has reached the last frame.

MMP_ANIM_DRAW

The frame will be advanced.

MMP_TEMPO_WAIT

The current frame has not been displayed long enough. The Movie Player is waiting for the frame's display period (defined by its tempo setting) to expire.

MMP_MOUSE_WAIT

The current frame's tempo value specifies a wait for a mouse click. The Movie Player is waiting for the stage window to receive a mouse-button message.

MMP_DEVICE_WAIT

As a result of encountering an mciWait command in the script channel, the Movie Player is waiting for the last MCI command sent to the specified device to finish.

Comments    	Use this function to determine when the Movie Player is about to advance the movie frame.

See Also	mmpAnimate, mmpAnimStopped


mmpAnimStopped

Syntax      	BOOL mmpAnimStopped(idMovie)

This function determines whether the movie is stopped.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns TRUE if movie is stopped. Returns FALSE if movie is running.


mmpClose

Syntax      	BOOL mmpClose(idMovie, wOptions)

This function shuts down an instance of the Movie Player.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

WORD  wOptions

Not used.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	This function stops the animation, clears the playback window,unloads the movie file, frees memory associated with the Movie Player instance, and shuts down the Movie Player instance.

A return value of FALSE indicates a Movie Player error; the movie ID is no longer valid. To get an error value, immediately call mmpError with a NULL movie ID.

See Also	MMPOpen, mmpError


mmpError

Syntax      	int mmpError(idMovie, lpszErrorString, wLen)

This function returns an error code for a Movie Player instance and optionally fills a character buffer with a descriptive error message.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance. Pass a NULL value to this parameter to retrieve information about the error that occurred on the last Movie Player operation.

LPSTR  lpszErrorString

Pointer to an error message buffer. If this pointer is not NULL, the buffer is filled with a descriptive error message. If you pass a NULL pointer, no error message string is copied.

WORD  wLen

Specifies the length of the buffer referenced by the lpszErrorString parameter. The maximum message length is specified by the constant MMP_MAXERRORLENGTH.

Return Value	Returns one of the following codes, which identify the last error that occurred:

MMPERR_NO_ERROR

Indicates no error occurred.

MMPERR_FATAL_ERROR

Indicates that a fatal error occurred.

MMPERR_STAGE_ERROR

Indicates an error occurred while creating the stage window.

MMPERR_FILE_VER

Indicates the movie file version is incompatible with the Movie Player.

MMPERR_FILE_TYPE

Indicates the file is not a RIFF RMMP movie file.

MMPERR_OPEN_ERROR

Indicates a DOS error occurred while trying to open the file.

MMPERR_READ_ERROR

Indicates a DOS error occurred while trying to read from the file.

MMPERR_EOF_ERROR

Indicates the Movie Player encountered an unexpected end-of-file.

MMPERR_REC_HEADER

Indicates an error in the file record header.

MMPERR_CAST_ERROR

Indicates an error occurred while trying to read a cast member.

MMPERR_CAST_MAP_ERROR

Indicates a cast-list mapping mismatch.

MMPERR_MEM_ALLOC

Indicates insufficient memory to complete the operation.

MMERR_BAD_PARM

Indicates a bad or missing parameter passed to the Movie Player function.

MMPERR_BAD_ID

Indicates an incorrect movie ID was used when calling a Movie Player function from a frame-hook function.

Comments    	After receiving an error return value from a Movie Player function,you should call mmpError to retrieve a specific error code and optional error text string.


mmpFileLoaded

Syntax      	BOOL mmpFileLoaded(idMovie)

This function determines whether a movie file has been loaded into the Movie Player instance.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns TRUE if a file is loaded, otherwise returns FALSE.

See Also	mmpLoadFile


mmpFreeFile

Syntax      	BOOL mmpFreeFile(idMovie, wOptions)

This function frees memory associated with a movie file previously loaded by mmpLoadFile.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

WORD  wOptions

Can contain the following flag:

MMP_ERASE_FRAME

Clear the stage window.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	If the movie is currently running, the animation is stopped and the file is unloaded.

See Also	mmpLoadFile, mmpFileLoaded


mmpGetCurFrame

Syntax      	int mmpGetCurFrame(idMovie)

This function returns the number of the frame displayed in the stage window.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns the current frame index. Returns zero if an error occurs.

Comments    	Frame numbering starts at 1.

See Also	mmpGoToFrame, mmpIsLastFrame


mmpGetFileInfo

Syntax      	BOOL mmpGetFileInfo(lpszFileName, lpInfo)

This function returns information about a movie file on disk.

Parameters  	LPSTR  lpszFileName

Specifies the name or file handle of an RMMP-format movie file.

To specify a movie filename, pass a far pointer to a character buffer containing the DOS filename of the movie file.

To specify a file handle, set the high-order word to zero and set the low-order word to the file handle of an open file. If you specify a file handle, the file pointer must point to the beginning of the RMMP chunk (at the first byte of the "RIFF" chunk ID).

LPMMPMOVIEINFO  lpInfo

Points to an MMPMOVIEINFO structure to be filled with information about the specified movie file.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

See Also	mmpGetMovieInfo


mmpGetFrameHook

Syntax      	FARPROC mmpGetFrameHook(idMovie)

Provides pointer to the most recently attached callback function.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns a FARPROC pointer to the most recently attached callback function. Returns NULL if no function is attached.

See Also	mmpSetFrameHook, MMP_PROCESS_FRAME, MMP_PROCESS_SCRIPT


mmpGetInfo

Syntax      	BOOL mmpGetInfo(idMovie, nIndex, lpData, wLen)

Returns internal movie data stored for the Movie Player instance. Since this function allows access to data structures used by the movie, improperly using the returned information can cause unexpected application errors or crash the Movie Player. Do not call this function while the movie is animating.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

int  nIndex

Specifies the type of data to be returned in the memory location pointed to by the lpData parameter. Use one of the following constants:

MMPINFO_LABELLIST

Return a handle to the label-list array. Function places a HANDLE to the array of MMPLABEL records in the memory location pointed to by lpData.

MMPINFO_LABELTEXT

Return a handle to the label-text block. Function places a HANDLE to the label-text block in the memory location pointed to by lpData.

MMPINFO_LABELCOUNT

Return the count of label entries. Function places a WORD-sized count value in the memory location pointed to by lpData.

MMPINFO_ACTIONLIST

Return a handle to the action-list array. The action list contains the script-channel commands for the movie. Function places a HANDLE to the array of MMPACTION records in the memory location pointed to by lpData.

MMPINFO_ACTIONTEXT

Return a handle to the action-text block. Function places a HANDLE to the action-text block in the memory location pointed to by lpData.

MMPINFO_ACTIONCOUNT

Return the count of action entries. Function places a WORD-sized count value in the memory location pointed to by lpData.

LPVOID  lpData

Specifies a far pointer to the memory area to receive the Movie Player instance data. The memory area pointed to by this parameter must be large enough to receive the requested data item.

WORD  wLen

Specifies the length of the memory location pointed to by the lpData parameter.

Return Value	Returns TRUE if successful; otherwise, returns FALSE.

Comments    	All handles returned by this function reference global memory objects.

For both the label and action-entry data, the three data items (label-list or action-list array, text block, and count value) are dependent on each other. When changing the label or action entry information, change all relevant data items as a single operation before yielding control. Use the mmpSetInfo command to change the memory handles or count values for the label list and action-text list.

See Also	mmpSetInfo


mmpGetMovieInfo

Syntax      	BOOL mmpGetMovieInfo(idMovie, lpInfo)

This function returns information about a movie file in memory.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

LPMMPMOVIEINFO  lpInfo

Points to an MMPMOVIEINFO structure to be filled with information about the specified movie file.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	This function fills out an MMPMOVIEINFO structure for the movie loaded into the specified Movie Player instance.

See Also	mmpGetFileInfo


mmpGetMute

Syntax      	BOOL mmpGetMute(idMovie)

This function returns TRUE if the Movie Player instance is set to disable sound playback.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns TRUE if sound playback is disabled, otherwise returns FALSE.

Comments    	The mute setting affects the playback of sound cast members. The mute setting does not affect "mci" or "mciWait" script-channel commands,including those used to play streamed audio resources.

See Also	mmpSetMute


mmpGetPaletteHandle

Syntax      	HPALETTE mmpGetPaletteHandle(idMovie)

This function returns a handle to the logical palette for the current frame.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns a handle to a logical palette if successful, otherwise returns NULL.


mmpGetRepeat

Syntax      	BOOL mmpGetRepeat(idMovie)

This function determines whether the Movie Player instance is set to repeat the movie.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns TRUE if repeat is on. Returns FALSE if repeat is off.

Comments    	If the repeat flag is set to TRUE, the Movie Player automatically rewinds and continues play after the last frame is shown.

See Also	mmpSetRepeat


mmpGetStage

Syntax      	BOOL mmpGetStage(idMovie, lphWndStage, lprectStage, wOptions)

This function returns information about the stage window for a given Movie Player instance.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

LPHWND  lphWndStage

Points to an HWND variable to be set to the handle of the stage window associated with the movie ID.

LPRECT  lprectStage

Points to a RECT structure to be set to the offset and extents of the playback area within the stage-window client area.

LPWORD  wOptions

Points to a WORD variable to be set to the stage options in effect for the Movie Player instance. For information on the stage options, refer to the description of the mmpSetStage function.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

See Also	mmpSetStage, mmpOpen


mmpGetTempo

Syntax      	short mmpGetTempo(idMovie)

This function returns the movie tempo in frames per second.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns the movie tempo in frames per second.

Comments    	The returned tempo value remains correct until the movie changes the frames-per-second rate in the tempo channel.

See Also	mmpSetTempo


mmpGoToFrame

Syntax      	BOOL mmpGoToFrame(idMovie, sNewFrame, wOptions)

This function jumps to a specified frame in the movie.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

short  sNewFrame

Identifies the number of the frame to jump to. Frames are numbered starting at 1. This parameter can take a frame number you specify or either of the following flags:

MMP_FRAME_FIRST

Jump to the first frame of the movie.

MMP_FRAME_LAST

Jump to the last frame of the movie.

WORD  wOptions

Specifies the following flags:

MMP_DRAW_FRAME

Draw the frame to the stage window.

Return Value	Returns TRUE if successful. Returns FALSE if an invalid frame number is passed to sNewFrame.

See Also	mmpGetCurFrame, mmpIsLastFrame


mmpIsLastFrame

Syntax      	BOOL mmpIsLastFrame(idMovie)

This function returns TRUE if the current frame index is the last frame of the movie.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns TRUE if the frame index is the last frame, otherwise returns FALSE.

See Also	mmpGetCurFrame


mmpLoadFile

Syntax      	BOOL mmpLoadFile(idMovie, lpszFileName, wOptions)

This function loads a movie file for playback and establishes playback options for the movie.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

LPSTR  lpszFileName

Specifies the name or file handle of an RMMP-format movie file.

To specify a movie filename, pass a far pointer to a character buffer containing the DOS filename of the movie file.

To specify a file handle, set the high-order word to zero and set the low-order word to the file handle of an open file. If you specify a file handle, the file pointer must point to the beginning of the RMMP chunk (at the first byte of the "RIFF" chunk ID).

WORD  wOptions

Specifies playback and load options. Use any combination of the following flags:

MMP_DRAW_FRAME

Draw the first frame to the stage window. By default,the Movie Player does not display the first frame.

MMP_ERASE_FRAME

Erase the stage window before loading the movie file.

MMP_LOAD_REFERENCED

Load only those cast members that are referenced in the score. Using this flag can reduce memory requirements for movie files containing unused cast members. Default setting is to load all cast members contained in the movie file.

MMP_LOAD_NOBUFFER

Create no off-screen buffer for imaging movie frames. Use this flag in low-memory situations. Default setting is to create the off-screen buffer. Some movies require the use of the off-screen buffer.

MMP_LOAD_NOSTATIC

Reduce the system colors to black and white, leaving up to 254 colors for Movie Player use. When the stage window is the active window in the system, the Windows color scheme switches to black and white. Default setting is to reserve the 20 system colors,leaving up to 236 colors for Movie Player use.

Return Value	Returns TRUE if operation successful, otherwise returns FALSE.

Comments    	If the Movie Player is playing a movie file when this function is called,it stops animation and frees the currently loaded file before attempting to load the new movie file.

System color scheme changes caused by calling mmpLoadFile with the MMP_LOAD_NOSTATIC flag are canceled when the movie file is unloaded, when the stage window is inactive, and when the stage window is closed.

See Also	mmpFreeFile, mmpFileLoaded


mmpOpen

Syntax      	MMPID mmpOpen(hAppInst, hWndStage, wOptions)

This function initializes a Movie Player instance.

Parameters  	HANDLE  hAppInst

Identifies the instance handle of the application opening the Movie Player. You can pass a NULL value to this parameter.

HWND  hWndStage

Specifies a handle to the window to be used as the stage window. If hWndStage is NULL, you must supply a stage window handle (using mmpSetStage) before starting animation.

WORD  wOptions

Not used.

Return Value	Returns a Movie Player instance identifier (movie ID) if successful. If the Movie Player fails to start an instance, the function returns NULL.

Comments    	Each instance of the Movie Player is identified by the unique movie ID returned from the call to mmpOpen. Most Movie Player calls require the movie ID returned by this function.

The Movie Player supports up to eight instances system-wide. A single application can play multiple movies simultaneously by opening multiple Movie Player instances and saving the movie ID for each instance.

If mmpOpen fails, you can call mmpErrorwith a NULL value for the movie ID to retrieve the last error that occurred.

See Also	mmpClose, mmpError, mmpSetStage


mmpRewind

Syntax      	BOOL mmpRewind(idMovie)

This function rewinds the movie, setting the current frame to frame number 1.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

See Also	mmpGoToFrame, mmpGetCurFrame, mmpIsLastFrame


mmpSetDC

Syntax      	BOOL mmpSetDC(idMovie, hDC)

This function sets a device context for a Movie Player instance,allowing the Movie Player to direct frame updates to a private or class device context.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

HDC  hDC

Identifies the handle to a device context to which the Movie Player instance will draw movie frames. To cancel the use of the alternate device context, pass a NULL value to this parameter.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	By default, the Movie Player obtains a handle to a device context with most operations. To improve performance, you can use the mmpSetDC function to specify a private or class device context to use when displaying movie frames. Be sure to register the playback window with the CS_CLASSDC or CS_OWNDC style flags.


mmpSetFrameHook

Syntax      	BOOL mmpSetFrameHook(idMovie, lpFrameHook)

This function hooks a callback function into the movie playback. The callback function is called after each frame update.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

LPMMPFRAMEHOOK  lpFrameHook

Specifies the procedure-instance address of the callback function. To remove your callback function, pass the original callback-function address (obtained using mmpGetFrameHook) to this parameter.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	The attached function is called after screen updates for each frame and subframe are concluded.

Callback	BOOL FAR PASCAL FrameHook(idMovie, wMsg, wParam, lParam)

FrameHook is a placeholder for the application-supplied function name. Export the actual name by including it in the EXPORTS statement in your module-definition file.

Parameters

MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

WORD  wMsg

Specifies a message indicating the reason for calling the frame-hook function. This message is either MMP_PROCESS_FRAMEor MMP_PROCESS_SCRIPT.

WORD  wParam

Specifies the frame index.

LONG  lParam

Specifies a parameter for the message.

Return Value

The return value depends on the message specified by wMsg.

Comments

Any Movie Player functions called from the callback function must be directed to the current Movie Player instance. Do not close the movie file or the Movie Player instance from the frame-hook function.

You should call any existing callback function at the end of your callback function. In this way, you can chain the frame-hook functions. Before hooking your callback function, use mmpGetFrameHook to obtain the address of the current callback function. If this value is not NULL, call the existing function at the end of your callback function.

To unhook your callback function,call mmpSetFrameHook and pass the original callback-function value (which may be NULL if no function was attached) to the lpFrameHook parameter.

See Also	mmpGetFrameHook, MMP_PROCESS_FRAME, MMP_PROCESS_SCRIPT


mmpSetInfo

Syntax      	BOOL mmpSetInfo(idMovie, nIndex, lpData, wLen)

Sets new values for internal movie data of the Movie Player instance. Since this function directly sets variables used by the movie, setting improper values can cause unexpected application errors or crash the Movie Player. Do not call this function while the movie is animating.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

int  nIndex

Specifies the type of data to provide to the Movie Player instance. Use one of the following constants:

MMPINFO_LABELLIST

Sets the handle to the label-list array. The lpData parameter must point to a HANDLE that references a global memory block containing an array of MMPLABELrecords. The label-list information must be compatible with the MMP label-text block. See the documentation on the MMPLABEL structure for information on the label-list format.

MMPINFO_LABELTEXT

Set the handle to the label text block. The lpData parameter must point to a HANDLE that references a global memory block containing a block of label text. The label text must be compatible with the MMP label-list information.

MMPINFO_LABELCOUNT

Set the count of label entries. The lpDataparameter must point to a WORD-sized count value.

MMPINFO_ACTIONLIST

Set the handle to the action-list array. The action list contains the script-channel commands for the movie. The lpData parameter must point to a HANDLE that references a global memory block containing an array of MMPACTIONrecords. The action-list information must be compatible with the MMP action-text block. See the documentation on the MMPACTION structure for information on the action-list format.

MMPINFO_ACTIONTEXT

Set the handle to the action-text block. The lpData parameter must point to a HANDLE that references a global memory block containing a block of action text. The action text must be compatible with the MMP action-list information.

MMPINFO_ACTIONCOUNT

Set the count of action entries. The lpDataparameter must point to a WORD-sized count value.

LPVOID  lpData

Specifies a far pointer to the data to supply to the Movie Player instance. The memory area pointed to by this parameter must be the correct size for the data item identified by the nIndex value.

WORD  wLen

Specifies the length of the memory location pointed to by the lpData parameter.

Return Value	Returns TRUE if successful; otherwise, returns FALSE.

Comments    	For both the label and action-entry data, the three data items (label-list or action-list array, text block, and count value) are dependent on each other. When changing the label or action entry information, change all relevant data items as a single operation before yielding control.

See Also	mmpGetInfo


mmpSetMute

Syntax      	BOOL mmpSetMute(idMovie, bMuteOn)

This function disables or enables any sound playback produced by the Movie Player instance. This setting is associated with the Movie Player instance, not with the movie; loading a new movie into the Movie Player instance does not change the mute setting.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

WORD  bMuteOn

Identifies whether to mute the sound. Set this to TRUE to turn off sound playback, or set it to FALSE to resume sound playback.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	The mute setting affects the playback of sound cast members. The mute setting does not affect "mci" or "mciWait" script-channel commands,including those used to play streamed audio resources.

See Also	mmpGetMute


mmpSetRepeat

Syntax      	BOOL mmpSetRepeat(idMovie, bRepeat)

This function tells the Movie Player instance whether to continuously repeat the movie.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

WORD  bRepeat

Indicates whether to automatically repeat the movie after the last frame. Set this to TRUE to repeat the movie or FALSE to turn off the automatic repeat.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	If the repeat flag is set to TRUE, the Movie Player automatically rewinds and continues play after the last frame is shown.

See Also	mmpGetRepeat


mmpSetStage

Syntax      	BOOL mmpSetStage(idMovie, hWndStage, lprectStage, wOptions)

This function provides the playback window, or stage window, for the Movie Player instance. It also specifies the position and size of the playback region within the window. It brings the stage window to the foreground and optionally updates the current frame.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

HWND  hWndStage

Identifies the handle to the window to associate with the Movie Player instance.

LPRECT  lprectStage

Points to a RECT structure specifying the origin and extents of the playback area within the stage window.

The top and left fields of the RECT contain the offset of the playback area within the stage-window client area, and the rightand bottom fields contain the extents.

If the movie as authored is larger than the specified extents, the playback area is clipped. If this parameter is NULL, the authored size of the movie is used.

WORD  wOptions

Specifies the following flags:

MMP_DRAW_FRAME

Draw the current frame to the stage window.

MMP_OFFSET_STAGE

Use the RECT structure pointed to by the lprectStage parameter to position and size the playback area.

MMP_CENTER_STAGE

Center the playback area in the window client area.

MMP_BORDER_STAGE

Draw a thin black border around the playback area. The border is visible only if there is sufficient room for it; use the MMP_CENTER_STAGE or MMP_OFFSET_STAGE flags to provide room for the border.

MMP_FIXED_STAGE

Fix the size and position of the movie playback area. When the window is resized, or when a new movie is loaded,the playback area remains fixed at either the size of the client area at the time mmpSetStage was called or, if the MMP_OFFSET_STAGE flag was specified, the offset and extents specified by the RECTvalues.

Return Value	Returns TRUE if operation successful, otherwise returns FALSE.

Comments    	You can use any pop-up or overlapped window for the stage window.

See Also	mmpGetStage, mmpOpen


mmpSetTempo

Syntax      	BOOL mmpSetTempo(idMovie, nTempo)

This function changes the tempo value for the Movie Player instance.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

int  nTempo

Specifies one of the following tempo values:

1 to 60

Specifies a new tempo rate of nTempo frames per second. The frames-per-second setting continues to the first change-tempo command encountered in the tempo channel.

-1 through -120

Specifies a delay value of -nTempo seconds for the current frame. The Movie Player waits -nTempo seconds before advancing to the next frame.

MMTEMPO_MOUSEWAIT

Specifies to wait at the current frame. The Movie Player pauses the animation until the stage window receives a mouse click or keystroke.

Return Value	Returns TRUE if successful, otherwise returns FALSE.

Comments    	If the tempo is locked, the mmpSetTempo command has no effect.

See Also	mmpGetTempo


mmpStartAnimating

Syntax      	BOOL mmpStartAnimating(idMovie, wOptions)

This function notifies the Movie Player instance that animation is to begin. Actual frame advance is handled by the mmpAnimate function.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

WORD  wOptions

Specifies the following flags:

MMP_DRAW_FRAME

Draw the current frame to the stage window.

Return Value	Returns TRUE if successful. Returns FALSE if the animation is already running.

See Also	mmpAnimate, mmpStopAnimating, mmpAnimStopped, mmpAnimStatus


mmpStopAnimating

Syntax      	BOOL mmpStopAnimating(idMovie, wOptions)

This function notifies the Movie Player that animation is to stop.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

WORD  wOptions

Specifies the following flags:

MMP_DRAW_FRAME

Draw the next frame in the stage window.

Return Value	Returns TRUE if successful. Returns FALSE if the animation is not running.

See Also	mmpStartAnimating, mmpAnimStopped, mmpAnimStatus


mmpUpdate

Syntax      	BOOL mmpUpdate(idMovie, hDC, lprectArea)

This function updates an invalid rectangle on the stage window, generally in response to a WM_PAINT message for the stage window.

Parameters  	MMPID  idMovie

Identifies the movie ID of the Movie Player instance.

HDC  hDC

Identifies the handle to the device context.

LPRECT  lprectArea

Points to a RECT data structure that contains the rectangle to be updated.

Return Value	Returns TRUE if successful, otherwise returns FALSE.


mmsystemGetVersion

Syntax      	WORD mmsystemGetVersion()

This function returns the current version number of the Multimedia extensions system software.

Return Value	The return value specifies the major and minor version numbers of the Multimedia extensions.  The high-order byte specifies the major version number.  The low-order byte specifies the minor version number.


OutputDebugStr

Syntax      	void OutputDebugStr(lpOutputString)

This function sends a debugging message directly to the COM1 port or to a secondary monochrome display adapter. Because it bypasses DOS, it can be called by low-level callback functions and other code at interrupt time.

Parameters  	LPSTR  lpOutputString

Specifies a far pointer to a null-terminated string.

Comments    	This function is available only in the debugging version of the Multimedia extensions. The DebugOutput keyname in the [mmsystem]section of SYSTEM.INI controls where the debugging information is sent. If DebugOutput is 0, all debug output is disabled. If DebugOutput is 1, debug output is sent to the COM1 port. If DebugOutput is 2, debug output is sent to a secondary monochrome display adapter.

To print the contents of a register, use the pound sign ("#") followed by one of the following register designations: "ax", "bx", "cx", "dx","si", "di", "bp", "sp", "al", "bl", "cl", "dl". For example, to print the stack pointer and accumulator registers, pass the following string to OutputDebugStr: "SP=#sp\r\nAX=#ax\r\n".


sndPlaySound

Syntax      	BOOL sndPlaySound(lpszSoundName, wFlags)

This function plays a waveform sound specified by a filename or by an entry in the [sounds] section of WIN.INI.  If the sound can't be found, it plays the default sound specified by the SystemDefault entry in the [sounds] section of WIN.INI. If there is no SystemDefault entry or if the default sound can't be found, the function makes no sound and returns FALSE.

Parameters  	LPSTR  lpszSoundName

Specifies the name of the sound to play. The function searches the [sounds] section of WIN.INI for an entry with this name and plays the associated waveform file. If no entry by this name exists, then it assumes the name is the name of a waveform file.

WORD  wFlags

Specifies options for playing the sound using one or more of the following flags:

SND_SYNC

The sound is played synchronously and the function does not return until the sound ends.

SND_ASYNC

The sound is played asynchronously and the function returns immediately after beginning the sound. To terminate an asynchronously-played sound, call sndPlaySound with lpszSoundName set to NULL.

SND_NODEFAULT

If the sound can't be found, the function returns silently without playing the default sound.

SND_MEMORY

The parameter specified by lpszSoundNamepoints to an in-memory image of a waveform sound.

SND_LOOP

The sound will continue to play repeatedly until sndPlaySound is called again with the lpszSoundName parameter set to NULL.  You must also specify the SND_ASYNC flag to loop sounds.

SND_NOSTOP

If a sound is currently playing, the function will immediately return FALSE without playing the requested sound.

Return Value	Returns TRUE if the sound is played, otherwise returns FALSE.

Comments    	The sound must fit in available physical memory and be playable by an installed waveform audio device driver. The directories searched for sound files are, in order: the current directory;the Windows directory; the Windows system directory; the directories listed in the PATH environment variable; the list of directories mapped in a network. See the Windows OpenFile function for more information about the directory search order.

If you specify the SND_MEMORY flag, lpszSoundName must point to an in-memory image of a waveform sound. If the sound is stored as a resource, use LoadResource and LockResource to load and lock the resource and get a pointer to it. If the sound is not a resource, you must use GlobalAlloc with the GMEM_MOVEABLE and GMEM_SHARE flags set and then GlobalLock to allocate and lock memory for the sound.

See Also	MessageBeep


timeBeginPeriod

Syntax      	WORD timeBeginPeriod(wPeriod)

This function sets the minimum (lowest number of milliseconds) timer resolution that an application or driver is going to use. Applications (and drivers) should call this API immediately before starting to use timer event services and should call timeEndPeriod as soon as they have finished using timer event services.

You must match calls to timeBeginPeriod with calls to timeEndPeriod.

Parameters  	WORD  wPeriod

Minimum period (between 1 and 55 ms.)

See Also	timeEndPeriod


timeEndPeriod

Syntax      	WORD timeEndPeriod(wPeriod)

This function clears a previously set minimum (lowestnumber of milliseconds) timer resolution that an application or driver is going to use. Applications (and drivers)should call this API immediately after using timer event services.

You must match calls to timeBeginPeriod with calls to timeEndPeriod.

Parameters  	WORD  wPeriod

Minimum period (between 1 and 55 ms.)

See Also	timeBeginPeriod


timeGetDevCaps

Syntax      	WORD timeGetDevCaps(lpTimeCaps, wSize)

This function queries the timer device to determine its capabilities.

Parameters  	LPTIMECAPS  lpTimeCaps

Specifies a far pointer to a TIMECAPS structure.  This structure is filled with information about the capabilities of the timer device.

WORD  wSize

Specifies the size of the TIMECAPS structure.

Return Value	Returns zero if successful.  Otherwise, returns an error number.


timeGetSystemTime

Syntax      	WORD timeGetSystemTime(lpTime, wSize)

This function retrieves the system time in milliseconds.  The system time is the time elapsed since multimedia Windows was started.

Parameters  	LPMMTIME  lpTime

Specifies a far pointer to an MMTIME data structure.

WORD  wSize

Specifies the size of the MMTIME structure.

Return Value	Returns zero if successful.  Otherwise, returns an error number. The system time is returned in the ms field of the MMTIMEstructure.

Comments    	The time is always returned in milliseconds.

See Also	timeGetTime


timeGetTime

Syntax      	DWORD timeGetTime()

This function retrieves the system time in milliseconds.  The system time is the time elapsed since multimedia Windows was started.

Return Value	The return value is the system time in milliseconds.

Comments    	The only difference between this function and the timeGetSystemTime function is timeGetSystemTimeuses the standard multimedia time structure MMTIME to return the system time.  This function has less overhead than timeGetSystemTime.

See Also	timeGetSystemTime


timeKillEvent

Syntax      	WORD timeKillEvent(wID)

This functions destroys a specified timer callback event.

Parameters  	WORD  wID

Identifies the event to be destroyed.

Return Value	Returns zero if successful.  Otherwise, returns an error number.

Comments    	The timer event ID specified by wID must be an ID returned by timeSetEvent.

See Also	timeSetEvent


timeSetEvent

Syntax      	WORD timeSetEvent(wDelay, wResolution, lpFunction, dwUser, wFlags)

This function sets up a timed callback event. The event can be a one-time event or a periodic event.  Once activated,the event calls the specified callback function.

Parameters  	WORD  wDelay

Specifies the event period in milliseconds. If the delay is less than the minimum period supported by the timer,then timeSetEvent creates a timer with the minimum period.

WORD  wResolution

Specifies the accuracy of the delay in milliseconds. The resolution of the timer event increases with smaller wResolution values. To reduce system overhead, use the maximum wResolution value appropriate for your application.

LPTIMECALLBACK  lpFunction

Specifies the procedure address of a callback function that is called once upon expiration of a one-shot event or periodically upon expiration of periodic events.

DWORD  dwUser

Contains user-supplied callback data.

WORD  wFlags

Specifies the type of timer event, using one of the following flags:

TIME_ONESHOT

Event occurs once, after wPeriod milliseconds.

TIME_PERIODIC

Event occurs every wPeriod milliseconds.

Return Value	Returns an ID code that identifies the timer event. Returns NULL if the timer event was not created.  The ID code is also passed to the callback function.

Comments    	Using this function to generate a high-frequency periodic-delay event (with a period less than 100 milliseconds) will consume a significant portion of the system CPU bandwidth.  Any call to timeSetEvent for a periodic-delay timer must be paired with a call to timeKillEvent.

The callback function must reside in a DLL.  You don't have to use MakeProcInstance to get a procedure-instance address for the callback function.

Callback	void FAR PASCAL TimeFunc(wID, wMsg, dwUser, dw1, dw2)

TimeFunc is a placeholder for the application-supplied function name.  The actual name must be exported by including it in the EXPORTS statement of the module-definition file for the DLL.

Parameters

WORD  wID

The ID of the timer event.  This is the ID returned by timeSetEvent.

WORD  wMsg

Not used.

DWORD  dwUser

User instance data supplied to the dwUserparameter of timeSetEvent.

DWORD  dw1

Not used.

DWORD  dw2

Not used.

Comments

Because the callback is accessed at interrupt time, it must reside in a DLL, and its code segment must be specified as FIXED in the module-definition file for the DLL.  Any data that the callback accesses must be in a FIXED data segment as well. The callback may not make any system calls except for PostMessage,timeGetSystemTime, timeGetTime, midiOutShortMsg,midiOutLongMsg, and OutputDebugStr.

See Also	timeKillEvent


waveInAddBuffer

Syntax      	WORD waveInAddBuffer(hWaveIn, lpWaveInHdr, wSize)

This function sends an input buffer to a waveform input device.  When the buffer is filled, it is sent back to the application.

Parameters  	HWAVEIN  hWaveIn

Specifies a handle to the waveform device which receives the buffer.

LPWAVEHDR  lpWaveInHdr

Specifies a far pointer to a WAVEHDRstructure that identifies the buffer.

WORD  wSize

€b
€
¬i�€
ã•àS‰‚ÿ
Specifies the size of the


waveInGetErrorText

Syntax      	WORD waveInGetErrorText(wError, lpText, wSize)

This function retrieves a textual description of the error identified by the specified error number.

Parameters  	WORD  wError

Specifies the error number.

LPSTR  lpText

Specifies a far pointer to the buffer which is filled with the textual error description.

WORD  wSize

Specifies the size of the buffer pointed to by lpText.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADERRNUM

Specified error number is out of range.

Comments    	If the textual error description is longer than the specified buffer,the description is truncated.  The returned error string is always null-terminated. If wSize is 0, nothing is copied and MMSYSERR_NOERROR is returned.  All error descriptions are less than 80 characters long.


waveInGetNumDevs

Syntax      	WORD waveInGetNumDevs()

This function returns the number of waveform input devices.

Return Value	Returns the number of waveform input devices present in the system.

See Also	waveInGetDevCaps


waveInGetPosition

Syntax      	WORD waveInGetPosition(hWaveIn, lpInfo, wSize)

This function retrieves the current input position of the specified waveform input device.

Parameters  	HWAVEIN  hWaveIn

Specifies a handle to the waveform input device that is being queried.

LPMMTIME  lpInfo

Specifies a far pointer to an MMTIMEstructure.

WORD  wSize

Specifies the size of the MMTIME structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	Before calling waveInGetPosition, set the wType field of the MMTIME structure to indicate the time format that you desire.  After calling waveInGetPosition, be sure to check the wType field to determine if the desired time format is supported.  If the desired format is not supported, wType will speciy an alternative format.


waveInOpen

Syntax      	WORD waveInOpen(lphWaveIn, wDeviceID, lpFormat, dwCallback, dwCallbackInstance, dwFlags)

This function opens a specified waveform input device for recording.

Parameters  	LPHWAVEIN  lphWaveIn

Specifies a far pointer to a HWAVEIN handle.  This location is filled with a handle identifying the opened waveform input device.  Use this handle to identify the device when calling other waveform input functions.  This parameter may be NULL if the WAVE_FORMAT_QUERY flag is specified for dwFlags.

WORD  wDeviceID

Identifies the waveform input device to open.

WAVE_MAPPER

If this flag is specified, the function will select the best waveform input device in the system that is capable of recording in the given format.

LPWAVEFORMAT  lpFormat

Specifies a pointer to a WAVEFORMATdata structure that identifies the desired format for recording waveform data.

DWORD  dwCallback

Specifies the address of a callback function or a handle to a window that is called during waveform recording to process messages related to the progress of recording.

DWORD  dwCallbackInstance

Specifies 32 bits of user instance data that is passed to the callback.  This parameter is not used with window callbacks.

DWORD  dwFlags

Specifies flags for opening the device.

WAVE_FORMAT_QUERY

If this flag is specified, the device will determine if it supports the given format, but will not actually open the device.

CALLBACK_WINDOW

If this flag is specified, dwCallback is assumed to be a window handle.

CALLBACK_FUNCTION

If this flag is specified, dwCallback is assumed to be a callback procedure address.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device id is out of range.

MMSYSERR_ALLOCATED

Specified resource is already allocated.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

WAVERR_BADFORMAT

Attempted to open with an unsupported wave format.

Comments    	Use waveInGetNumDevs to determine the number of waveform input devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.

If a window is chosen to receive callback information, the following messages are sent to the window procedure function to indicate the progress of waveform input:  MM_WIM_OPEN, MM_WIM_CLOSE,MM_WIM_DATA

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of waveform input: WIM_OPEN, WIM_CLOSE, WIM_DATA.  The callback function must reside in a DLL.  You do not have to use MakeProcInstance to get a procedure-instance address for the callback function.

Callback	void FAR PASCAL WaveInFunc(hWaveIn, wMsg, dwInstance, dwParam1, dwParam2)

WaveInFunc is a placeholder for the application-supplied function name.  The actual name must be exported by including it in an EXPORTS statement in the DLL's module-definition file.

Parameters

HWAVEIN  hWaveIn

Specifies a handle to the waveform device associated with the callback.

WORD  wMsg

Specifies a waveform input device.

DWORD  dwInstance

Specifies the 32 bits of user instance data specified with waveInOpen.

DWORD  dwParam1

Specifies a parameter for the message.

DWORD  dwParam2

Specifies a parameter for the message.

Comments

Because the callback is accessed at interrupt time, it must reside in a DLL and its code segment must be specified as FIXED in the module-definition file for the DLL.  Any data that the callback accesses must be in a FIXED data segment as well.  The callback may not make any system calls except for PostMessage, timeGetSystemTime,timeGetTime, and OutputDebugStr.

See Also	waveInClose


waveInPrepareHeader

Syntax      	WORD waveInPrepareHeader(hWaveIn, lpWaveInHdr, wSize)

This function prepares a buffer for waveform input.

Parameters  	HWAVEIN  hWaveIn

Specifies a handle to the waveform input device that the buffer will be sent to.

LPWAVEHDR  lpWaveInHdr

Specifies a pointer to a WAVEHDR structure that identifies the data buffer to be prepared.

WORD  wSize

Specifies the size of the WAVEHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

Comments    	The WAVEHDR data structure and the data block pointed to by its lpData field must be allocated with GlobalAlloc using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with GlobalLock. Preparing a header that has already been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveInUnprepareHeader


waveInReset

Syntax      	WORD waveInReset(hWaveIn)

This function stops input on a given waveform input device and resets the current position to 0.  All pending buffers are marked as done and returned to the application.

Parameters  	HWAVEIN  hWaveIn

Specifies a handle to the waveform input device that is to be reset.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

See Also	waveInStart, waveInStop, waveInAddBuffer, waveInClose


waveInStart

Syntax      	WORD waveInStart(hWaveIn)

This function starts input on a specified waveform input device.

Parameters  	HWAVEIN  hWaveIn

Specifies a handle to the waveform input device to be started.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	Buffers are returned to the client when full or when waveInResetis called (the dwBytesRecorded field in the header will contain the actual length of data). If there are no buffers in the queue, the data is thrown away without notification to the client and input will continue. Calling this function when input is already started will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveInStop, waveInReset


waveInStop

Syntax      	WORD waveInStop(hWaveIn)

This function stops waveform input.

Parameters  	HWAVEIN  hWaveIn

Specifies a handle to the waveform input device to be stopped.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	If there are any buffers in the queue, the current buffer will be marked as done (the dwBytesRecorded field in the header will contain the actual length of data), but any empty buffers in the queue will remain there.  Calling this function when input is not started will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveInStart, waveInReset


waveInUnprepareHeader

Syntax      	WORD waveInUnprepareHeader(hWaveIn, lpWaveInHdr, wSize)

This function is the complementary function to waveInPrepareHeader.  It must be called after the device driver has filled a data buffer and returned it to the application to clean up the preparation done by waveInPrepareHeader.

Parameters  	HWAVEIN  hWaveIn

Specifies a handle to the waveform input device that buffer was sent to.

LPWAVEHDR  lpWaveInHdr

Specifies a pointer to a WAVEHDRstructure identifying the data buffer that is to be cleaned up.

WORD  wSize

Specifies the size of the WAVEHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

WAVERR_STILLPLAYING

lpWaveInHdr is still in the queue.

Comments    	This function must be called before a data buffer can be freed. After passing a buffer to the device driver with waveInAddBuffer, you must wait until the driver is finished with the buffer before calling waveInUnprepareHeader.  Unpreparing a buffer that has not been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveInPrepareHeader


waveOutBreakLoop

Syntax      	WORD waveOutBreakLoop(hWaveOut)

This function breaks a loop on a given waveform output device and allows playback to continue with the next block in the driver list.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device to receive the command.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	Waveform looping is controlled by the dwLoops and dwFlags fields in the WAVEHDR structures passed to the device with waveOutWrite.  Use the WHDR_BEGINLOOP and WHDR_ENDLOOP flags in the dwFlags field to specify the beginning and ending data blocks for looping.  To loop on a single block, specify both flags for the same block.  Use the dwLoops field in the WAVEHDRstructure for the first block in the loop to specify the number of loops. Calling this function when the nothing is playing or looping will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveOutWrite, waveOutPause, waveOutRestart


waveOutClose

Syntax      	WORD waveOutClose(hWaveOut)

This function closes the specified waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device to be closed.  If the function is successful, the handle is no longer valid after this call.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

WAVERR_STILLPLAYING

There are still buffers in the queue.

Comments    	If the device is still playing a waveform, the close operation will fail.  Use waveOutReset to terminate waveform playback before calling waveOutClose.

See Also	waveOutOpen, waveOutReset


waveOutGetDevCaps

Syntax      	WORD waveOutGetDevCaps(wDeviceID, lpCaps, wSize)

This function queries a specified waveform device to determine its capabilities.

Parameters  	WORD  wDeviceID

Identifies the waveform output device to be queried.

LPWAVEOUTCAPS  lpCaps

Specifies a far pointer to a WAVEOUTCAPSstructure.  This structure is filled with information about the capabilities of the device.

WORD  wSize

Specifies the size of the WAVEOUTCAPS structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device id is out of range.

Comments    	Use waveOutGetNumDevs to determine the number of waveform output devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.  Only wSize bytes (or less) of information will be copied to the location pointed to by lpCaps.  If wSize is 0, nothing will be copied and MMSYSERR_NOERROR is returned.

See Also	waveOutGetNumDevs


waveOutGetErrorText

Syntax      	WORD waveOutGetErrorText(wError, lpText, wSize)

This function retrieves a textual description of the error identified by the specified error number.

Parameters  	WORD  wError

Specifies the error number.

LPSTR  lpText

Specifies a far pointer to a buffer which is filled with the textual error description.

WORD  wSize

Specifies the length of the buffer pointed to by lpText.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADERRNUM

Specified error number is out of range.

Comments    	If the textual error description is longer than the specified buffer,the description is truncated.  The returned error string is always null-terminated. If wSize is 0, nothing is copied and MMSYSERR_NOERROR is returned.  All error descriptions are less than 80 characters long.


waveOutGetNumDevs

Syntax      	WORD waveOutGetNumDevs()

This function retrieves the number of waveform output devices present in the system.

Return Value	Returns the number of waveform output devices present in the system.

See Also	waveOutGetDevCaps


waveOutGetPitch

Syntax      	WORD waveOutGetPitch(hWaveOut, lpdwPitch)

This function queries the the current pitch setting of a waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device that is being queried.

LPDWORD  lpdwPitch

Specifies a far pointer to a location that will be filled with the current pitch setting.  The pitch is specified as a fixed point value.  The high-order word of the DWORD location contains the integer part of the number and the low-order word contains the fractional part.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

Comments    	Changing the pitch does not change the playback rate or the sample rate.  The playback time is also unchanged.  Not all devices support volume changes.  Use the WAVECAPS_PITCH flag to test the dwSupportfield of the WAVEOUTCAPS structure filled by waveOutGetDevCapsto see if the device supports pitch control.

See Also	waveOutSetPitch, waveOutGetPlaybackRate, waveOutSetPlaybackRate


waveOutGetPlaybackRate

Syntax      	WORD waveOutGetPlaybackRate(hWaveOut, lpdwRate)

This function queries the current playback rate setting of a waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device that is being queried.

LPDWORD  lpdwRate

Specifies a far pointer to a location that will be filled with the current playback rate.  The rate is specified as a fixed point value.  The high-order word of the DWORD location contains the integer part of the number and the low-order word contains the fractional part.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

Comments    	Changing the playback rate does not change the sample rate but will change the playback time.  Not all devices support playback rate changes. Use the WAVECAPS_PLAYBACKRATE flag to test the dwSupport field of the WAVEOUTCAPS structure filled by waveOutGetDevCaps to see if the device supports playback rate changes.

See Also	waveOutSetPlaybackRate, waveOutSetPitch, waveOutGetPitch


waveOutGetPosition

Syntax      	WORD waveOutGetPosition(hWaveOut, lpInfo, wSize)

This function retrieves the current playback position of the specified waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device that is being queried.

LPMMTIME  lpInfo

Specifies a far pointer to an MMTIMEstructure.

WORD  wSize

Specifies the size of the MMTIME structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	Before calling waveOutGetPosition, set the wType field of the MMTIME structure to indicate the time format that you desire.  After calling waveOutGetPosition, be sure to check the wType field to determine if the desired time format is supported.  If the desired format is not supported, wType will specify an alternative format.


waveOutGetVolume

Syntax      	WORD waveOutGetVolume(wDeviceID, lpdwVolume)

This function queries the current volume setting of a waveform output device.

Parameters  	WORD  wDeviceID

Identifies the waveform output device to be queried.

LPDWORD  lpdwVolume

Specifies a far pointr to a location that will be filled with the current volume setting.  The high-order word of this location contains the left channel volume setting and the low-order word contains the right channel setting.  A value of 0xFFFF represents full volume and a value of 0x0000 is silence.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

Comments    	Not all devices support volume changes.  Use the WAVECAPS_VOLUME flag to test the dwSupport field of the WAVEOUTCAPS structure filled by waveOutGetDevCaps to see if the device supports volume control.  Use the WAVECAPS_LRVOLUME flag to test if the device supports volume control on both the left and right channels.  If a device does not support both left and right volume control, only the right channel value is valid.

See Also	waveOutSetVolume


waveOutOpen

Syntax      	WORD waveOutOpen(lphWaveOut, wDeviceID, lpFormat, dwCallback, dwCallbackInstance, dwFlags)

This function opens a specified waveform output device for playback.

Parameters  	LPHWAVEOUT  lphWaveOut

Specifies a far pointer to an HWAVEOUT handle.  This location is filled with a handle identifying the opened waveform output device.  Use the handle to identify the device when calling other waveform output functions.  This parameter may be NULL if the WAVE_FORMAT_QUERY flag is specified for dwFlags.

WORD  wDeviceID

Identifies the waveform output device to open.

WAVE_MAPPER

If this flag is specified, the function will select the best waveform output device in the system that is capable of playing the given format.

LPWAVEFORMAT  lpFormat

Specifies a pointer to a WAVEFORMATstructure that idenfifies the format of the waveform data that will be sent to the waveform output device.

DWORD  dwCallback

Specifies the address of a callback function or a handle to a window that is called during waveform playback to process messages related to the progress of the playback. Specify NULL for this parameter if no callback is desired.

DWORD  dwCallbackInstance

Specifies 32 bits of user instance data that is passed to the callback.  This parameter is not used with window callbacks.

DWORD  dwFlags

Specifies flags for opening the device.

WAVE_FORMAT_QUERY

If this flag is specified, the device driver will determine if it supports the given format, but will not actually open the device.

CALLBACK_WINDOW

If this flag is specified, dwCallback is assumed to be a window handle.

CALLBACK_FUNCTION

If this flag is specified, dwCallback is assumed to be a callback procedure address.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_BADDEVICEID

Specified device id is out of range.

MMSYSERR_ALLOCATED

Specified resource is already allocated.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

WAVERR_BADFORMAT

Attempted to open with an unsupported wave format.

Comments    	Use waveOutGetNumDevs to determine the number of waveform output devices present in the system.  The device ID specified by wDeviceID varies from zero to one less than the number of devices present.

The WAVEFORMAT structure pointed to by lpFormat may be extended to include type-specific information for certain data formats. For example, for PCM data, an extra WORD is added to specify the number of bits per sample.  Use the PCMWAVEFORMAT structure in this case.

If a window is chosen to receive callback information, the following messages are sent to the window procedure function to indicate the progress of waveform output:  MM_WOM_OPEN, MM_WOM_CLOSE,MM_WOM_DONE

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of waveform output: WOM_OPEN, WOM_CLOSE, WOM_DONE.  The callback function must reside in a DLL.  You do not have to use MakeProcInstance to get a procedure-instance address for the callback function.

Callback	void FAR PASCAL WaveOutFunc(hWaveOut, wMsg, dwInstance, dwParam1, dwParam2)

WaveOutFunc is a placeholder for the application-supplied function name.  The actual name must be exported by including it in an EXPORTS statement in the DLL's module-definition file.

Parameters

HWAVEOUT  hWaveOut

Specifies a handle to the waveform device associated with the callback.

WORD  wMsg

Specifies a waveform output message.

DWORD  dwInstance

Specifies the 32 bits of user instance data specified with waveOutOpen.

DWORD  dwParam1

Specifies a parameter for the message.

DWORD  dwParam2

Specifies a parameter for the message.

Comments

Because the callback is accessed at interrupt time, it must reside in a DLL and its code segment must be specified as FIXED in the module-definition file for the DLL.  Any data that the callback accesses must be in a FIXED data segment as well.  The callback may not make any system calls except for PostMessage, timeGetSystemTime,timeGetTime, and OutputDebugStr.

See Also	waveOutClose, PCMWAVEFORMAT


waveOutPause

Syntax      	WORD waveOutPause(hWaveOut)

This function pauses playback on a specified waveform output device.  The current playback position is saved.  Use waveOutRestart to resume playback from the current playback position.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device to be paused.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	Calling this function when the output is already paused will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveOutRestart, waveOutBreakLoop


waveOutPrepareHeader

Syntax      	WORD waveOutPrepareHeader(hWaveOut, lpWaveOutHdr, wSize)

This function prepares a waveform data block for playback.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device that the data block will be sent to.

LPWAVEHDR  lpWaveOutHdr

Specifies a pointer to a WAVEHDR structure that idenfifies the data block to be prepared.

WORD  wSize

Specifies the size of the WAVEHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

Comments    	The WAVEHDR data structure and the data block pointed to by its lpData field must be allocated with GlobalAlloc using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with GlobalLock. Preparing a header that has already been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveOutUnprepareHeader


waveOutReset

Syntax      	WORD waveOutReset(hWaveOut)

This function stops playback on a given waveform output device and resets the current position to 0.  All pending playback buffers are marked as done and returned to the application.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device that is to be reset.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

See Also	waveOutWrite, waveOutClose


waveOutRestart

Syntax      	WORD waveOutRestart(hWaveOut)

This function restarts a paused waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device that is to be restarted.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

Comments    	Calling this function when the output is not paused will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveOutPause, waveOutBreakLoop


waveOutSetPitch

Syntax      	WORD waveOutSetPitch(hWaveOut, dwPitch)

This function sets the pitch of a waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device.

DWORD  dwPitch

Specifies the new pitch setting.  The pitch is specified as a fixed point value.  The high-order word contains the integer part of the number and the low-order word contains the fractional part.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

Comments    	Changing the pitch does not change the playback rate or the sample rate.  The playback time is also unchanged.  Not all devices support volume changes.  Use the WAVECAPS_PITCH flag to test the dwSupportfield of the WAVEOUTCAPS structure filled by waveOutGetDevCapsto see if the device supports pitch control.

See Also	waveOutGetPitch, waveOutSetPlaybackRate, waveOutGetPlaybackRate


waveOutSetPlaybackRate

Syntax      	WORD waveOutSetPlaybackRate(hWaveOut, dwRate)

This function sets the playback rate of a waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device.

DWORD  dwRate

Specifies the new playback rate setting. The rate is specified as a fixed point value.  The high-order word contains the integer part of the nuber and the low-order word contains the fractional part.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

Comments    	Changing the playback rate does not change the sample rate but will change the playback time.  Not all devices support playback rate changes. Use the WAVECAPS_PLAYBACKRATE flag to test the dwSupport field of the WAVEOUTCAPS structure filled by waveOutGetDevCaps to see if the device supports playback rate changes.

See Also	waveOutGetPlaybackRate, waveOutSetPitch, waveOutGetPitch


waveOutSetVolume

Syntax      	WORD waveOutSetVolume(wDeviceID, dwVolume)

This function sets the volume of a waveform output device.

Parameters  	WORD  wDeviceID

Identifies the waveform output device to be queried.

DWORD  dwVolume

Specifies the new volume setting.  The high-order word contains the left channel volume setting and the low-order word contains the right channel setting.  A value of 0xFFFF represents full volume and a value of 0x0000 is silence.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

Comments    	Not all devices support volume changes.  Use the WAVECAPS_VOLUME flag to test the dwSupport field of the WAVEOUTCAPS structure filled by waveOutGetDevCaps to see if the device supports volume control.  Use the WAVECAPS_LRVOLUME flag to test if the device supports volume control on both the left and right channels.  If a device does not support both left and right volume control, only the right channel value is used.

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also	waveOutGetVolume


waveOutUnprepareHeader

Syntax      	WORD waveOutUnprepareHeader(hWaveOut, lpWaveOutHdr, wSize)

This function is the complementary function to waveOutPrepareHeader.  It must be called after the device driver is finished with a data block to clean up the preparation done by waveOutPrepareHeader.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform output device that played the data block.

LPWAVEHDR  lpWaveOutHdr

Specifies a pointer to a WAVEHDRstructure identifying the data block that is to be cleaned up.

WORD  wSize

Specifies the size of the WAVEHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

WAVERR_STILLPLAYING

lpWaveOutHdr is still in the queue.

Comments    	This function must be called before a data buffer can be freed. After passing a buffer to the device driver with waveOutWrite, you must wait until the driver is finished with the buffer before calling waveOutUnprepareHeader.  Unpreparing a buffer that has not been prepared will have no effect and MMSYSERR_NOERROR will be returned.

See Also	waveOutPrepareHeader


waveOutWrite

Syntax      	WORD waveOutWrite(hWaveOut, lpWaveOutHdr, wSize)

This function sends a data block to the specified waveform output device.

Parameters  	HWAVEOUT  hWaveOut

Specifies a handle to the waveform device that the data is to be sent to.

LPWAVEHDR  lpWaveOutHdr

Specifies a far pointer to a WAVEHDRstructure containing information about the data block.

WORD  wSize

Specifies the size of the WAVEHDR structure.

Return Value	Returns zero if the function was successful.  Otherwise, it returns an error number.  Possible error returns are:

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

WAVERR_UNPREPARED

lpWaveOutHdr hasn't been prepared.

Comments    	The data buffer must be prepared with waveOutPrepareHeader before it is passed to waveOutWrite.  The WAVEHDR data structure and the data buffer pointed to by its lpData field must be allocated with GlobalAlloc using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with GlobalLock.  Unless the device is paused by calling waveOutPause, playback begins when the first data block is sent to the device.

See Also	waveOutPrepareHeader, waveOutPause, waveOutReset, waveOutRestart


AUXCAPS

The AUXCAPS structure describes the capabilities of an auxiliary output device.

typedef struct auxcaps_tag {

    WORD wMid;

    WORD wPid;

    VERSION vDriverVersion;

    char szPname[MAXPNAMELEN];

    WORD wTechnology;

    DWORD dwSupport;

} AUXCAPS;

Fields      	The AUXCAPS structure contains the following fields:

wMid

Specifies a manufacturer ID for the device driver for the auxiliary audio device.  Currently defined IDs are:

MM_MICROSOFT

Drivers developed by Microsoft Corporation.

wPid

Specifies a product ID for the auxiliary audio device. Currently, no product IDs are defined for auxiliary audio devices.

vDriverVersion

Specifies the version number of the device driver for the auxiliary audio device.  The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname[MAXPNAMELEN]

Specifies the product name in a NULL-terminated string.

wTechnology

Describes the type of the auxiliary audio output according to one of the following flags:

AUXCAPS_CDAUDIO

Audio output from an internal CD-ROM drive.

AUXCAPS_AUXIN

Audio output from auxiliary input jacks.

dwSupport

Describes optional functionality supported by the auxiliary audio device.

AUXCAPS_VOLUME

Supports volume control.

AUXCAPS_LRVOLUME

Supports separate left and right volume control.

Comments    	If a device supports volume changes, the AUXCAPS_VOLUME flag will be set for the dwSupport field.  If a device supports separate volume changes on the left and right channels, both the AUXCAPS_VOLUME and the AUXCAPS_LRVOLUME flags will be set for this field.


JOYCAPS

Structure for storing joystick capability information.

typedef struct joyinfo_tag {

    WORD wMid;

    WORD wPid;

    char szPname[MAXPNAMELEN];

    WORD wXmin;

    WORD wXmax;

    WORD wYmin;

    WORD wYmax;

    WORD wZmin;

    WORD wZmax;

    WORD wNumButtons;

    WORD wPeriodMin;

    WORD wPeriodMax;

} JOYCAPS;

Fields      	The JOYCAPS structure contains the following fields:

wMid

Specifies the manufacturer ID of the joystick.

wPid

Specifies the product identification of the joystick.

szPname[MAXPNAMELEN]

Specifies the product name of the joystick, stored as a NULL terminated string.

wXmin

Specifies the minimum x position value of the joystick.

wXmax

Specifies the maximum x position value of the joystick.

wYmin

Specifies the minimum y position value of the joystick.

wYmax

Specifies the maximum y position value of the joystick.

wZmin

Specifies the minimum z position value of the joystick.

wZmax

Specifies the maximum z position value of the joystick.

wNumButtons

Specifies the number of buttons on the joystick.

wPeriodMin

Specifies the smallest polling interval supported when captured by joySetCapture.

wPeriodMax

Specifies the largest polling interval supported when captured by joySetCapture.


JOYINFO

Structure for storing joystick position and button state information.

typedef struct joyinfo_tag {

    WORD wXpos;

    WORD wYpos;

    WORD wZpos;

    WORD wButtons;

} JOYINFO;

Fields      	The JOYINFO structure contains the following fields:

wXpos

Specifies the current x-position of joystick.

wYpos

Specifies the current y-position of joystick.

wZpos

Specifies the current z-position of joystick.

wButtons

Specifies the current state of joystick buttons. It can be any combination of the following bit flags:

JOY_BUTTON1

Set if button 1 is pressed.

JOY_BUTTON2

Set if button 2 is pressed.

JOY_BUTTON3

Set if button 3 is pressed.

JOY_BUTTON4

Set if button 4 is pressed.


MCI_ANIM_OPEN_PARMS

The MCI_ANIM_OPEN_PARMSstructure contains information for MCI_OPEN message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    WORD wDeviceID;

    WORD wReserved0;

    LPSTR lpstrDeviceType;

    LPSTR lpstrElementName;

    LPSTR lpstrAlias;

    DWORD dwStyle;

    WORD hWndParent;

    WORD wReserved1;

} MCI_ANIM_OPEN_PARMS;

Fields      	The MCI_ANIM_OPEN_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

wDeviceID

Specifies the device ID returned to user.

wReserved0

Reserved field.

lpstrDeviceType

Specifies the name or constant ID of the device type.

lpstrElementName

Specifies the device element name (usually a pathname) or NULL.

lpstrAlias

Specifies an optional device alias.

dwStyle

Specifies the window style.

hWndParent

Specifies the handle to use as the window parent.

wReserved1

Reserved.


MCI_ANIM_PLAY_PARMS

The MCI_ANIM_PLAY_PARMS structure contains parameters for the MCI_PLAY message for animation devices. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommandto validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    DWORD dwSpeed;

} MCI_ANIM_PLAY_PARMS;

Fields      	The MCI_ANIM_PLAY_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwFrom

Specifies the position to play from.

dwTo

Specifies the position to play to.

dwSpeed

Specifies the play rate in frames per second.

See Also	MCI_PLAY


MCI_ANIM_RECT_PARMS

The MCI_ANIM_RECT_PARMS structure contains parameters for the MCI_PUT and MCI_WHERE messages for animation devices. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlagsparameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    RECT rc;

} MCI_ANIM_RECT_PARMS;

Fields      	The MCI_ANIM_RECT_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

rc

Specifies a rectangle.

See Also	MCI_PUT, MCI_WHERE


MCI_ANIM_SET_PARMS

The MCI_ANIM_SET_PARMS structure contains parameters for the MCI_SET message for movie and graphics devices. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

} MCI_ANIM_SET_PARMS;

Fields      	The MCI_ANIM_SET_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwTimeFormat

Specifies the time format used by the animation device.

dwAudio

Specifies the audio output channel.

See Also	MCI_SET


MCI_ANIM_STEP_PARMS

The MCI_ANIM_STEP_PARMS structure contains parameters for the MCI_STEP message for movie and graphic devices. When assigning data the fields in this data structure, set the corresponding MCI flags in the dwFlagsparameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrames;

} MCI_ANIM_STEP_PARMS;

Fields      	The MCI_ANIM_STEP_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwFrames

Specifies the number of frames to step.

See Also	MCI_STEP


MCI_ANIM_UPDATE_PARMS

The MCI_ANIM_UPDATE_PARMS structure contains parameters for the MCI_UPDATE message for animation devices. When assigning data to the fields in this data structure,set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    RECT rc;

    HDC hDC;

} MCI_ANIM_UPDATE_PARMS;

Fields      	The MCI_ANIM_UPDATE_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

rc

Specifies a window rectangle.

hDC

Specifies a handle to the device context.

See Also	MCI_UPDATE


MCI_ANIM_WINDOW_PARMS

The MCI_ANIM_WINDOW_PARMS structure contains parameters for the MCI_WINDOW message for movie and graphic devices. When assigning data to the fields in this data structure,set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    WORD hWnd;

    WORD wReserved1;

    WORD nCmdShow;

    WORD wReserved2;

    LPSTR lpstrText;

} MCI_ANIM_WINDOW_PARMS;

Fields      	The MCI_ANIM_WINDOW_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

hWnd

Specifies a handle to the display window.

wReserved1

Reserved.

nCmdShow

Specifies how the window is displayed.

wReserved2

Reserved.

lpstrText

Specifies a long pointer to a null-terminated string containing the window caption.

See Also	MCI_WINDOW


MCI_BREAK_PARMS

The MCI_BREAK_PARMS structure contains parameters for the MCI_BREAK message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    int nVirtKey;

    WORD wReserved0;

    HWND hwndBreak;

    WORD wReserved1;

} MCI_BREAK_PARMS;

Fields      	The MCI_BREAK_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

nVirtKey

Specifies the virtual key code used for the break key.

wReserved0

Reserved.

hwndBreak

Specifies a window handle of the window that must be the current window for break detection.

wReserved1

Reserved.

See Also	MCI_BREAK


MCI_GENERIC_PARMS

The MCI_GENERIC_PARMS structure contains the information for MCI command messages that have empty parameter lists. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

} MCI_GENERIC_PARMS;

Fields      	The MCI_GENERIC_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

See Also	MCI_COPY, MCI_CLOSE, MCI_CUE, MCI_PASTE, MCI_PAUSE, MCI_REALIZE, MCI_SPIN, MCI_STOP


MCI_GETDEVCAPS_PARMS

The MCI_GETDEVCAPS_PARMS structure contains parameters for the MCI_GETDEVCAPS message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwReturn;

    DWORD dwItem;

} MCI_GETDEVCAPS_PARMS;

Fields      	The MCI_GETDEVCAPS_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwReturn

Contains the return information on exit.

dwItem

Identifies the capability being queried.

See Also	MCI_GETDEVCAPS


MCI_INFO_PARMS

The MCI_INFO_PARMS structure contains parameters for the MCI_INFO message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpstrReturn;

    DWORD dwRetSize;

} MCI_INFO_PARMS;

Fields      	The MCI_INFO_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

lpstrReturn

Specifies a long pointer to a user-supplied buffer for the return string.

dwRetSize

Specifies the size in bytes of the buffer for the return string.

See Also	MCI_INFO


MCI_LOAD_PARMS

The MCI_LOAD_PARMSstructure contains the information for MCI_LOAD message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpfilename;

} MCI_LOAD_PARMS;

Fields      	The MCI_LOAD_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

lpfilename

Specifies a far pointer to a null-terminated string containing the filename of the device element to load.

See Also	MCI_LOAD


MCI_OPEN_PARMS

The MCI_OPEN_PARMS structure contains information for MCI open message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    WORD wDeviceID;

    WORD wReserved0;

    LPSTR lpstrDeviceType;

    LPSTR lpstrElementName;

    LPSTR lpstrAlias;

} MCI_OPEN_PARMS;

Fields      	The MCI_OPEN_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

wDeviceID

Specifies the device ID returned to user.

wReserved0

Reserved.

lpstrDeviceType

Specifies the name or constant ID of the device type.

lpstrElementName

Specifies the device element name (usually a pathname) or NULL.

lpstrAlias

Specifies an optional device alias.

See Also	MCI_OPEN


MCI_OVLY_OPEN_PARMS

The MCI_OVLY_OPEN_PARMSstructure contains information for MCI_OPEN message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    WORD wDeviceID;

    WORD wReserved0;

    LPSTR lpstrDeviceType;

    LPSTR lpstrElementName;

    LPSTR lpstrAlias;

    DWORD dwStyle;

    DWORD hWndParent;

    WORD wReserved1;

} MCI_OVLY_OPEN_PARMS;

Fields      	The MCI_OVLY_OPEN_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

wDeviceID

Specifies the device ID returned to user.

wReserved0

Reserved.

lpstrDeviceType

Specifies the name or contstant ID of the device type obtained from the SYSTEM.INI file.

lpstrElementName

Specifies the device element name (usually a pathname) or NULL.

lpstrAlias

Specifies an optional device alias.

dwStyle

Specifies the window style.

hWndParent

Specifies the handle to use as the window parent.

wReserved1

Reserved.

See Also	MCI_OPEN


MCI_OVLY_RECT_PARMS

The MCI_OVLY_RECT_PARMS structure contains parameters for the MCI_PUT and MCI_WHERE messages for video overlay devices. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    RECT rc;

} MCI_OVLY_RECT_PARMS;

Fields      	The MCI_OVLY_RECT_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

rc

Specifies a rectangle.

See Also	MCI_PUT, MCI_WHERE


MCI_OVLY_UPDATE_PARMS

The MCI_OVLY_UPDATE_PARMS structure contains parameters for the MCI_UPDATE message for video overlay devices. When assigning data to the fields in this data structure,set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    RECT rc;

    HDC hDC;

} MCI_OVLY_UPDATE_PARMS;

Fields      	The MCI_OVLY_UPDATE_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

rc

Specifies a window rectangle.

hDC

Specifies a handle to the device context.

See Also	MCI_UPDATE


MCI_OVLY_WINDOW_PARMS

The MCI_OVLY_WINDOW_PARMS structure contains parameters for the MCI_WINDOW message for video overlay devices. When assigning data to the fields in this data structure,set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    WORD hWnd;

    WORD wReserved1;

    WORD nCmdShow;

    WORD wReserved2;

    LPSTR lpstrText;

} MCI_OVLY_WINDOW_PARMS;

Fields      	The MCI_OVLY_WINDOW_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

hWnd

Specifies a handle to the display window.

wReserved1

Reserved.

nCmdShow

Specifies how the window is displayed.

wReserved2

Reserved.

lpstrText

Specifies a long pointer to a null-terminated buffer containing the window caption.

See Also	MCI_WINDOW


MCI_PLAY_PARMS

The MCI_PLAY_PARMS structure contains parameters for the MCI_PLAY message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_PLAY_PARMS;

Fields      	The MCI_PLAY_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwFrom

Specifies the position to play from.

dwTo

Specifies the position to play to.

See Also	MCI_PLAY


MCI_RECORD_PARMS

The MCI_RECORD_PARMS structure contains parameters for the MCI_RECORD message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommandto validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_RECORD_PARMS;

Fields      	The MCI_RECORD_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwFrom

Specifies the position to play from.

dwTo

Specifies the position to play to.

See Also	MCI_RECORD


MCI_SAVE_PARMS

The MCI_SAVE_PARMSstructure contains the information for MCI_SAVE message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD lpfilename;

} MCI_SAVE_PARMS;

Fields      	The MCI_SAVE_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

lpfilename

Specifies a far pointer to the buffer containing a null-terminated string.

See Also	MCI_SAVE


MCI_SEEK_PARMS

The MCI_SEEK_PARMS structure contains parameters for the MCI_SEEK message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwTo;

} MCI_SEEK_PARMS;

Fields      	The MCI_SEEK_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwTo

Specifies the position to seek to.

See Also	MCI_SEEK


MCI_SEQ_SET_PARMS

The MCI_SEQ_SET_PARMS structure contains parameters for the MCI_SET message for MIDI sequencer devices. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

    DWORD dwTempo;

    DWORD dwPort;

    DWORD dwSlave;

    DWORD dwMaster;

    DWORD dwOffset;

} MCI_SEQ_SET_PARMS;

Fields      	The MCI_SEQ_SET_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwTimeFormat

Specifies the time format of the sequencer.

dwAudio

Specifies the audio output channel.

dwTempo

Specifies the tempo.

dwPort

Specifies the output port.

dwSlave

Specifies the type of synchronization used by the sequencer for slave operation.

dwMaster

Specifies the type of synchronization used by the sequencer for master operation.

dwOffset

Specifies the data offset.

See Also	MCI_SET


MCI_SET_PARMS

The MCI_SET_PARMS structure contains parameters for the MCI_SET message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

} MCI_SET_PARMS;

Fields      	The MCI_SET_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwTimeFormat

Specifies the time format used by the animation device.

dwAudio

Specifies the audio output channel.

See Also	MCI_SET


MCI_SOUND_PARMS

The MCI_SOUND_PARMS structure contains parameters for the MCI_SOUND message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpstrSoundName;

} MCI_SOUND_PARMS;

Fields      	The MCI_SOUND_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

lpstrSoundName

Specifies a far pointer to a null-terminated string containing the name of the sound or the name of the file containing the sound to be played.

See Also	MCI_SOUND


MCI_STATUS_PARMS

The MCI_STATUS_PARMS structure contains parameters for the MCI_STATUS message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwReturn;

    DWORD dwTrack;

    DWORD dwItem;

} MCI_STATUS_PARMS;

Fields      	The MCI_STATUS_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwReturn

Contains the return information on exit.

dwTrack

Specifies the length or number of tracks.

dwItem

Identifies the capability being queried.

See Also	MCI_STATUS


MCI_SYSINFO_PARMS

The MCI_SYSINFO_PARMS structure contains parameters for the MCI_SYSINFO message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwDummyCallback;

    LPSTR lpstrReturn;

    DWORD dwRetSize;

    DWORD dwNumber;

    WORD wDeviceType;

    WORD wReserved0;

} MCI_SYSINFO_PARMS;

Fields      	The MCI_SYSINFO_PARMS structure contains the following fields:

dwDummyCallback

Reserved. Callback functions are not used for this command.

lpstrReturn

Specifies a long pointer to a user-supplied buffer for the return string.

dwRetSize

Specifies the size in bytes of the buffer for the return string.

dwNumber

Specifies a number indicating the device position in the MCI device table or in the list of open devices if the MCI_SYSINFO_OPEN flag is set.

wDeviceType

Specifies the type of device.

wReserved0

Reserved.

See Also	MCI_SYSINFO


MCI_VD_ESCAPE_PARMS

The MCI_VD_ESCAPE_PARMS structure contains parameters for the MCI_ESCAPE message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    LPSTR lpstrCommand;

} MCI_VD_ESCAPE_PARMS;

Fields      	The MCI_VD_ESCAPE_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

lpstrCommand

Specifies a far pointer to a null-terminated buffer containing the command to send to the device.

See Also	MCI_ESCAPE


MCI_VD_PLAY_PARMS

The MCI_VD_PLAY_PARMS structure contains parameters for the MCI_PLAY message for videodiscs. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

    DWORD dwSpeed;

} MCI_VD_PLAY_PARMS;

Fields      	The MCI_VD_PLAY_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwFrom

Specifies the position to play from.

dwTo

Specifies the position to play to.

dwSpeed

Specifies the playing speed in frames per second.

See Also	MCI_PLAY


MCI_VD_STEP_PARMS

The MCI_VD_STEP_PARMS structure contains parameters for the MCI_STEP message for videodiscs. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrames;

} MCI_VD_STEP_PARMS;

Fields      	The MCI_VD_STEP_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwFrames

Specifies the number of frames to step.

See Also	MCI_STEP


MCI_WAVE_CUT_PARMS

The MCI_WAVE_CUT_PARMS structure contains parameters for the MCI_CUT message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommandto validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwFrom;

    DWORD dwTo;

} MCI_WAVE_CUT_PARMS;

Fields      	The MCI_WAVE_CUT_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwFrom

Specifies the position to cut from.

dwTo

Specifies the position to cut to.

See Also	MCI_CUT


MCI_WAVE_OPEN_PARMS

The MCI_WAVE_OPEN_PARMSstructure contains information for MCI_OPEN message. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    WORD wDeviceID;

    WORD wReserved0;

    LPSTR lpstrDeviceType;

    LPSTR lpstrElementName;

    LPSTR lpstrAlias;

    DWORD dwBufferSeconds;

} MCI_WAVE_OPEN_PARMS;

Fields      	The MCI_WAVE_OPEN_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

wDeviceID

Specifies the device ID returned to user.

wReserved0

Reserved.

lpstrDeviceType

Specifies the name or constant ID of the device type obtained.

lpstrElementName

Specifies the device element name (usually a pathname) or NULL.

lpstrAlias

Specifies an optional device alias.

dwBufferSeconds

Specifies the buffer length in seconds.

See Also	MCI_OPEN


MCI_WAVE_SET_PARMS

The MCI_WAVE_SET_PARMS structure contains parameters for the MCI_SET message for waveform devices. When assigning data to the fields in this data structure, set the corresponding MCI flags in the dwFlags parameter of mciSendCommand to validate the fields.

typedef struct  {

    DWORD dwCallback;

    DWORD dwTimeFormat;

    DWORD dwAudio;

    WORD wInput;

    WORD wReserved0;

    WORD wOutput;

    WORD wReserved1;

    WORD wFormatTag;

    WORD wReserved2;

    WORD nChannels;

    WORD wReserved3;

    DWORD nSamplesPerSec;

    DWORD nAvgBytesPerSec;

    WORD nBlockAlign;

    WORD wReserved4;

    WORD wBitsPerSample;

    WORD wReserved5;

} MCI_WAVE_SET_PARMS;

Fields      	The MCI_WAVE_SET_PARMS structure contains the following fields:

dwCallback

Specifies a window handle cast to a DWORD used for the MCI_NOTIFY callback function.

dwTimeFormat

Specifies the time format used by by the device.

dwAudio

Specifies the channel used for audio output.

wInput

Specifies the channel used for audio input.

wReserved0

Reserved.

wOutput

Specifies the channel used for output.

wReserved1

Reserved.

wFormatTag

Species the interpretation of the waveform data.

wReserved2

Reserved.

nChannels

Specifies mono (1) or stereo (2).

wReserved3

Reserved.

nSamplesPerSec

Specifies the samples per second used for the waveform.

nAvgBytesPerSec

Specifies the sample rate in bytes per second.

nBlockAlign

Specifies the block alignment of the data.

wReserved4

Reserved.

wBitsPerSample

Specifies the number of bits per sample.

wReserved5

Reserved.

See Also	MCI_SET


MIDIHDR

The MIDIHDR structure defines the header used to identify a MIDI system-exclusive data buffer.

typedef struct midihdr_tag {

    LPSTR lpData;

    DWORD dwBufferLength;

    DWORD dwBytesRecorded;

    DWORD dwUser;

    DWORD dwFlags;

    struct midihdr_tag far * lpNext;

    DWORD reserved;

} MIDIHDR;

Fields      	The MIDIHDR structure contains the following fields:

lpData

Specifies a far pointer to the system-exclusive data buffer.

dwBufferLength

Specifies the length of the data buffer.

dwBytesRecorded

When the header is used in input, this specifies how much data is in the buffer.

dwUser

Specifies 32 bits of user data.

dwFlags

Specifies flags giving information about the data buffer.

MHDR_DONE

Set by the device driver to indicate that it is finished with the data buffer and is returning it to the application.

lpNext

Is reserved and should not be used.

reserved

Is reserved and should not be used.


MIDIINCAPS

The MIDIINCAPS structure describes the capabilities of a MIDI input device.

typedef struct midiincaps_tag {

    WORD wMid;

    WORD wPid;

    VERSION vDriverVersion;

    char szPname[MAXPNAMELEN];

} MIDIINCAPS;

Fields      	The MIDIINCAPS structure contains the following fields:

wMid

Specifies a manufacturer ID for the device driver for the MIDI input device.  Currently defined IDs are:

MM_MICROSOFT

Drivers developed by Microsoft Corporation.

wPid

Specifies a product ID for the MIDI input device. Currently defined IDs are:

MM_SNDBLST_MIDIIN

SoundBlaster MIDI input port.

MM_MPU401_MIDIIN

MPU401 MIDI input port.

MM_MSOUND_MIDIIN

MSound MIDI input port.

vDriverVersion

Specifies the version number of the device driver for the MIDI input device.  The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname[MAXPNAMELEN]

Specifies the product name in a NULL-terminated string.

See Also	midiInGetDevCaps


MIDIOUTCAPS

The MIDIOUTCAPS structure describes the capabilities of a MIDI output device.

typedef struct midioutcaps_tag {

    WORD wMid;

    WORD wPid;

    VERSION vDriverVersion;

    char szPname[MAXPNAMELEN];

    WORD wTechnology;

    WORD wVoices;

    WORD wNotes;

    WORD wChannelMask;

    DWORD dwSupport;

} MIDIOUTCAPS;

Fields      	The MIDIOUTCAPS structure contains the following fields:

wMid

Specifies a manufacturer ID for the device driver for the MIDI output device.  Curently defined IDs are:

MM_MICROSOFT

Drivers developed by Microsoft Corporation.

wPid

Specifies a product ID for the MIDI output device.  Currently defined IDs are:

MM_SNDBLST_MIDIOUT

SoundBlaster MIDI output port.

MM_MPU401_MIDIOUT

MPU401 MIDI output port.

MM_MSOUND_MIDIOUT

MSound MIDI output port.

MM_MSOUND_SYNTH

MSound MIDI synthesizer.

MM_ADLIB

Adlib synthesizer.

MM_MIDI_MAPPER

Microsoft MIDI Mapper.

vDriverVersion

Specifies the version number of the device driver for the MIDI output device.  The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname[MAXPNAMELEN]

Specifies the product name in a NULL-terminated string.

wTechnology

Describes the type of the MIDI output device according to one of the following flags:

MOD_MIDIPORT

Indicates the device is a MIDI hardware port.

MOD_SQSYNTH

Indicates the device is a square wave synthesizer.

MOD_FMSYNTH

Indicates the device is an FM synthesizer.

MOD_MAPPER

Indicates the device is the Microsoft MIDI Mapper.

wVoices

Specifies the number of voices supported by an internal synthesizer device.  If the device is a port, the field is not meaningful and will be set to 0.

wNotes

Specifies the maximum number of simultaneous notes that may be played by an internal synthesizer device.  If the device is a port, the field is not meaningful and will be set to 0.

wChannelMask

Specifies the channels that an internal synthesizer device responds to, where the least significant bit refers to channel 0 and the most significant bit to channel 15.  Port devices transmit on all channels and so will set this field to 0xFFFF.

dwSupport

Specifies optional functionality supported by the device.

MIDICAPS_VOLUME

Supports volume control.

MIDICAPS_LRVOLUME

Supports separate left and right volume control.

MIDICAPS_CACHE

Supports patch caching.

Comments    	If a device supports volume changes, the MIDICAPS_VOLUME flag will be set for the dwSupport field.  If a device supports separate volume changes on the left and right channels, both the MIDICAPS_VOLUME and the MIDICAPS_LRVOLUME flags will be set for this field.

See Also	midiOutGetDevCaps


MMCKINFO

This structure contains information about a chunk in a RIFF file.

typedef struct _MMCKINFO {

    FOURCC ckid;

    DWORD cksize;

    FOURCC fccType;

    DWORD dwDataOffset;

    DWORD dwFlags;

} MMCKINFO;

Fields      	The MMCKINFO structure contains the following fields:

ckid

Specifies the chunk ID of the chunk.

cksize

Specifies the size of the data field of the chunk. The size of the data field does not include the four-byte chunk ID, the four-byte chunk size, or the optional pad byte at the end of the data field.

fccType

Specifies the form type for "RIFF" chunks or the list type for "LIST" chunks.

dwDataOffset

Specifies the file offset of the beginning of the chunk's data field, relative to the beginning of the file.

dwFlags

Specifies flags giving additional information about the chunk. Contains zero or more of the following flags:

MMIO_DIRTY

Indicates that the length of the chunk may have changed and should be updated by mmioAscend.  This flag is set when a chunk is created by mmioCreateChunk.


MMIOINFO

This structure contains the current state of a file opened with mmioOpen.

typedef struct _MMIOINFO {

    DWORD dwFlags;

    FOURCC fccIOProc;

    LPMMIOPROC pIOProc;

    WORD wErrorRet;

    WORD wReserved;

    LONG cchBuffer;

    HPSTR pchBuffer;

    HPSTR pchNext;

    HPSTR pchEndRead;

    HPSTR pchEndWrite;

    LONG lBufOffset;

    LONG lDiskOffset;

    DWORD adwInfo[4];

    DWORD dwReserved1;

    DWORD dwReserved2;

    HMMIO hmmio;

} MMIOINFO;

Fields      	The MMIOINFO structure contains the following fields:

dwFlags

Specifies options indicating how a file was opened:

MMIO_READ

The file was opened only for reading.

MMIO_WRITE

The file was opened only for writing.

MMIO_READWRITE

The file was opened for both reading and writing.

MMIO_COMPAT

The file was opened with compatibility mode,allowing any process on a given machine to open the file any number of times.

MMIO_EXCLUSIVE

The file was opened with exclusive mode,denying other processes both read and write access to the file.

MMIO_DENYWRITE

Other processes are denied write access to the file.

MMIO_DENYREAD

Other processes are denied read access to the file.

MMIO_DENYNONE

Other processes are not denied read or write access to the file.

MMIO_CREATE

mmioOpen was directed to create the file, or truncate it to zero length if it already existed.

MMIO_ALLOCBUF

The file's I/O buffer was allocated by mmioOpen or mmioSetBuffer.

fccIOProc

Specifies the four-character code identifying the file's I/O procedure.  If the I/O procedure is not an installed I/O procedure, fccIOProc is NULL.

pIOProc

Specifies the address of the file's I/O procedure.

wErrorRet

Holds the extended error value from mmioOpenif mmioOpen returns NULL.  Is not used to return extended error information from any other functions.

wReserved

Reserved for future use.

cchBuffer

Specifies the size of the file's I/O buffer in bytes. If the file does not have an I/O buffer, this field is zero.

pchBuffer

Specifies the address of the file's I/O buffer. If the file is unbuffered, pchBuffer is NULL.

pchNext

Specifies a huge pointer to the next location in the I/O buffer to be read or written. If no more bytes can be read without calling mmioAdvance or mmioRead, then this field points to pchEndRead. If no more bytes can be written without calling mmioAdvanceor mmioWrite, then this field points to pchEndWrite.

pchEndRead

Specifies a pointer to the location that is one byte past the last location in the buffer that can be read.

pchEndWrite

Specifies a pointer to the location that is one byte past the last location in the buffer that can be written.

lBufOffset

Reserved for internal use by MMIO functions.

lDiskOffset

Specifies the current file position. The current file position is an offset in bytes from the beginning of the file. I/O procedures are responsible for maintaining this field.

adwInfo[4]

Contained state information maintained by the I/O procedure.  I/O procedures can also use these fields to transfer information from the caller to the I/O procedure when the caller opens a file.

dwReserved1

Reserved for internal use by MMIO functions.

dwReserved2

Reserved for internal use by MMIO functions.

hmmio

Specifies the MMIO handle to the open file. I/O procedures can use this handle when calling other MMIO functions.

See Also	mmioGetInfo


MMPACTION

The MMPACTION structure contains information about a movie file script-channel command.

typedef struct tagMMPACTION {

    BYTE bMenuItem;

    BYTE bActionCode;

    WORD wTextOffset;

} MMPACTION;

Fields      	The MMPACTION structure contains the following fields:

bMenuItem

Specifies the menu item number from the script-channel window.

bActionCode

Not used by Movie Player.

wTextOffset

Specifies the offset of the script-channel text from the start of the action text block.

Comments    	The action text is stored in packed format, without terminating NULL characters. To determine the length of an action-text entry, subtract the wTextOffset value of the action entry from the wTextOffset value of the next action entry in the list. The action-entry list contains one action entry beyond the count of action-code entries returned by the mmpGetInfo function. The wTextOffset value of the last MMPACTION structure indexes one byte beyond the end of the action-code text.


MMPLABEL

The MMPLABEL structure contains information about a movie file label entry.

typedef struct tagMMPLABEL {

    WORD wFrameNum;

    WORD wTextOffset;

} MMPLABEL;

Fields      	The MMPLABEL structure contains the following fields:

wFrameNum

Specifies the frame number associated with the label.

wTextOffset

Specifies the offset of the label text from the start of the label text block.

Comments    	The label text is stored in packed format. Each label entry is terminated with a character value 0x0d. To determine the length of a label entry, subtract the wTextOffset value of the label entry from the wTextOffset value of the next label entry. The label list contains one label entry beyond the count of label entries returned by the mmpGetInfo function. The wTextOffset value of the last MMPLABEL structure indexes one byte beyond the end of the label text.


MMPMOVIEINFO

The MMPMOVIEINFO structure contains information about a movie file.

typedef struct tagMMPMOVIEINFO {

    DWORD dwFileVersion;

    DWORD dwTotalFrames;

    DWORD dwInitialFramesPerSecond;

    WORD wPixelDepth;

    DWORD dwMovieExtentX;

    DWORD dwMovieExtentY;

    char chFullMacName[128];

} MMPMOVIEINFO;

Fields      	The MMPMOVIEINFO structure contains the following fields:

dwFileVersion

Specifies the version of the authoring system used to create the file. The high-order word contains the major version number, and the low-order word contains the minor version number.

dwTotalFrames

Specifies the number of frames in the movie.

dwInitialFramesPerSecond

Specifies the initial tempo of the movie in frames per second.

wPixelDepth

Specifies the number of bits per pixel under which the movie was authored (either 1, 4, or 8).

dwMovieExtentX

Specifies the pixel width of the movie playback area.

dwMovieExtentY

Specifies the pixel length of the movie playback area.

chFullMacName[128]

Specifies the movie title in a NULL-terminated string.


MMTIME

General purpose structure for timing information.

typedef struct mmtime_tag {

    WORD wType;

    union {

        DWORD ms;

        DWORD sample;

        DWORD cb;

        struct {

            BYTE hour;

            BYTE min;

            BYTE sec;

            BYTE frame;

            BYTE fps;

            BYTE dummy;

        } smpte;

        struct {

            DWORD songptrpos;

        } midi;

    } u;

} MMTIME;

Fields      	The MMTIME structure contains the following fields:

wType

Specifies the type of the union.

TIME_MS

Time counted in milliseconds.

TIME_SAMPLES

Number of wave samples.

TIME_BYTES

Current byte offset.

TIME_SMPTE

SMPTE time.

TIME_MIDI

MIDI time.

ms

Milliseconds.  Used when wType is TIME_MS.

sample

Samples.  Used when wType is TIME_SAMPLES.

cb

Byte count.  Used when wType is TIME_BYTES.

hour

Hours.

min

Minutes.

sec

Seconds.

frame

Frames.

fps

Frames per second (24, 25, 29(30 drop) or 30).

dummy

Dummy byte for alignment.

songptrpos

Song pointer position.


PCMWAVEFORMAT

The PCMWAVEFORMAT structure describes the data format for PCM waveform data.

typedef struct pcmwaveformat_tag {

    WAVEFORMAT wf;

    WORD wBitsPerSample;

} PCMWAVEFORMAT;

Fields      	The PCMWAVEFORMAT structure contains the following fields:

wf

Specifies a WAVEFORMAT structure containing general information about the format of the waveform data.

wBitsPerSample

Specifies the number of bits per sample.

See Also	WAVEFORMAT


TIMECAPS

Structure for returning information about the resolution of the timer.

typedef struct timecaps_tag {

    WORD wPeriodMin;

    WORD wPeriodMax;

} TIMECAPS;

Fields      	The TIMECAPS structure contains the following fields:

wPeriodMin

Minimum period supported by timer.

wPeriodMax

Maximum period supported by timer.


WAVEFORMAT

The WAVEFORMAT structure describes the format of waveform data.  Only format information common to all waveform data formats is included in this structure.  For formats that require additional information, this structure is included as a field in another data structure along with the additional information.

typedef struct waveformat_tag {

    WORD wFormatTag;

    WORD nChannels;

    DWORD nSamplesPerSec;

    DWORD nAvgBytesPerSec;

    WORD nBlockAlign;

} WAVEFORMAT;

Fields      	The WAVEFORMAT structure contains the following fields:

wFormatTag

Specifies the format type.

WAVE_FORMAT_PCM

Waveform data is PCM.

nChannels

Specifies the number of channels in the waveform data.  Mono data uses 1 channel and stereo data uses 2 channels.

nSamplesPerSec

Specifies the sample rate in samples per second.

nAvgBytesPerSec

Specifies the required average data transfer rate in bytes per second.

nBlockAlign

Specifies the block alignment in bytes. The block alignment is the minimum atomic unit of data.

Comments    	For PCM data, the block alignment is the number of bytes used by a single sample, including data for both channels if the data is stereo. For example, the block alignment for 16-bit stereo PCM is 4 bytes (2 channels, 2 bytes per sample).

See Also	PCMWAVEFORMAT


WAVEHDR

The WAVEHDR structure defines the header used to identify a waveform data buffer.

typedef struct wavehdr_tag {

    LPSTR lpData;

    DWORD dwBufferLength;

    DWORD dwBytesRecorded;

    DWORD dwUser;

    DWORD dwFlags;

    DWORD dwLoops;

    struct wavehdr_tag far * lpNext;

    DWORD reserved;

} WAVEHDR;

Fields      	The WAVEHDR structure contains the following fields:

lpData

Specifies a far pointer to the waveform data buffer.

dwBufferLength

Specifies the length of the data buffer.

dwBytesRecorded

When the header is used in input, this specifies how much data is in the buffer.

dwUser

Specifies 32 bits of user data.

dwFlags

Specifies flags giving information about the data buffer.

WHDR_DONE

Set by the device driver to indicate that it is finished with the data buffer and is returning it to the application.

WHDR_BEGINLOOP

Specifies that this buffer is the first buffer in a loop.  This flag is only used with output data buffers.

WHDR_ENDLOOP

Specifies that this buffer is the last buffer in a loop.  This flag is only used with output data buffers.

dwLoops

Specifies the number of times to play the loop. This parameter is used only with output data buffers.

lpNext

Is reserved and should not be used.

reserved

Is reserved and should not be used.

Comments    	Use the WHDR_BEGINLOOP and WHDR_ENDLOOP flags in the dwFlagsfield to specify the beginning and ending data blocks for looping.  To loop on a single block, specify both flags for the same block.  Use the dwLoops field in the WAVEHDR structure for the first block in the loop to specify the number times to play the loop.


WAVEINCAPS

The WAVEINCAPS structure describes the capabilities of a waveform input device.

typedef struct waveincaps_tag {

    WORD wMid;

    WORD wPid;

    VERSION vDriverVersion;

    char szPname[MAXPNAMELEN];

    DWORD dwFormats;

    WORD wChannels;

} WAVEINCAPS;

Fields      	The WAVEINCAPS structure contains the following fields:

wMid

Specifies a manufacturer ID for the device driver for the waveform input device.  Currently defined IDs are:

MM_MICROSOFT

Drivers developed by Microsoft Corporation.

wPid

Specifies a product ID for the waveform input device. Currently defined IDs are:

MM_SNDBLST_WAVEIN

 €>
€
¬A‚€
‚ÿ
SoundBlas
szPname[MAXPNAMELEN]

Specifies the product name in a NULL-terminated string.

dwFormats

Specifies which standard formats are supported. The supported formats are specified with a logical OR of the following flags:

WAVE_FORMAT_1M08

11.025 kHz, Mono, 8-bit

WAVE_FORMAT_1S08

11.025 kHz, Stereo, 8-bit

WAVE_FORMAT_1M16

11.025 kHz, Mono, 16-bit

WAVE_FORMAT_1S16

11.025 kHz, Stereo, 16-bit

WAVE_FORMAT_2M08

22.05 kHz, Mono, 8-bit

WAVE_FORMAT_2S08

22.05 kHz, Stereo, 8-bit

WAVE_FORMAT_2M16

22.05 kHz, Mono, 16-bit

WAVE_FORMAT_2S16

22.05 kHz, Stereo, 16-bit

WAVE_FORMAT_4M08

44.1 kHz, Mono, 8-bit

WAVE_FORMAT_4S08

44.1 kHz, Stereo, 8-bit

WAVE_FORMAT_4M16

44.1 kHz, Mono, 16-bit

WAVE_FORMAT_4S16

44.1 kHz, Stereo, 16-bit

wChannels

Specifies whether the device supports mono (1) or stereo (2) output.

dwSupport

Specifies optional functionality supported by the device.

WAVECAPS_PITCH

Supports pitch control.

WAVECAPS_PLAYBACKRATE

Supports playback rate control.

WAVECAPS_VOLUME

Supports volume control.

WAVECAPS_LRVOLUME

Supports separate left and right volume control.

Comments    	If a device supports volume changes, the WAVECAPS_VOLUME flag will be set for the dwSupport field.  If a device supports separate volume changes on the left and right channels, both the WAVECAPS_VOLUME and the WAVECAPS_LRVOLUME flags will be set for this field.

See Also	waveOutGetDevCaps