Reading and Writing Midi Messages

Functions
PMEXPORT int	Pm_Read (PortMidiStream *stream, PmEvent *buffer, int32_t length)
	Retrieve midi data into a buffer. More...
PMEXPORT PmError	Pm_Poll (PortMidiStream *stream)
	Test whether input is available. More...
PMEXPORT PmError	Pm_Write (PortMidiStream *stream, PmEvent *buffer, int32_t length)
	Write MIDI data from a buffer. More...
PMEXPORT PmError	Pm_WriteShort (PortMidiStream *stream, PmTimestamp when, PmMessage msg)
	Write a timestamped non-system-exclusive midi message. More...
PMEXPORT PmError	Pm_WriteSysEx (PortMidiStream *stream, PmTimestamp when, unsigned char *msg)
	Write a timestamped system-exclusive midi message. More...

Detailed Description

Function Documentation

Pm_Poll()

PMEXPORT PmError Pm_Poll

(

PortMidiStream *

stream

)

Test whether input is available.

Parameters

stream

an open input stream.

Returns

TRUE, FALSE, or an error value.

If there was an asynchronous error, pmHostError is returned and you must call again to determine if input is (also) available.

You should probably not use this function. Call Pm_Read() instead. If it returns 0, then there is no data available. It is possible for Pm_Poll() to return TRUE before the complete message is available, so Pm_Read() could return 0 even after Pm_Poll() returns TRUE. Only call Pm_Poll() if you want to know that data is probably available even though you are not ready to receive data.

Pm_Read()

PMEXPORT int Pm_Read	(	PortMidiStream *	stream,
		PmEvent *	buffer,
		int32_t	length
	)

Retrieve midi data into a buffer.

Parameters

stream

the open input stream.

Returns

the number of events read, or, if the result is negative, a PmError value will be returned.

The Buffer Overflow Problem

The problem: if an input overflow occurs, data will be lost, ultimately because there is no flow control all the way back to the data source. When data is lost, the receiver should be notified and some sort of graceful recovery should take place, e.g. you shouldn't resume receiving in the middle of a long sysex message.

With a lock-free fifo, which is pretty much what we're stuck with to enable portability to the Mac, it's tricky for the producer and consumer to synchronously reset the buffer and resume normal operation.

Solution: the entire buffer managed by PortMidi will be flushed when an overflow occurs. The consumer (Pm_Read()) gets an error message (#pmBufferOverflow) and ordinary processing resumes as soon as a new message arrives. The remainder of a partial sysex message is not considered to be a "new message" and will be flushed as well.

Pm_Write()

PMEXPORT PmError Pm_Write	(	PortMidiStream *	stream,
		PmEvent *	buffer,
		int32_t	length
	)

Write MIDI data from a buffer.

Parameters

stream	an open output stream.
buffer	(address of) an array of MIDI event data.
length	the length of the buffer.

Returns

TRUE, FALSE, or an error value.

buffer may contain:

• short messages
• sysex messages that are converted into a sequence of PmEvent structures, e.g. sending data from a file or forwarding them from midi input.

Use Pm_WriteSysEx() to write a sysex message stored as a contiguous array of bytes.

Sysex data may contain embedded real-time messages.

buffer is managed by the caller. The buffer may be destroyed as soon as this call returns.

Pm_WriteShort()

PMEXPORT PmError Pm_WriteShort	(	PortMidiStream *	stream,
		PmTimestamp	when,
		PmMessage	msg
	)

Write a timestamped non-system-exclusive midi message.

Parameters

stream	an open output stream.
when	timestamp for the event.
msg	the data for the event.

Returns

pmNoError or an error code.

Messages are delivered in order, and timestamps must be non-decreasing. (But timestamps are ignored if the stream was opened with latency = 0, and otherwise, non-decreasing timestamps are "corrected" to the lowest valid value.)

Pm_WriteSysEx()

PMEXPORT PmError Pm_WriteSysEx	(	PortMidiStream *	stream,
		PmTimestamp	when,
		unsigned char *	msg
	)

Write a timestamped system-exclusive midi message.

Parameters

stream	an open output stream.
when	timestamp for the event.
msg	the sysex message, terminated with an EOX status byte.

Returns

pmNoError or an error code.

msg is managed by the caller and may be destroyed when this call returns.