The MMA never officially adopted the "Channel Number" and "Port Number" Meta-events
that I described in the "MIDI File Specification" article on my web site. Rather,
these were some Meta-Events that Cakewalk, and a couple other companies, decided to
conjure up and add to their MIDI files. After all, there needed to be some way to
save this information in a MIDI file, and there was no officially-sanctioned Meta-Events
for this purpose. More recently, the MMA came up with a "Device (Port) Name" Meta-Event
to replace the use of these two unofficial Meta-Events. The Port Name Meta-Event contains
the actual name of a port, for example "MIDI Out #1". Contrast this to the old, Port
Number Meta-Event which contained only a port number. If the user changed around his
system, adding a new MIDI card or even a software synth, the ports could get reassigned
to different port numbers. Loading a previously saved MIDI file could cause that file's
Port Number Meta-Events to be referencing the wrong ports. But by using a Port Name
Meta-Event instead, you can always look up that port by name, and therefore ensure that
you have the correct port.

I have changed the way the MIDIFILE.DLL utilizes the MetaPort Callback, in order to now
support the Port Name Meta-Event, hopefully in a way that is transparent to older programs
that use only the now-obsolete Port Number Meta-Event.

When loading a MIDI file: If you supply a MetaPort Callback, then whenever MIDIFILE
encounters a Port Name Meta-Event, it attempts to look that name up in the list of
installed MIDI Out devices on the computer. If it finds such a matching name, it
substitutes a Port Number Meta-Event with the PortNumber field set to that device's ID.
(This would be the ID used with midiOutOpen()). It passes this Port Number Meta-Event
to your MetaPort Callback, just as if it were a MIDI file with the now-obsolete Port Number
event. In other words, MIDIFILE internally converts the new Port Name event to an old Port
Number event, doing the checking for this port's existence.

If there isn't a matching MIDI Out name, then MIDIFILE passes that Port Name Meta-Event to
any MetaText callback you have. In this case, you'll have to figure out what to do with
a port name that doesn't exist upon the system. I recommend substituting MIDI_MAPPER for
that port.

So, supplying a MetaPort Callback can be useful for new programs too. After all, MIDIFILE
does the work that you yourself would have to do -- looking up the port name and determining
which port it is. And in the event that MIDIFILE can't find an existing port, it then passes
on the Port Name to your MetaText Callback so that you can determine what to do with it.

As an improved feature, if MIDIFILE does encounter an old Meta-Port event in a MIDI file, it
checks whether the port number exists upon the computer. If not, it sets the port number to
-1 (ie, MIDI_MAPPER). So for example, if a computer has only 1 port, and MIDIFILE encounters
a Port Number event referencing a port number of 3, then MIDIFILE passes to your MetaPort
callback a PortNumber of -1.

When saving a MIDI file, if you tell MIDIFILE to save a Port Number Meta-Event, it will
instead look up that port's name in the list of MIDI Out devices on the computer, and if
found, save a Port Name Meta-Event instead. So MIDIFILE now internally converts old Port
Number Meta-Events to the new Port Name Meta-Event.

Again, this could be useful to a new program if you don't want to keep track of names, and
instead use Port numbers internally. MIDIFILE will take care of looking up the proper name
for the Port Name Meta-Event.

If you don't want MIDIFILE to monkey with the new Port Name events, and you want to handle
them all yourself, then do not supply a MetaPort callback. MIDIFILE will consequently be
forced to pass *all* Port Name events to your MetaText Callback. Of course, you'll lose any
Port Number events in older MIDI files. But since those are now obsolete, that shouldn't be
a problem. (Or you could use MIDI File Disassembler to disassemble these files, and then
immediately reassemble them. MIDI File Disassembler will replace old Port Number events with
new Port Name events).

Also, the MMA has added a new "Program Name" Meta-Event. This will, as before, be sent to
your MetaText Callback when loading a MIDI file.

This new ZIP archive includes the new MIDIFILE.DLL and MIDIFILE.H. It also includes update
MFWRITE\MFWRITE.C, MFREAD\MFREAD.C, MFCREAD\MFCMIDIFILE.CPP, and MFCWRITE\MFCMIDIFILE.CPP
to reflect displaying the new "Device Name" and "Program Name" Meta-Events. (I also caught
a bug in MfcRead and MfRead where they didn't display the last hex byte on a Text event's
data). Furthermore, since a new error message had to be added to MIDIFILE.DLL, I have
updated the MFREAD.RTF help file to include a _BADMEM entry. You should add this to any
help book for your own app. There is also a new MIDIFILE.HLP book. I also forgot to include
the icon files with MfcRead and MfcWrite in the older ZIP archive. Those are now included.

Actually the ZIP archive contains the whole distribution, but the other files haven't changed.
