This documentation is converted to docbook.
Check the trunk/src/documentation/haiku_book subdir. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@18791 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
@@ -1,292 +0,0 @@
|
||||
/*!
|
||||
\class BMidiRoster MidiRoster.h
|
||||
\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
|
||||
|
||||
\sa \ref bmidiop "The possible be:op codes (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.
|
||||
|
||||
*/
|
||||
Reference in New Issue
Block a user