661 lines
26 KiB
HTML
661 lines
26 KiB
HTML
<HTML>
|
|
<BODY>
|
|
|
|
<H1>The BeOS R5 Midi Kit protocol</H1>
|
|
|
|
<P>In the course of writing the OpenBeOS Midi Kit, I spent some time looking at
|
|
how BeOS R5's libmidi2.so and midi_server communicate. Not out of a compulsion
|
|
to clone this protocol, but to learn from it. After all, the Be engineers spent
|
|
a lot of time thinking about this already, and it would be foolish not to build
|
|
on their experience. Here is what I have found out.</P>
|
|
|
|
<P>Two kinds of communication happen: administrative tasks and MIDI events. The
|
|
housekeeping stuff is done by sending BMessages between the BMidiRoster and the
|
|
midi_server. MIDI events are sent between producers and consumers using ports,
|
|
without intervention from the server.</P>
|
|
|
|
<P>This document describes the BMessage protocol. The protocol appears to be
|
|
asynchronous, which means that when BMidiRoster sends a message to the
|
|
midi_server, it does not wait around for a reply, even though the midi_server
|
|
replies to all messages. The libmidi2 functions <I>do</I> block until the reply
|
|
is received, though, so client code does not have to worry about any of
|
|
this.</P>
|
|
|
|
<P>Both BMidiRoster and the midi_server can initiate messages. BMidiRoster
|
|
typically sends a message when client code calls one of the functions from a
|
|
libmidi2 class. When the midi_server sends messages, it is to keep BMidiRoster
|
|
up-to-date about changes in the roster. BMidiRoster never replies to messages
|
|
from the server. The encoding of the BMessage 'what' codes indicates their
|
|
direction. The 'Mxxx' messages are sent from libmidi2 to the midi_server. The
|
|
'mXXX' messages go the other way around: from the server to a client.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>Who does what?</H2>
|
|
|
|
<P>The players here are the midi_server, which is a normal BApplication, and
|
|
all the client apps, also BApplications. The client apps have loaded a copy of
|
|
libmidi2 into their own address space. The main class from libmidi2 is
|
|
BMidiRoster. The BMidiRoster has a BLooper that communicates with the
|
|
midi_server's BLooper.</P>
|
|
|
|
<P>The midi_server keeps a list of <I>all</I> endpoints in the system, even
|
|
local, nonpublished, ones. Each BMidiRoster instance keeps its own list of
|
|
remote published endpoints, and all endpoints local to this application. It
|
|
does not know about remote endpoints that are not published yet.</P>
|
|
|
|
<P>Whenever you make a change to one of your own endpoints, your BMidiRoster
|
|
notifies the midi_server. If your endpoint is published, the midi_server then
|
|
notifies all of the other BMidiRosters, so they can update their local rosters.
|
|
It does <I>not</I> notify your own app! (Sometimes, however, the midi_server
|
|
also notifies everyone else even if your local endpoint is <I>not</I>
|
|
published. The reason for this escapes me, because the other BMidiRosters have
|
|
no access to those endpoints anyway.)</P>
|
|
|
|
<P>By the way, "notification" here means the internal communications between
|
|
server and libmidi, not the B_MIDI_EVENT messages you receive when you call
|
|
BMidiRoster::StartWatching().</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiRoster::MidiRoster()</H2>
|
|
|
|
<P>The first time it is called, this function creates the one-and-only instance
|
|
of BMidiRoster. Even if you don't explicitly call it yourself, it is used
|
|
behind-the-scenes anyway by any of the other BMidiRoster functions.
|
|
MidiRoster() constructs a BLooper and gets it running. Then it sends a
|
|
BMessenger with the looper's address to the midi_server:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mapp (0x4d617070, or 1298231408)
|
|
entry be:msngr, type='MSNG', c=1, size=24,
|
|
</SMALL></PRE>
|
|
|
|
<P>The server now responds with mOBJ messages for all <I>remote</I>
|
|
<I>published</I> producers and consumers. (Obviously, this list only contains
|
|
remote objects because by now you can't have created any local endpoints
|
|
yet.)</P>
|
|
|
|
<P>For a consumer this message looks like:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mOBJ (0x6d4f424a, or 1833910858)
|
|
entry be:consumer, type='LONG', c=1, size= 4, data[0]: 0x1 (1, '')
|
|
entry be:latency, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry be:port, type='LONG', c=1, size= 4, data[0]: 0x1dab (7595, '')
|
|
entry be:name, type='CSTR', c=1, size=16, data[0]: "/dev/midi/vbus0"
|
|
</SMALL></PRE>
|
|
|
|
<P>(Oddness: why is be:latency a LONG and not a LLNG? Since latency is
|
|
expressed in microseconds using a 64-bit bigtime_t, you'd expect the
|
|
midi_server to send all 64 of those bits... In the 'Mnew' message, on the other
|
|
hand, be:latency <I>is</I> a LLGN.)</P>
|
|
|
|
<P>And for a producer:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mOBJ (0x6d4f424a, or 1833910858)
|
|
entry be:producer, type='LONG', c=1, size= 4, data[0]: 0x2 (2, '')
|
|
entry be:name, type='CSTR', c=1, size=16, data[0]: "/dev/midi/vbus0"
|
|
</SMALL></PRE>
|
|
|
|
<P>Note that the be:name field is not present if the endpoint has no name. That
|
|
is, if the endpoint was constructed by passing a NULL name into the
|
|
BMidiLocalConsumer() or BMidiLocalProducer() constructor.</P>
|
|
|
|
<P>Next up are notifications for <I>all</I> connections, even those between
|
|
endpoints that are not registered:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mCON (0x6d434f4e, or 1833127758)
|
|
entry be:producer, type='LONG', c=1, size= 4, data[0]: 0x13 (19, '')
|
|
entry be:consumer, type='LONG', c=1, size= 4, data[0]: 0x14 (20, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>These messages are followed by an Msyn message:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = Msyn (0x4d73796e, or 1299413358)
|
|
</SMALL></PRE>
|
|
|
|
<P>And finally the (asynchronous) reply:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>Only after this reply is received, MidiRoster() returns.</P>
|
|
|
|
<P>The purpose of the Msyn message is not entirely clear. (Without it, Be's
|
|
libmidi2 blocks in the MidiRoster() call.) Does it signify the end of the list
|
|
of endpoints? Why doesn't libmidi2 simply wait for the final reply?</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiLocalProducer constructor</H2>
|
|
|
|
<P>BMidiRoster, on behalf of the constructor, sends the following to the
|
|
midi_server:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mnew (0x4d6e6577, or 1299080567)
|
|
entry be:type, type='CSTR', c=1, size=9, data[0]: "producer"
|
|
entry be:name, type='CSTR', c=1, size=21, data[0]: "MIDI Keyboard output"
|
|
</SMALL></PRE>
|
|
|
|
<P>The be:name field is optional.</P>
|
|
|
|
<P>The reply includes the ID for the new endpoint. This means that the
|
|
midi_server assigns the IDs, and any endpoint gets an ID whether it is
|
|
published or not.</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x11 (17, '')
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>Unlike many other Be API classes, BMidiLocalProducer and BMidiLocalConsumer
|
|
don't have an InitCheck() method. But under certain odd circumstances (such as
|
|
the midi_server not running), creating the endpoint might fail. How does client
|
|
code check for that? Well, it turns out that upon failure, the endpoint is
|
|
assigned ID 0, so you can check for that. In that case, the endpoint's refcount
|
|
is 0 and you should not Release() it. (That is stupid, actually, because
|
|
Release() is the only way that you can destroy the object. Our implementation
|
|
should bump the endpoint to 1 even on failure!)</P>
|
|
|
|
<P>If another app creates a new endpoint, your BMidiRoster is not notified. The
|
|
remote endpoint is not published yet, so your app is not supposed to see
|
|
it.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiLocalConsumer constructor</H2>
|
|
|
|
<P>This is similar to the BMidiLocalProducer constructor, although the contents
|
|
of the message differ slightly. Again, be:name is optional.</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mnew (0x4d6e6577, or 1299080567)
|
|
entry be:type, type='CSTR', c=1, size=9, data[0]: "consumer"
|
|
entry be:latency, type='LLNG', c=1, size= 8, data[0]: 0x0 (0, '')
|
|
entry be:port, type='LONG', c=1, size= 4, data[0]: 0x4c0 (1216, '')
|
|
entry be:name, type='CSTR', c=1, size=13, data[0]: "InternalMIDI"
|
|
</SMALL></PRE>
|
|
|
|
<P>And the reply:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x11 (17, '')
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>Before it sends the message to the server, the constructor creates a new
|
|
port with the name "MidiEventPort" and a queue length (capacity) of 1.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiEndpoint::Register()<BR>
|
|
BMidiRoster::Register()</H2>
|
|
|
|
<P>Sends the same message for producers and consumers:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mreg (0x4d726567, or 1299342695)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x17f (383, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>The reply:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>If you try to Register() an endpoint that is already registered, libmidi2
|
|
still sends the message. (Which could mean that BMidiRoster does not keep track
|
|
of this registered state.) The midi_server simply ignores that request, and
|
|
sends back error code 0 (B_OK). So the API does not flag this as an error.</P>
|
|
|
|
<P>If you send an invalid be:id, the midi_server returns error code -1 (General
|
|
OS Error, B_ERROR). If you try to Register() a remote endpoint, libmidi2
|
|
immediately returns error code -1, and does not send a message to the
|
|
server.</P>
|
|
|
|
<P>If another app Register()'s a producer, your BMidiRoster receives:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mOBJ (0x6d4f424a, or 1833910858)
|
|
entry be:producer, type='LONG', c=1, size= 4, data[0]: 0x17 (23, '')
|
|
entry be:name, type='CSTR', c=1, size=7, data[0]: "a name"
|
|
</SMALL></PRE>
|
|
|
|
<P>If the other app registers a consumer, your BMidiRoster
|
|
receives:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mOBJ (0x6d4f424a, or 1833910858)
|
|
entry be:consumer, type='LONG', c=1, size= 4, data[0]: 0x19 (25, '')
|
|
entry be:latency, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry be:port, type='LONG', c=1, size= 4, data[0]: 0xde9 (3561, '')
|
|
entry be:name, type='CSTR', c=1, size=7, data[0]: "a name"
|
|
</SMALL></PRE>
|
|
|
|
<P>These are the same messages you get when your BMidiRoster instance is
|
|
constructed. In both messages, the be:name field is optional again.</P>
|
|
|
|
<P>If the other app Register()'s the endpoint more than once, you still get
|
|
only one notification. So the midi_server simply ignores that second publish
|
|
request.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiEndpoint::Unregister()<BR>
|
|
BMidiRoster::Unregister()</H2>
|
|
|
|
<P>Sends the same message for producers and consumers:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Munr (0x4d756e72, or 1299541618)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x17f (383, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>The reply:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>If you try to Unregister() and endpoint that is already unregistered,
|
|
libmidi2 still sends the message. The midi_server simply ignores that request,
|
|
and sends back error code 0 (B_OK). So the API does not flag this as an error.
|
|
If you try to Unregister() a remote endpoint, libmidi2 immediately returns
|
|
error code -1, and does not send a message to the server.</P>
|
|
|
|
<P>When another app Unregister()'s one of its own endpoints, your BMidiRoster
|
|
receives:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mDEL (0x6d44454c, or 1833190732)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x17 (23, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>When the other app deletes that endpoint (refcount is now 0) and it is not
|
|
unregistered yet, your BMidiRoster also receives that mDEL message. Multiple
|
|
Unregisters() are ignored again by the midi_server.</P>
|
|
|
|
<P>If an app quits without properly cleaning up, i.e. it does not Unregister()
|
|
and Release() its endpoints, then the midi_server's roster contains a stale
|
|
endpoint. As soon as the midi_server recognizes this (for example, when an
|
|
application tries to connect that endpoint), it sends all BMidiRosters an mDEL
|
|
message for this endpoint. (This message is sent whenever the midi_server feels
|
|
like it, so libmidi2 can receive this message while it is still waiting for a
|
|
reply to some other message.) If the stale endpoint is still on the roster and
|
|
you (re)start your app, then you receive an mOBJ message for this endpoint
|
|
during the startup handshake. A little later you will receive the mDEL.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiEndpoint::Release()</H2>
|
|
|
|
<P>Only sends a message if the refcount of local objects (published or not)
|
|
becomes 0:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mdel (0x4d64656c, or 1298425196)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x17f (383, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>The corresponding reply:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>If you did not Unregister() a published endpoint before you Release()'d it,
|
|
no 'Munr' message is sent. Of course, the midi_server is smart enough to
|
|
realize that this endpoint should be wiped from the roster now. Likewise, if
|
|
this endpoint is connected to another endpoint, Release() will not send a
|
|
separate 'Mdis' message, but the server <I>will</I> disconnect them. (This, of
|
|
course, only happens when you Release() local objects. Releasing a proxy has no
|
|
impact on the connection with the real endpoint.)</P>
|
|
|
|
<P>When you Release() a proxy (a remote endpoint) and its refcount becomes 0,
|
|
libmidi2 does not send an 'Mdel' message to the server. After all, the object
|
|
is not deleted, just your proxy. If the remote endpoint still exists (i.e.
|
|
IsValid() returns true), the BMidiRoster actually keeps a cached copy of the
|
|
proxy object around, just in case you need it again. This means you can do
|
|
this: endp = NextEndpoint(); endp->Release(); (now refcount is 0) endp-
|
|
>Acquire(); (now refcount is 1 again). But I advice against that since it
|
|
doesn't work for all objects; local and dead remote endpoints <I>will</I> be
|
|
deleted when their refcount reaches zero.</P>
|
|
|
|
<P>In Be's implementation, if you Release() a local endpoint that already has a
|
|
zero refcount, libmidi still sends out the 'Mdel' message. It also drops you
|
|
into the debugger. (I think it should return an error code instead, it already
|
|
has a status_t.) However, if you Release() proxies a few times too many, your
|
|
app does not jump into the debugger. (Again, I think the return result should
|
|
be an error code here -- for OpenBeOS R1 I think we should jump into the
|
|
debugger just like with local objects). Hmm, actually, whether you end up in
|
|
the debugger depends on the contents of memory after the object is deleted,
|
|
because you perform the extra Release() on a dead object. Don't do that.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiEndpoint::SetName()</H2>
|
|
|
|
<P>For local endpoints, both unpublished and published, libmidi2 sends:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mnam (0x4d6e616d, or 1299079533)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x17f (383, '')
|
|
entry be:name, type='CSTR', c=1, size=7, data[0]: "b name"
|
|
</SMALL></PRE>
|
|
|
|
<P>And receives:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>You cannot rename remote endpoints. If you try, libmidi2 will simply ignore
|
|
your request. It does not send a message to the midi_server.</P>
|
|
|
|
<P>If another application renames one of its own endpoints, all other
|
|
BMidiRosters receive:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mREN (0x6d52454e, or 1834108238)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x5 (5, '')
|
|
entry be:name, type='CSTR', c=1, size=7, data[0]: "b name"
|
|
</SMALL></PRE>
|
|
|
|
<P>You receive this message even if the other app did not publish its endpoint.
|
|
This seems rather strange, because your BMidiRoster has no knowledge of this
|
|
particular endpoint yet, so what is it to do with this message? Ignore it, I
|
|
guess.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiEndpoint::GetProperties()</H2>
|
|
|
|
<P>For <I>any</I> kind of endpoint (local non-published, local published,
|
|
remote) libmidi2 sends the following message to the server:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mgpr (0x4d677072, or 1298624626)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x2b2 (690, '')
|
|
entry be:props, type='MSGG', c=1, size= 0,
|
|
</SMALL></PRE>
|
|
|
|
<P>(Why this "get properties" request includes a BMessage is a mistery to me.
|
|
The midi_server does not appear to copy its contents into the reply, which
|
|
would have made at least some sense. The BMessage from the client is completely
|
|
overwritten with the endpoint's properties.)</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:props, type='MSGG', c=1, size= 0,
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>This means that endpoint properties are stored in the server only, not
|
|
inside the BMidiEndpoints, and not by the local BMidiRosters.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiEndpoint::SetProperties()</H2>
|
|
|
|
<P>For local endpoints, published or not, libmidi2 sends the following message
|
|
to the server:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mspr (0x4d737072, or 1299411058)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x17f (383, '')
|
|
entry be:props, type='MSGG', c=1, size= 0,
|
|
</SMALL></PRE>
|
|
|
|
<P>And expects this back:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>You cannot change the properties of remote endpoints. If you try, libmidi2
|
|
will ignore your request. It does not send a message to the midi_server, and it
|
|
returns the -1 error code (B_ERROR).</P>
|
|
|
|
<P>If another application changes the properties of one of its own endpoints,
|
|
all other BMidiRosters receive:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mPRP (0x6d505250, or 1833980496)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x13 (19, '')
|
|
entry be:properties, type='MSGG', c=1, size= 0,
|
|
</SMALL></PRE>
|
|
|
|
<P>You receive this message even if the other app did not publish its
|
|
endpoint.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiLocalConsumer::SetLatency()</H2>
|
|
|
|
<P>For local endpoints, published or not, libmidi2 sends the following message
|
|
to the server:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mlat (0x4d6c6174, or 1298948468)
|
|
entry be:latency, type='LLNG', c=1, size= 8, data[0]: 0x3e8 (1000, '')
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x14f (335, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>And receives:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>If another application changes the latency of one of its own consumers, all
|
|
other BMidiRosters receive:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mLAT (0x6d4c4154, or 1833714004)
|
|
entry be:id, type='LONG', c=1, size= 4, data[0]: 0x15 (21, '')
|
|
entry be:latency, type='LLNG', c=1, size= 8, data[0]: 0x3e8 (1000, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>You receive this message even if the other app did not publish its
|
|
endpoint.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiProducer::Connect()</H2>
|
|
|
|
<P>The message:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mcon (0x4d636f6e, or 1298362222)
|
|
entry be:producer, type='LONG', c=1, size= 4, data[0]: 0x17f (383, '')
|
|
entry be:consumer, type='LONG', c=1, size= 4, data[0]: 0x376 (886, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>The answer:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>The server sends back a B_ERROR result if you specify wrong ID's. When you
|
|
try to connect a producer and consumer that are already connected to each
|
|
other, libmidi2 still sends the 'Mcon' message to the server (even though it
|
|
could have known these endpoints are already connected). In that case, the
|
|
server responds with a B_ERROR code as well.</P>
|
|
|
|
<P>When another app makes the connection, your BMidiRoster receives:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mCON (0x6d434f4e, or 1833127758)
|
|
entry be:producer, type='LONG', c=1, size= 4, data[0]: 0x13 (19, '')
|
|
entry be:consumer, type='LONG', c=1, size= 4, data[0]: 0x14 (20, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>Note: your BMidiRoster receives this notification even if the producer or
|
|
the consumer (or both) are not registered endpoints.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>BMidiProducer::Disconnect()</H2>
|
|
|
|
<P>The message:</P>
|
|
|
|
<PRE><SMALL>
|
|
OUT BMessage: what = Mdis (0x4d646973, or 1298426227)
|
|
entry be:producer, type='LONG', c=1, size= 4, data[0]: 0x309 (777, '')
|
|
entry be:consumer, type='LONG', c=1, size= 4, data[0]: 0x393 (915, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>The answer:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = (0x0, or 0)
|
|
entry be:result, type='LONG', c=1, size= 4, data[0]: 0x0 (0, '')
|
|
entry _previous_, ...
|
|
</SMALL></PRE>
|
|
|
|
<P>The server sends back a B_ERROR result if you specify wrong ID's. When you
|
|
try to disconnect a producer and consumer that are not connected to each other,
|
|
libmidi2 still sends the 'Mdis' message to the server (even though it could
|
|
have known these endpoints are not connected). In that case, the server
|
|
responds with a B_ERROR code as well.</P>
|
|
|
|
<P>When another app breaks the connection, your BMidiRoster receives:</P>
|
|
|
|
<PRE><SMALL>
|
|
IN BMessage: what = mDIS (0x6d444953, or 1833191763)
|
|
entry be:producer, type='LONG', c=1, size= 4, data[0]: 0x13 (19, '')
|
|
entry be:consumer, type='LONG', c=1, size= 4, data[0]: 0x14 (20, '')
|
|
</SMALL></PRE>
|
|
|
|
<P>Note: your BMidiRoster receives this notification even if the producer or
|
|
the consumer (or both) are not registered endpoints.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>Watchin'</H2>
|
|
|
|
<P>BMidiRoster::StartWatching() and StopWatching() do not send messages to the
|
|
midi_server. This means that the BMidiRoster itself, and not the midi_server,
|
|
sends the notifications to the messenger. It does this whenever it receives a
|
|
message from the midi_server.</P>
|
|
|
|
<P>The relationship between midi_server messages and B_MIDI_EVENT notifications
|
|
is as follows:</P>
|
|
|
|
<BLOCKQUOTE>
|
|
<TABLE BORDER="1">
|
|
<TR><TH>message</TH><TH>notification</TH></TR>
|
|
<TR><TD>mOBJ</TD><TD>B_MIDI_REGISTERED</TD></TR>
|
|
<TR><TD>mDEL</TD><TD> B_MIDI_UNREGISTERED </TD></TR>
|
|
<TR><TD>mCON</TD><TD>B_MIDI_CONNECTED</TD></TR>
|
|
<TR><TD>mDIS</TD><TD>B_MIDI_DISCONNECTED</TD></TR>
|
|
<TR><TD>mREN</TD><TD>B_MIDI_CHANGED_NAME</TD></TR>
|
|
<TR><TD>mLAT</TD><TD>B_MIDI_CHANGED_LATENCY</TD></TR>
|
|
<TR><TD>mPRP</TD><TD>B_MIDI_CHANGED_PROPERTIES</TD></TR>
|
|
</TABLE>
|
|
</BLOCKQUOTE>
|
|
|
|
<P>For each message on the left, the watcher will receive the corresponding
|
|
notification on the right.</P>
|
|
|
|
<HR SIZE="1">
|
|
|
|
<H2>Other observations</H2>
|
|
|
|
<P>Operations that do not send messages to the midi_server:</P>
|
|
|
|
<UL>
|
|
|
|
<LI><P>BMidiEndpoint::Acquire(). This means reference counting is done locally
|
|
by BMidiRoster. Release() doesn't send a message either, unless the refcount
|
|
becomes 0 and the object is deleted. (Which suggests that it is actually the
|
|
destructor and not Release() that sends the message.)</P></LI>
|
|
|
|
<LI><P>BMidiRoster::NextEndpoint(), NextProducer(), NextConsumer(),
|
|
FindEndpoint(), FindProducer(), FindConsumer(). None of these functions send
|
|
messages to the midi_server. This means that each BMidiRoster instance keeps
|
|
its own list of available endpoints. This is why it receives 'mOBJ' messages
|
|
during the startup handshake, and whenever a new remote endpoint is registered,
|
|
and 'mDEL' messages for every endpoint that disappears. Even though the
|
|
NextXXX() functions do not return locally created objects, this "local roster"
|
|
<I>does</I> keep track of them, since FindXXX() <I>do</I> return local
|
|
endpoints.</P></LI>
|
|
|
|
<LI><P>BMidiEndpoint::Name(), ID(), IsProducer(), IsConsumer(), IsRemote(),
|
|
IsLocal() IsPersistent(). BMidiConsumer::Latency().
|
|
BMidiLocalConsumer::GetProducerID(), SetTimeout(). These all appear to consult
|
|
BMidiRoster's local roster.</P></LI>
|
|
|
|
<LI><P>BMidiEndpoint::IsValid(). This function simply looks at BMidiRoster's
|
|
local roster to see whether the remote endpoint is still visible, i.e. not
|
|
unregistered. It does not determine whether the endpoint's application is still
|
|
alive, or "ping" the endpoint or anything fancy like that.</P></LI>
|
|
|
|
<LI><P>BMidiProducer::IsConnected(), Connections(). This means that
|
|
BMidiRoster's local roster, or maybe the BMidiProducers themselves (including
|
|
the proxies) keep track of the various connections.</P></LI>
|
|
|
|
<LI><P>BMidiLocalProducer::Connected(), Disconnected(). These methods are
|
|
invoked when any app (including your own) makes or breaks a connection on one
|
|
of your local producers. These hooks are invoked before the B_MIDI_EVENT
|
|
messages are sent to any watchers.</P></LI>
|
|
|
|
<LI><P>Quitting your app. Even though the BMidiRoster instance is deleted when
|
|
the app quits, it does not let the midi_server know that the application in
|
|
question is now gone. Any endpoints you have registered are not automatically
|
|
unregistered. This means that the midi_server is left with some stale
|
|
information. Undoubtedly, there is a mechanism in place to clean this up. The
|
|
same mechanism would be used to clean up apps that did not exit cleanly, or
|
|
that crashed.</P></LI>
|
|
|
|
</UL>
|
|
|
|
<P>Other stuff:</P>
|
|
|
|
<UL>
|
|
|
|
<LI><P>libmidi2.so exports an int32 symbol called "midi_debug_level". If you
|
|
set it to a non-zero value, libmidi2 will dump a lot of interesting debug info
|
|
on stdout. To do this, declare the variable in your app with "extern int32
|
|
midi_debug_level;", and then set it to some high value later: "midi_debug_level
|
|
= 0x7FFFFFFF;" Now run your app from a Terminal and watch libmidi2 do its
|
|
thing.</P></LI>
|
|
|
|
<LI><P>libmidi2.so also exports an int32 symbol called
|
|
"midi_dispatcher_priority". This is the runtime priority of the thread that
|
|
fields MIDI events to consumers.</P></LI>
|
|
|
|
</UL>
|
|
|
|
</BODY>
|
|
</HTML>
|