/*!
\class BMidiProducer MidiProducer.h
\brief Streams MIDI events to connected consumers

A producer is an object that generate a stream of MIDI events. Each producer 
has a list of BMidiConsumer objects to which it is connected, and may be asked 
to connect to or disconnect from a BMidiConsumer. A producer can spray its 
events to multiple consumers at the same time. 

A BMidiProducer either represents a local producer, i.e. a class extending from 
BMidiLocalProducer, or is a proxy for a remote object published by another app. 

*/

/*!
\fn status_t BMidiProducer::Connect(BMidiConsumer* cons)
\brief Connects a consumer to this producer

Establishes a connection between this producer and the specified consumer 
endpoint. From now on, any events that this producer sprays will be sent to 
that consumer. You may connect multiple consumers to a producer.

\return B_OK on success, or an error code when the connection could not be 
established. If the consumer is a proxy for a remote object and that object no 
longer exists, Connect() returns B_ERROR. It also returns B_ERROR if you try to 
connect the same producer and consumer more than once.

\sa Disconnect()
*/

/*!
\fn status_t BMidiProducer::Disconnect(BMidiConsumer* cons)
\brief Disconnects a consumer from this producer

Terminates the connection between this producer and the specified consumer 
endpoint. From now on, any events that this producer sprays no longer go to 
that consumer.

\return B_OK on success, or an error code if there was no connection to break

\sa Connect()
*/

/*!
\fn bool BMidiProducer::IsConnected(BMidiConsumer* cons) const
\brief Determines whether a consumer is connected to this producer
\sa Connect()
\sa Disconnect()
*/

/*!
\fn BList* BMidiProducer::Connections() const
\brief Returns a list with all connected consumers

Returns a BList with pointers to BMidiEndpoint objects for all consumers that 
are connected to this producer. You can examine the contents of the list as 
follows:

\code
BList* list = prod->Connections();
for (int32 t = 0; t < list->CountItems(); ++t)
{
    BMidiEndpoint* endp = (BMidiEndpoint*) list->ItemAt(t);
    ...do stuff...
    endp->Release();  // yes, here too!
}
delete list;
\endcode

Every time you call this function, a new BList is allocated. The caller (that 
is you) is responsible for freeing this list. The BMidiEndpoint objects in the 
list have their reference counts bumped, so you need to Release() them before 
you delete the list or they will go all leaky on you.

*/