README for PortMidi
Roger Dannenberg

VERSION: this is the 17-Jan-07 version of PortMidi.

Documentation for PortMidi is found in pm_common/portmidi.h.

Additional documentation:
  - Windows: see pm_win/README_WIN.txt and pm_win/debugging_dlls.txt
  - Linux: see pm_linux/README_LINUX.txt
  - Mac OSX: see pm_mac/README_MAC.txt
  - Common Lisp: see pm_cl/README_CL.txt

---------- some notes on the design of PortMidi ----------

POINTERS VS DEVICE NUMBERS

When you open a MIDI port, PortMidi allocates a structure to
maintain the state of the open device. Since every device is
also listed in a table, you might think it would be simpler to
use the table index rather than a pointer to identify a device.
This would also help with error checking (it's hard to make
sure a pointer is valid). PortMidi's design parallels that of
PortAudio.

ERROR HANDLING

Error handling turned out to be much more complicated than expected.
PortMidi functions return error codes that the caller can check.
In addition, errors may occur asynchronously due to MIDI input. 
However, for Windows, there are virtually no errors that can
occur if the code is correct and not passing bogus values. One
exception is an error that the system is out of memory, but my
guess is that one is unlikely to recover gracefully from that.
Therefore, all errors in callbacks are guarded by assert(), which
means not guarded at all in release configurations.

Ordinarily, the caller checks for an error code. If the error is
system-dependent, pmHostError is returned and the caller can
call Pm_GetHostErrorText to get a text description of the error.

Host error codes are system-specific and are recorded in the 
system-specific data allocated for each open MIDI port. 
However, if an error occurs on open or close,
we cannot store the error with the device because there will be
no device data (assuming PortMidi cleans up after devices that
are not open). For open and close, we will convert the error
to text, copy it to a global string, and set pm_hosterror, a
global flag.

Similarly, whenever a Read or Write operation returns pmHostError,
the corresponding error string is copied to a global string
and pm_hosterror is set. This makes getting error strings
simple and uniform, although it does cost a string copy and some
overhead even if the user does not want to look at the error data.

The system-specific Read, Write, Poll, etc. implementations should
check for asynchronous errors and return immediately if one is
found so that these get reported. This happens in the Mac OS X 
code, where lots of things are happening in callbacks, but again,
in Windows, there are no error codes recorded in callbacks.

DEBUGGING

If you are building a console application for research, we suggest
compiling with the option PM_CHECK_ERRORS. This will insert a
check for error return values at the end of each PortMidi 
function. If an error is encountered, a text message is printed
using printf(), the user is asked to type ENTER, and then exit(-1)
is called to clean up and terminate the program.

You should not use PM_CHECK_ERRORS if printf() does not work
(e.g. this is not a console application under Windows, or there
is no visible console on some other OS), and you should not use
PM_CHECK_ERRORS if you intend to recover from errors rather than
abruptly terminate the program.

The Windows version (and perhaps others) also offers a DEBUG
compile-time option. See README_WIN.txt.