Reading and Writing Midi Messages

Functions
int	Pm_Read (PortMidiStream *stream, PmEvent *buffer, long length)
	Pm_Read() retrieves midi data into a buffer, and returns the number of events read.
PmError	Pm_Poll (PortMidiStream *stream)
	Pm_Poll() tests whether input is available, returning TRUE, FALSE, or an error value.
PmError	Pm_Write (PortMidiStream *stream, PmEvent *buffer, long length)
	Pm_Write() writes midi data from a buffer.
PmError	Pm_WriteShort (PortMidiStream *stream, PmTimestamp when, long msg)
	Pm_WriteShort() writes a timestamped non-system-exclusive midi message.
PmError	Pm_WriteSysEx (PortMidiStream *stream, PmTimestamp when, unsigned char *msg)
	Pm_WriteSysEx() writes a timestamped system-exclusive midi message.

---

Function Documentation

int Pm_Read	(	PortMidiStream *	stream,
		PmEvent *	buffer,
		long	length
	)

Pm_Read() retrieves midi data into a buffer, and returns the number of events read.

Result is a non-negative number unless an error occurs, in which case a PmError value will be returned.

Buffer Overflow

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 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.

Definition at line 352 of file portmidi.c.

PmError Pm_Write	(	PortMidiStream *	stream,
		PmEvent *	buffer,
		long	length
	)

Pm_Write() writes midi data from a buffer.

This may contain:

• short messages or
• 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.

Definition at line 443 of file portmidi.c.

References PmEvent::message, and PmEvent::timestamp.

Referenced by Pm_WriteShort(), and Pm_WriteSysEx().

PmError Pm_WriteShort	(	PortMidiStream *	stream,
		PmTimestamp	when,
		long	msg
	)

Pm_WriteShort() writes a timestamped non-system-exclusive midi message.

Messages are delivered in order as received, and timestamps must be non-decreasing. (But timestamps are ignored if the stream was opened with latency = 0.)

Definition at line 576 of file portmidi.c.

References Pm_Write().