BMidiRoster Class Reference

Interface to the system-wide Midi Roster. More...

#include <MidiRoster.h>

Static Public Member Functions
static BMidiConsumer *	FindConsumer (int32 id, bool localOnly=false)
	Finds the consumer with the specified id.
static BMidiEndpoint *	FindEndpoint (int32 id, bool localOnly=false)
	Returns the endpoint with the specified id.
static BMidiProducer *	FindProducer (int32 id, bool localOnly=false)
	Finds the producer with the specified id.
static BMidiRoster *	MidiRoster ()
	Returns a pointer to the only instance of BMidiRoster.
static BMidiConsumer *	NextConsumer (int32 *id)
	Returns the next consumer from the roster.
static BMidiEndpoint *	NextEndpoint (int32 *id)
	Returns the next endpoint from the roster.
static BMidiProducer *	NextProducer (int32 *id)
	Returns the next producer from the roster.
static status_t	Register (BMidiEndpoint *endp)
	Publishes an endpoint to other applications.
static void	StartWatching (const BMessenger *msngr)
	Start receiving notifications from the Midi Roster.
static void	StopWatching ()
	Stop receiving notifications from the Midi Roster.
static status_t	Unregister (BMidiEndpoint *endp)
	Hides an endpoint from other applications.

Detailed Description

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:

producer = BMidiRoster::FindProducer(someID);

Or using the slightly more annoying:

BMidiRoster* roster = BMidiRoster::MidiRoster();
if (roster != NULL)
{
    producer = roster->FindProducer(someID);
}

Member Function Documentation

FindConsumer()

BMidiConsumer * BMidiRoster::FindConsumer ( int32  id, bool  localOnly = false  )

static

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.

See also

FindProducer

FindEndpoint

FindEndpoint()

BMidiEndpoint * BMidiRoster::FindEndpoint ( int32  id, bool  localOnly = false  )

static

Returns the endpoint with the specified id.

FindEndpoint() will always find any 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:

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);
}

Remember that FindEndpoint() increments the endpoint's reference count, so you should always Release() an endpoint when you are done with it:

BMidiEndpoint* endp = BMidiRoster::FindEndpoint(someID);
if (endp != NULL)
{
    ...do stuff with the endpoint...
    endp->Release();
}

FindProducer()

BMidiProducer * BMidiRoster::FindProducer ( int32  id, bool  localOnly = false  )

static

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.

See also

FindConsumer

FindEndpoint

MidiRoster()

BMidiRoster * BMidiRoster::MidiRoster ( )

static

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.

NextConsumer()

BMidiConsumer * BMidiRoster::NextConsumer ( int32 *  id )

static

Returns the next consumer from the roster.

Like NextEndpoint(), but only returns consumer endpoints.

See also

NextProducer

NextEndpoint

NextEndpoint()

BMidiEndpoint * BMidiRoster::NextEndpoint ( int32 *  id )

static

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 not return locally created endpoints, even if they are Register()'ed.

Usage example:

int32 id = 0;
BMidiEndpoint* endp;
while ((endp = BMidiRoster::NextEndpoint(&id)) != NULL)
{
    ... do something with endpoint ...
    endp->Release();  // don't forget!
}

Remember that NextEndpoint() bumps the endpoint's reference count, so you should always Release() it when you are done.

NextProducer()

BMidiProducer * BMidiRoster::NextProducer ( int32 *  id )

static

Returns the next producer from the roster.

Like NextEndpoint(), but only returns producer endpoints.

See also

NextConsumer

NextEndpoint

Register()

status_t BMidiRoster::Register ( BMidiEndpoint *  object )

static

Publishes an endpoint to other applications.

Calls BMidiEndpoint's Register() method to publish an endpoint, which makes it visible to other applications.

StartWatching()

void BMidiRoster::StartWatching ( const BMessenger *  msngr )

static

Start receiving notifications from the Midi Roster.

When you start watching, BMidiRoster sends you notifications for all currently published remote 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.

be:op	int32	B_MIDI_REGISTERED
be:id	int32	id of the endpoint
be:type	string	"producer" or "consumer"

be:op	int32	B_MIDI_UNREGISTERED
be:id	int32	id of the endpoint
be:type	string	"producer" or "consumer"

The "connected" and "disconnected" notifications are sent when a consumer Connect()'s to a producer, or when they Disconnect() . You will receive these notifications when any 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 will be notified when another app connects one of your published endpoints.

be:op	int32	B_MIDI_CONNECTED
be:producer	int32	id of the connector
be:consumer	int32	id of the connectee

be:op	int32	B_MIDI_DISCONNECTED
be:producer	int32	id of the connector
be:consumer	int32	id of the connectee

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.

be:op	int32	B_MIDI_CHANGED_NAME
be:id	int32	id of the endpoint
be:type	string	"producer" or "consumer"
be:name	string	the endpoint's new name

be:op	int32	B_MIDI_CHANGED_LATENCY
be:id	int32	id of the endpoint
be:type	string	"producer" or "consumer"
be:latency	int64	the new latency (microseconds)

be:op	int32	B_MIDI_CHANGED_PROPERTIES
be:id	int32	id of the endpoint
be:type	string	"producer" or "consumer"
be:properties	bmessage	the new properties

Typical usage example:

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;
    }
}

For the possible midi options, see BMidiOp

StopWatching()

void BMidiRoster::StopWatching ( )

static

Stop receiving notifications from the Midi Roster.

See also

StartWatching()

Unregister()

status_t BMidiRoster::Unregister ( BMidiEndpoint *  object )

static

Hides an endpoint from other applications.

Calls BMidiEndpoint's Unregister() method to hide a previously published endpoint from other applications.