mirror of
https://review.haiku-os.org/haiku
synced 2025-02-02 03:36:14 +01:00
089b7ad4c6
I will keep working on the Docbook version, but as I'm still not completely comfortable with that as final choice, I'm playing around with this as well. The String.cpp file contained doxygen documentation for almost all methods, I copied those to a new file (string.dox) and grouped them accordingly. (Done because Axel is absolutely against in-header or in-source docs) Integrated the BMidiConsumer and BMidiLocalConsumer class into the same file (like I did now to the producers), since I think it's better to keep a 1:1 relation with the headers. Removed the mididefs.dox file and replaced it with the midi2/Midi2Defs.dox file which actually documents the Midi2Defs.h file, rather than contain a custom page that was somewhat hard to find. Please see http://www.myhouserules.nl/haiku_book/index.html for a generated book from the current source. I actually quite like the output so far, though I'm aware of the fact that I needed to perform some tricks to let Doxygen get to this point. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@19651 a95241bf-73f2-0310-859d-f6bbb57e9c96
304 lines
9.6 KiB
Plaintext
304 lines
9.6 KiB
Plaintext
/*!
|
|
\class BMidiRoster MidiRoster.h
|
|
\ingroup midi2
|
|
\ingroup libmidi2
|
|
\brief Interface to the system-wide Midi Roster
|
|
|
|
BMidiRoster allows you to find available MIDI consumer and producer objects.
|
|
You can locate these objects using the iterative NextEndpoint(),
|
|
NextProducer(), and NextConsumer() methods or by requesting notification
|
|
messages to be sent with StartWatching(). Notification messages may contain
|
|
object IDs which can be resolved using the FindEndpoint(), FindProducer(), and
|
|
FindConsumer() methods.
|
|
|
|
The constructor and destructor of BMidiRoster are private, which means that you
|
|
cannot create or delete your own BMidiRoster objects. Every application can
|
|
have only one instance of BMidiRoster, which is automatically created the very
|
|
first time you use a Midi Kit function.
|
|
|
|
You can call BMidiRoster's functions like this:
|
|
|
|
\code
|
|
producer = BMidiRoster::FindProducer(someID);
|
|
\endcode
|
|
|
|
Or using the slightly more annoying:
|
|
|
|
\code
|
|
BMidiRoster* roster = BMidiRoster::MidiRoster();
|
|
if (roster != NULL)
|
|
{
|
|
producer = roster->FindProducer(someID);
|
|
}
|
|
\endcode
|
|
*/
|
|
|
|
/*!
|
|
\fn BMidiEndpoint* BMidiRoster::NextEndpoint(int32* id)
|
|
\brief Returns the next endpoint from the roster
|
|
|
|
The "next endpoint" means: the endpoint with the ID that follows id. So if you
|
|
set id to 3, the first possible endpoint it returns is endpoint 4. No endpoint
|
|
can have ID 0, so passing 0 gives you the first endpoint. If you pass NULL
|
|
instead of an ID, NextEndpoint() always returns NULL. When the function
|
|
returns, it sets id to the ID of the endpoint that was found. If no more
|
|
endpoints exist, NextEndpoint() returns NULL and id is not changed.
|
|
NextEndpoint() does <I>not</I> return locally created endpoints, even if they
|
|
are Register()'ed.
|
|
|
|
Usage example:
|
|
|
|
\code
|
|
int32 id = 0;
|
|
BMidiEndpoint* endp;
|
|
while ((endp = BMidiRoster::NextEndpoint(&id)) != NULL)
|
|
{
|
|
...do something with endpoint ...
|
|
endp->Release(); // don't forget!
|
|
}
|
|
\endcode
|
|
|
|
Remember that NextEndpoint() bumps the endpoint's reference count, so you
|
|
should always \link BMidiEndpoint::Release() Release() \endlink it when you are
|
|
done.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\fn BMidiProducer* BMidiRoster::NextProducer(int32* id)
|
|
\brief Returns the next producer from the roster
|
|
|
|
Like NextEndpoint(), but only returns producer endpoints.
|
|
|
|
\sa NextConsumer
|
|
\sa NextEndpoint
|
|
*/
|
|
|
|
/*!
|
|
\fn BMidiConsumer* BMidiRoster::NextConsumer(int32* id)
|
|
\brief Returns the next consumer from the roster
|
|
|
|
Like NextEndpoint(), but only returns consumer endpoints.
|
|
|
|
\sa NextProducer
|
|
\sa NextEndpoint
|
|
*/
|
|
|
|
/*!
|
|
\fn BMidiEndpoint* BMidiRoster::FindEndpoint(
|
|
int32 id, bool localOnly = false)
|
|
\brief Returns the endpoint with the specified ID
|
|
|
|
FindEndpoint() will always find <I>any</I> local endpoints created by this
|
|
application; they do not have to be published with Register() first. If
|
|
localOnly is false, FindEndpoint() also looks at remote endpoints, otherwise
|
|
only local endpoints will be resolved. Returns NULL if no such endpoint could
|
|
be found.
|
|
|
|
You should use a dynamic_cast to convert the BMidiEndpoint into a producer or
|
|
consumer:
|
|
|
|
\code
|
|
BMidiEndpoint* endp = ...;
|
|
BMidiProducer* prod = NULL;
|
|
BMidiConsumer* cons = NULL;
|
|
|
|
if (endp->IsProducer())
|
|
{
|
|
prod = dynamic_cast<BMidiProducer*>(endp);
|
|
}
|
|
else if (endp->IsConsumer())
|
|
{
|
|
cons = dynamic_cast<BMidiConsumer*>(endp);
|
|
}
|
|
\endcode
|
|
|
|
Remember that FindEndpoint() increments the endpoint's reference count, so you
|
|
should always \link BMidiEndpoint::Release() Release() \endlink an endpoint
|
|
when you are done with it:
|
|
|
|
\code
|
|
BMidiEndpoint* endp = BMidiRoster::FindEndpoint(someID);
|
|
if (endp != NULL)
|
|
{
|
|
...do stuff with the endpoint...
|
|
endp->Release();
|
|
}
|
|
\endcode
|
|
|
|
*/
|
|
|
|
/*!
|
|
\fn BMidiProducer* BMidiRoster::FindProducer(
|
|
int32 id, bool localOnly = false)
|
|
\brief Finds the producer with the specified ID
|
|
|
|
Like FindEndpoint(), but only looks for producer endpoints. Returns NULL if no
|
|
endpoint with that ID exists, or if that endpoint is not a producer.
|
|
|
|
\sa FindConsumer
|
|
\sa FindEndpoint
|
|
*/
|
|
|
|
/*!
|
|
\fn BMidiConsumer* BMidiRoster::FindConsumer(
|
|
int32 id, bool localOnly = false)
|
|
\brief Finds the consumer with the specified ID
|
|
|
|
Like FindEndpoint(), but only looks for consumer endpoints. Returns NULL if no
|
|
endpoint with that ID exists, or if that endpoint is not a consumer.
|
|
|
|
\sa FindProducer
|
|
\sa FindEndpoint
|
|
*/
|
|
|
|
/*!
|
|
\fn void BMidiRoster::StartWatching(const BMessenger* msngr)
|
|
\brief Start receiving notifications from the Midi Roster
|
|
|
|
When you start watching, BMidiRoster sends you notifications for all currently
|
|
<I>published</I> <I>remote</I> endpoints, and all the current connections
|
|
between them. (At this point, BMidiRoster does not let you know about
|
|
connections between unpublished endpoints, nor does it tell you anything about
|
|
your local endpoints, even though they may be published.)
|
|
|
|
Thereafter, you'll receive notifications any time something important happens
|
|
to an object. The application that performs these operations is itself not
|
|
notified. The assumption here is that you already know about these changes,
|
|
because you are the one that is performing them.
|
|
|
|
The notifications are BMessages with code B_MIDI_EVENT. You specify the
|
|
BMessenger that will be used to send these messages. Each message contains a
|
|
field called be:op that describes the type of notification.
|
|
|
|
The "registered" and "unregistered" notifications are sent when a remote
|
|
endpoint Register()'s or Unregister()'s, respectively. You don't receive these
|
|
notifications when you register or unregister your local endpoints, but the
|
|
other apps will.
|
|
|
|
<TABLE BORDER="1">
|
|
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_REGISTERED</TD></TR>
|
|
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
|
|
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
|
|
</TABLE>
|
|
|
|
<TABLE BORDER="1">
|
|
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_UNREGISTERED</TD></TR>
|
|
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
|
|
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
|
|
</TABLE>
|
|
|
|
The "connected" and "disconnected" notifications are sent when a consumer \link
|
|
BMidiProducer::Connect() Connect()\endlink's to a producer, or when they \link
|
|
BMidiProducer::Disconnect() Disconnect() \endlink. You will receive these
|
|
notifications when <I>any</I> two endpoints connect or disconnect, even if they
|
|
are not published. (The purpose of which is debatable.) You won't receive the
|
|
notifications if you are the one making the connection, even if both endpoints
|
|
are remote. You <I>will</I> be notified when another app connects one of your
|
|
published endpoints.
|
|
|
|
<TABLE BORDER="1">
|
|
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CONNECTED</TD></TR>
|
|
<TR><TD>be:producer</TD><TD>int32</TD><TD>ID of the connector</TD></TR>
|
|
<TR><TD>be:consumer</TD><TD>int32</TD><TD>ID of the connectee</TD></TR>
|
|
</TABLE>
|
|
|
|
<TABLE BORDER="1">
|
|
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_DISCONNECTED</TD></TR>
|
|
<TR><TD>be:producer</TD><TD>int32</TD><TD>ID of the connector</TD></TR>
|
|
<TR><TD>be:consumer</TD><TD>int32</TD><TD>ID of the connectee</TD></TR>
|
|
</TABLE>
|
|
|
|
The following notifications are sent when an endpoint's attributes are changed.
|
|
You receive these notifications only if another application is changing one of
|
|
its published endpoints.
|
|
|
|
<TABLE BORDER="1">
|
|
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_NAME</TD></TR>
|
|
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
|
|
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
|
|
<TR><TD>be:name</TD><TD>string</TD><TD>the endpoint's new name</TD></TR>
|
|
</TABLE>
|
|
|
|
<TABLE BORDER="1">
|
|
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_LATENCY</TD></TR>
|
|
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
|
|
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
|
|
<TR><TD>be:latency</TD><TD>int64</TD><TD>the new latency (microseconds)</TD></TR>
|
|
</TABLE>
|
|
|
|
<TABLE BORDER="1">
|
|
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_PROPERTIES</TD></TR>
|
|
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
|
|
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
|
|
<TR><TD>be:properties</TD><TD>BMessage</TD><TD>the new properties</TD></TR>
|
|
</TABLE>
|
|
|
|
Typical usage example:
|
|
|
|
\code
|
|
void MyView::AttachedToWindow()
|
|
{
|
|
BMessenger msgr(this);
|
|
BMidiRoster::StartWatching(&msgr);
|
|
}
|
|
|
|
void MyView::MessageReceived(BMessage* msg)
|
|
{
|
|
switch (msg->what)
|
|
{
|
|
case B_MIDI_EVENT:
|
|
HandleMidiEvent(msg);
|
|
break;
|
|
default:
|
|
super::MessageReceived(msg);
|
|
break;
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
For the possible midi options, see #BMidiOp
|
|
*/
|
|
|
|
/*!
|
|
\fn void BMidiRoster::StopWatching()
|
|
\brief Stop receiving notifications from the Midi Roster
|
|
\sa StartWatching()
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t BMidiRoster::Register(BMidiEndpoint* object)
|
|
\brief Publishes an endpoint to other applications
|
|
|
|
Calls BMidiEndpoint's \link BMidiEndpoint::Register() Register() \endlink
|
|
method to publish an endpoint, which makes it visible to other applications.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\fn status_t BMidiRoster::Unregister(BMidiEndpoint* object)
|
|
\brief Hides an endpoint from other applications
|
|
|
|
Calls BMidiEndpoint's \link BMidiEndpoint::Unregister() Unregister() \endlink
|
|
method to hide a previously published endpoint from other applications.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\fn BMidiRoster* BMidiRoster::MidiRoster()
|
|
\brief Returns a pointer to the only instance of BMidiRoster
|
|
|
|
There is no real reason use this function, since all BMidiRoster's public
|
|
function are static.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\enum BMidiOp
|
|
\brief Defines the status codes for MIDI Server notification messages.
|
|
|
|
These codes are used when you request notification as in BMidiRoster::StartWatching().
|
|
Check against these codes to determine what is happening. See the StartWatching() method
|
|
for a more complete description of the codes and their meaning.
|
|
*/
|