Revert earlier removal.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@18801 a95241bf-73f2-0310-859d-f6bbb57e9c96
2006-09-11 08:50:10 +00:00
parent f4bd80a2dc
commit e932ec1af2
11 changed files with 1604 additions and 3 deletions
@@ -0,0 +1,75 @@
+/*!
+\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.
+
+*/