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 fixed callback function or a handle to a window 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 user instance data 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 as follows:

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 MIDI map. This occurs only when opening the mapper.

MIDIERR_NODEVICE

A port in the current MIDI map doesn't exist. This occurs only when opening the mapper.

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 instance data supplied 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, timeSetEvent, timeKillEvent, midiOutShortMsg, midiOutLongMsg, and OutputDebugStr.

See Also

midiOutClose