midiConnect

The midiConnect function connects a MIDI input device to a MIDI thru or output device, or connects a MIDI thru device to a MIDI output device.

MMRESULT midiConnect(

HMIDI hMidi,

HMIDIOUT hmo,

LPVOID pReserved

);

Parameters

hMidi

Handle of a MIDI input device or a MIDI thru device. (For thru devices, this handle must have been returned by a call to the midiOutOpen function.)

hmo

Handle of the MIDI output or thru device.

pReserved

Reserved; must be NULL.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MIDIERR_NOTREADY	Specified input device is already connected to an output device.
MMSYSERR_INVALHANDLE	Specified device handle is invalid.

Remarks

After calling this function, the MIDI input device receives event data in an MIM_DATA message whenever a message with the same event data is sent to the output device driver.

A thru driver is a special form of MIDI output driver. The system will allow only one MIDI output device to be connected to a MIDI input device, but multiple MIDI output devices can be connected to a MIDI thru device. Whenever the given MIDI input device receives event data in an MIM_DATA message, a message with the same event data is sent to the given output device driver (or through the thru driver to the output drivers).

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, midiOutOpen, MIM_DATA

midiConnect

The midiConnect function connects a MIDI input device to a MIDI thru or output device, or connects a MIDI thru device to a MIDI output device.

MMRESULT midiConnect(

HMIDI hMidi,

HMIDIOUT hmo,

LPVOID pReserved

);

Parameters

hMidi

Handle of a MIDI input device or a MIDI thru device. (For thru devices, this handle must have been returned by a call to the midiOutOpen function.)

hmo

Handle of the MIDI output or thru device.

pReserved

Reserved; must be NULL.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MIDIERR_NOTREADY	Specified input device is already connected to an output device.
MMSYSERR_INVALHANDLE	Specified device handle is invalid.

Remarks

After calling this function, the MIDI input device receives event data in an MIM_DATA message whenever a message with the same event data is sent to the output device driver.

A thru driver is a special form of MIDI output driver. The system will allow only one MIDI output device to be connected to a MIDI input device, but multiple MIDI output devices can be connected to a MIDI thru device. Whenever the given MIDI input device receives event data in an MIM_DATA message, a message with the same event data is sent to the given output device driver (or through the thru driver to the output drivers).

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, midiOutOpen, MIM_DATA

midiDisconnect

The midiDisconnect function disconnects a MIDI input device from a MIDI thru or output device, or disconnects a MIDI thru device from a MIDI output device.

MMRESULT midiDisconnect(

HMIDI hMidi,

HMIDIOUT hmo,

LPVOID pReserved

);

Parameters

hMidi

Handle of a MIDI input device or a MIDI thru device.

hmo

Handle of the MIDI output device to be disconnected.

pReserved

Reserved; must be NULL.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MMSYSERR_INVALHANDLE	Specified device handle is invalid.

Remarks

MIDI input, output, and thru devices can be connected by using the midiConnect function. Thereafter, whenever the MIDI input device receives event data in an MIM_DATA message, a message with the same event data is sent to the output device driver (or through the thru driver to the output drivers).

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, midiConnect, MIM_DATA

midiInAddBuffer

The midiInAddBuffer function sends an input buffer to a specified opened MIDI input device. This function is used for system-exclusive messages.

MMRESULT midiInAddBuffer(

HMIDIIN hMidiIn,

LPMIDIHDR lpMidiInHdr,

UINT cbMidiInHdr

);

Parameters

hMidiIn

Handle of the MIDI input device.

lpMidiInHdr

Address of a MIDIHDR structure that identifies the buffer.

cbMidiInHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MIDIERR_STILLPLAYING		The buffer pointed to by lpMidiInHdr is still in the queue.
MIDIERR_UNPREPARED		The buffer pointed to by lpMidiInHdr has not been prepared.
MMSYSERR_INVALHANDLE		The specified device handle is invalid.
MMSYSERR_INVALPARAM		The specified pointer or structure is invalid.
MMSYSERR_NOMEM		The system is unable to allocate or lock memory.

Remarks

When the buffer is filled, it is sent back to the application.

The buffer must be prepared by using the midiInPrepareHeader function before it is passed to the midiInAddBuffer function.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, MIDIHDR, midiInPrepareHeader

midiInClose

The midiInClose function closes the specified MIDI input device.

MMRESULT midiInClose(

HMIDIIN hMidiIn

);

Parameters

hMidiIn

Handle of the MIDI input device. If the function is successful, the handle is no longer valid after the call to this function.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MIDIERR_STILLPLAYING	Buffers are still in the queue.
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

Remarks

If there are input buffers that have been sent by using the midiInAddBuffer function and have not been returned to the application, the close operation will fail. To return all pending buffers through the callback function, use the midiInReset function.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, midiInAddBuffer, midiInReset

midiInGetDevCaps

The midiInGetDevCaps function determines the capabilities of a specified MIDI input device.

MMRESULT midiInGetDevCaps(

UINT uDeviceID,

LPMIDIINCAPS lpMidiInCaps,

UINT cbMidiInCaps

);

Parameters

uDeviceID

Identifier of the MIDI input device. The device identifier varies from zero to one less than the number of devices present. This parameter can also be a properly cast device handle.

lpMidiInCaps

Address of a MIDIINCAPS structure that is filled with information about the capabilities of the device.

cbMidiInCaps

Size, in bytes, of the MIDIINCAPS structure. Only cbMidiInCaps bytes (or less) of information is copied to the location pointed to by lpMidiInCaps. If cbMidiInCaps is zero, nothing is copied, and the function returns MMSYSERR_NOERROR.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NODRIVER	The driver is not installed.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

Remarks

To determine the number of MIDI input devices present on the system, use the midiInGetNumDevs function.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, MIDIINCAPS, midiInGetNumDevs

midiInGetErrorText

The midiInGetErrorText function retrieves a textual description for an error identified by the specified error code.

MMRESULT midiInGetErrorText(

MMRESULT wError,

LPSTR lpText,

UINT cchText

);

Parameters

wError

Error code.

lpText

Address of the buffer to be filled with the textual error description.

cchText

Length, in characters, of the buffer pointed to by lpText.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MMSYSERR_BADERRNUM	The specified error number is out of range.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

Remarks

If the textual error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchText is zero, nothing is copied, and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions

midiInGetID

The midiInGetID function gets the device identifier for the given MIDI input device.

This function is supported for backward compatibility. New applications can cast a handle of the device rather than retrieving the device identifier.

MMRESULT midiInGetID(

HMIDIIN hmi,

LPUINT puDeviceID

);

Parameters

hmi

Handle of the MIDI input device.

puDeviceID

Address of a variable to be filled with the device identifier.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MMSYSERR_INVALHANDLE		The hwi parameter specifies an invalid handle.
MMSYSERR_NODRIVER		No device driver is present.
MMSYSERR_NOMEM		Unable to allocate or lock memory.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions

midiInGetNumDevs

The midiInGetNumDevs function retrieves the number of MIDI input devices in the system.

UINT midiInGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of MIDI input devices present in the system. A return value of zero means that there are no devices (not that there is no error).

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions

midiInGetNumDevs

The midiInGetNumDevs function retrieves the number of MIDI input devices in the system.

UINT midiInGetNumDevs(VOID);

Parameters

This function takes no parameters.

Return Values

Returns the number of MIDI input devices present in the system. A return value of zero means that there are no devices (not that there is no error).

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions

midiInMessage

The midiInMessage function sends a message to the MIDI device driver.

DWORD midiInMessage(

HMIDIIN hMidiIn,

UINT msg,

DWORD dw1,

DWORD dw2

);

Parameters

hMidiIn

Handle of the MIDI device.

msg

Message to send.

dw1 and dw2

Message parameters.

Return Values

Returns the value returned by the audio device driver.

Remarks

This function is used only for driver-specific messages that are not supported by the MIDI API.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions

midiInMessage

The midiInMessage function sends a message to the MIDI device driver.

DWORD midiInMessage(

HMIDIIN hMidiIn,

UINT msg,

DWORD dw1,

DWORD dw2

);

Parameters

hMidiIn

Handle of the MIDI device.

msg

Message to send.

dw1 and dw2

Message parameters.

Return Values

Returns the value returned by the audio device driver.

Remarks

This function is used only for driver-specific messages that are not supported by the MIDI API.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

midiInOpen

The midiInOpen function opens a specified MIDI input device.

MMRESULT midiInOpen(

LPHMIDIIN lphMidiIn,

UINT uDeviceID,

DWORD dwCallback,

DWORD dwCallbackInstance,

DWORD dwFlags

);

Parameters

lphMidiIn

Address of an HMIDIIN handle. This location is filled with a handle identifying the opened MIDI input device. The handle is used to identify the device in calls to other MIDI input functions.

uDeviceID

Identifier of the MIDI input device to be opened.

dwCallback

Address of a callback function, a thread identifier, or a handle of a window called with information about incoming MIDI messages. For more information on the callback function, see MidiInProc.

dwCallbackInstance

User instance data passed to the callback function. This parameter is not used with window callback functions or threads.

dwFlags

Callback flag for opening the device and, optionally, a status flag that helps regulate rapid data transfers. It can be the following values:

CALLBACK_FUNCTION

The dwCallback parameter is a callback procedure address.

CALLBACK_NULL

There is no callback mechanism. This value is the default setting.

CALLBACK_THREAD

The dwCallback parameter is a thread identifier.

CALLBACK_WINDOW

The dwCallback parameter is a window handle.

MIDI_IO_STATUS

When this parameter also specifies CALLBACK_FUNCTION, MIM_MOREDATA messages are sent to the callback function as well as MIM_DATA messages. Or, if this parameter also specifies CALLBACK_WINDOW, MM_MIM_MOREDATA messages are sent to the window as well as MM_MIM_DATA messages. This flag does not affect event or thread callbacks.

Most applications that use a callback mechanism will specify CALLBACK_FUNCTION for this parameter.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MMSYSERR_ALLOCATED	The specified resource is already allocated.
MMSYSERR_BADDEVICEID	The specified device identifier is out of range.
MMSYSERR_INVALFLAG	The flags specified by dwFlags are invalid.
MMSYSERR_INVALPARAM	The specified pointer or structure is invalid.
MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

Remarks

To determine the number of MIDI input devices present in the system, use the midiInGetNumDevs function. The device identifier specified by wDeviceID varies from zero to one less than the number of devices present.

If a window or thread is chosen to receive callback information, the following messages are sent to the window procedure or thread 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, and MM_MIM_MOREDATA.

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, and MIM_MOREDATA.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, MIM_MOREDATA, MIM_DATA, MM_MIM_MOREDATA, MM_MIM_DATA, midiInGetNumDevs, MidiInProc, MM_MIM_OPEN, MM_MIM_CLOSE, MM_MIM_LONGDATA, MM_MIM_ERROR, MM_MIM_LONGERROR, MIM_OPEN, MIM_CLOSE, MIM_DATA, MIM_LONGDATA, MIM_ERROR, MIM_LONGERROR, MIM_MOREDATA

midiInPrepareHeader

The midiInPrepareHeader function prepares a buffer for MIDI input.

MMRESULT midiInPrepareHeader(

HMIDIIN hMidiIn,

LPMIDIHDR lpMidiInHdr,

UINT cbMidiInHdr

);

Parameters

hMidiIn

Handle of the MIDI input device.

lpMidiInHdr

Address of a MIDIHDR structure that identifies the buffer to be prepared.

cbMidiInHdr

Size, in bytes, of the MIDIHDR structure.

Return Values

Returns MMSYSERR_NOERROR if successful or an error otherwise. Possible error values include the following:

Value	Description
MMSYSERR_INVALHANDLE		The specified device handle is invalid.
MMSYSERR_INVALPARAM		The specified address is invalid.
MMSYSERR_NOMEM		The system is unable to allocate or lock memory.

Remarks

Preparing a header that has already been prepared has no effect, and the function returns zero.

After the header has been prepared, do not modify the buffer. To free the buffer, use the midiInUnprepareHeader function.

Before using this function, you must set the lpData, dwBufferLength, and dwFlags members of the MIDIHDR structure. The dwFlags member must be set to zero.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mmsystem.h.
  Import Library: Use winmm.lib.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions, MIDIHDR, midiInUnprepareHeader

MidiInProc

The MidiInProc function is the callback function for handling incoming MIDI messages. MidiInProc is a placeholder for the application-supplied function name. The address of this function can be specified in the callback-address parameter of the midiInOpen function.

void CALLBACK MidiInProc(

HMIDIIN hMidiIn,

UINT wMsg,

DWORD dwInstance,

DWORD dwParam1,

DWORD dwParam2

);

Parameters

hMidiIn

Handle of the MIDI input device.

wMsg

MIDI input message.

dwInstance

Instance data supplied with the midiInOpen function.

dwParam1

Message parameters.

dwParam2

Message parameters.

Return Values

This function does not return a value.

Remarks

Applications should not call any system-defined functions from inside a callback function, except for EnterCriticalSection, LeaveCriticalSection, midiOutLongMsg, midiOutShortMsg, OutputDebugString, PostMessage, PostThreadMessage, SetEvent, timeGetSystemTime, timeGetTime, timeKillEvent, and timeSetEvent.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Import Library: User-defined.

See Also

Musical Instrument Digital Interface (MIDI) Overview, MIDI Functions,