diff --git a/src/documentation/haiku_book/midi/midi1.xml b/src/documentation/haiku_book/midi/midi1.xml index d23aa13234..a8e8c59ca5 100644 --- a/src/documentation/haiku_book/midi/midi1.xml +++ b/src/documentation/haiku_book/midi/midi1.xml @@ -50,7 +50,7 @@ The old Midi Kit is slowly fading into obscurity. You may want to use the - instead. Also note that the Haiku implementation + MIDI 2 Kit instead. Also note that the Haiku implementation of the kit sometimes behaves differently than the one from BeOS R5 or what the BeBook says, but usually for the better ;-) diff --git a/src/documentation/haiku_book/midi/midi2api.xml b/src/documentation/haiku_book/midi/midi2api.xml index 17a2aca9d3..ac5e41189e 100644 --- a/src/documentation/haiku_book/midi/midi2api.xml +++ b/src/documentation/haiku_book/midi/midi2api.xml @@ -10,35 +10,40 @@ -BMidiRoster"> -Register()"> -Unregister()"> -StartWatching()"> +BMidiRoster"> +Register()"> +Unregister()"> +StartWatching()"> -BMidiEndpoint"> -Name()"> -SetName()"> -ID()"> -Register()"> -Unregister()"> -IsProducer()"> -IsConsumer()"> -IsRemote()"> -IsLocal()"> -IsPersistent()"> -IsValid()"> -Acquire()"> -Release()"> -SetProperties()"> -GetProperties()"> +BMidiEndpoint"> +Name()"> +SetName()"> +ID()"> +Register()"> +Unregister()"> +IsProducer()"> +IsConsumer()"> +IsRemote()"> +IsLocal()"> +IsPersistent()"> +IsValid()"> +Acquire()"> +Release()"> +SetProperties()"> +GetProperties()"> -BMidiLocalConsumer"> -BMidiLocalConsumer"> +BMidiLocalConsumer"> +BMidiLocalConsumer"> -BMidiLocalProducer"> +BMidiLocalProducer"> + +BMidiProducer"> +Connect()"> +Disconnect()"> + +BMidiConsumer"> +Latency()"> -BMidiProducer"> -BMidiConsumer"> ]> @@ -46,9 +51,9 @@ &midi2defs; &midi2roster; + &midi2endpoint; &midi2consumer; &midi2producer; - &midi2endpoint; &midi2localconsumer; &midi2localproducer; diff --git a/src/documentation/haiku_book/midi/midi2consumer.xml b/src/documentation/haiku_book/midi/midi2consumer.xml index 135d835ca6..6b87b07aaf 100644 --- a/src/documentation/haiku_book/midi/midi2consumer.xml +++ b/src/documentation/haiku_book/midi/midi2consumer.xml @@ -7,16 +7,22 @@ A consumer is an object that knows how to deal with incoming MIDI events. A consumer can be connected to multiple producers at the same time. There is no way to find out which producers are connected to this consumer just by looking - at the BMidiConsumer object; you will have to consult BMidiRoster for that. + at the &BMidiConsumer; object; you will have to consult &BMidiRoster; for that. - A BMidiConsumer either represents a local consumer, i.e. a class extending from - BMidiLocalConsumer, or is a proxy for a remote object published by another app. + A &BMidiConsumer; either represents a local consumer, i.e. a class extending from + &BMidiLocalConsumer;, or is a proxy for a remote object published by another app. - bigtime_t Latency() const + Latency() + + + bigtime_t + Latency + const + The latency is measured in microseconds. Producers should attempt to get MIDI @@ -26,20 +32,22 @@ - You cannot set the latency on a BMidiConsumer, only on a - BMidiLocalConsumer. + You cannot set the latency on a &BMidiConsumer;, only on a + &BMidiLocalConsumer;. The latency issue gets slightly more complicated when multiple endpoints are chained together, as in the following picture: - +-------+ +-------------+ +-------+ - | | | | | | - | prodA |---->| consB prodB |---->| consC | - | | | | | | - +-------+ +-------------+ +-------+ - appA appB (filter) appC + ++-------+ +-------------+ +-------+ +| | | | | | +| prodA |---->| consB prodB |---->| consC | +| | | | | | ++-------+ +-------------+ +-------+ +appA appB (filter) appC + diff --git a/src/documentation/haiku_book/midi/midi2endpoint.xml b/src/documentation/haiku_book/midi/midi2endpoint.xml index e717c8bba1..51baeaad0f 100644 --- a/src/documentation/haiku_book/midi/midi2endpoint.xml +++ b/src/documentation/haiku_book/midi/midi2endpoint.xml @@ -4,24 +4,24 @@ BMidiEndpoint - The MidiEndpoint.h file defines the &bmidiendpoint;, + The MidiEndpoint.h file defines the &BMidiEndpoint;, which is the baseclass for all MIDI endpoints. - &bmidiendpoint; is the abstract base class that represents either a producer or + &BMidiEndpoint; is the abstract base class that represents either a producer or consumer endpoint. It may be used to obtain the state, name, properties, or - system-wide ID of the object. &bmidiendpoint; also provides the ability to change + system-wide ID of the object. &BMidiEndpoint; also provides the ability to change the name and properties of endpoints that were created locally. - Remember, you cannot call the destructor of &bmidiendpoint; and its subclasses + Remember, you cannot call the destructor of &BMidiEndpoint; and its subclasses directly. Endpoint objects are destructed automatically when their reference count drops to zero. If necessary, the destructor of a local endpoint first - breaks off any connections and &bmidiendpoint_unregister;'s the endpoint before it is + breaks off any connections and &BMidiEndpoint_Unregister;'s the endpoint before it is deleted. However, for good style and bonus points you should really - BMidiProducer::Disconnect() and &bmidiendpoint_unregister; the object + BMidiProducer::Disconnect() and &BMidiEndpoint_Unregister; the object yourself and not rely on the destructor to do this. @@ -31,7 +31,7 @@ Name() - const char * + const char * Name const @@ -43,11 +43,11 @@ The function never returns NULL. If you created a local endpoint by passing a NULL name into its constructor (or passing no name, which is the same thing), - then &bmidiendpoint_name; will return an empty string, not NULL. + then &BMidiEndpoint_Name; will return an empty string, not NULL. - See also &bmidiendpoint_setname;. + See also &BMidiEndpoint_SetName;. @@ -55,7 +55,7 @@ SetName() - void SetName + void SetName constchar *name @@ -72,7 +72,7 @@ Even though you can call this function on both remote and local objects, you - are only allowed to change the names of local endpoints; &bmidiendpoint_setname; + are only allowed to change the names of local endpoints; &BMidiEndpoint_SetName; calls on remote endpoints are ignored. @@ -81,12 +81,12 @@ - See also &bmidiendpoint_name;. + See also &BMidiEndpoint_Name;. - int32 BMidiEndpoint::ID() const + ID() int32 Name const @@ -113,18 +113,18 @@ - Determines whether this endpoint is a &bmidiproducer;. + Determines whether this endpoint is a &BMidiProducer;. If it is, you can use a dynamic_cast to convert this object into a producer: - if (endp->IsProducer()) - { - BMidiProducer* prod = dynamic_cast <BMidiProducer*>(endp); - .... - } +if (endp->IsProducer()) +{ + BMidiProducer* prod = dynamic_cast <BMidiProducer*>(endp); + .... +} @@ -137,17 +137,17 @@ - Determines whether this endpoint is a &bmidiconsumer;. + Determines whether this endpoint is a &BMidiConsumer;. If it is, you can use a dynamic_cast to convert this object into a consumer: - if (endp->IsConsumer()) - { - BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp); - .... - } +if (endp->IsConsumer()) +{ + BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp); + .... +} @@ -165,7 +165,7 @@ An endpoint is "remote" when it is created by another application. Obviously, - the remote object is &bmidiendpoint_register;'ed as well, otherwise you would not be able to + the remote object is &BMidiEndpoint_Register;'ed as well, otherwise you would not be able to see it. @@ -183,7 +183,7 @@ An endpoint is "local" when it is created by this application; in other words, - a &bmidilocalconsumer; or &bmidilocalproducer;. + a &BMidiLocalConsumer; or &BMidiLocalProducer;. @@ -221,16 +221,16 @@ Suppose you obtained a proxy object for a remote endpoint by querying the - &bmidiroster;. What if the application that published this endpoint quits, or - less drastically, &bmidiendpoint_unregister;'s that endpoint? Even though you still have a - &bmidiendpoint; proxy object, the real endpoint no longer exists. You can use - &bmidiendpoint_isvalid; to check for this. + &BMidiRoster;. What if the application that published this endpoint quits, or + less drastically, &BMidiEndpoint_Unregister;'s that endpoint? Even though you still have a + &BMidiEndpoint; proxy object, the real endpoint no longer exists. You can use + &BMidiEndpoint_IsValid; to check for this. - Don't worry, operations on invalid objects, such as &bmidiendpoint_getproperties;, will + Don't worry, operations on invalid objects, such as &BMidiEndpoint_GetProperties;, will return an error code (typically B_ERROR), but not cause a crash. Local objects - are always are considered to be valid, even if you did not &bmidiendpoint_register; them. + are always are considered to be valid, even if you did not &BMidiEndpoint_Register; them. (The only time a local endpoint is not valid is when there was a problem constructing it.) @@ -238,8 +238,8 @@ If the application that created the remote endpoint crashes, then there is no guarantee that the Midi Server immediately recognizes this. In that case, - &bmidiendpoint_isvalid; may still return true. Eventually, the stale endpoint will be removed - from the roster, though. From then on, &bmidiendpoint_isvalid; correctly returns false. + &BMidiEndpoint_IsValid; may still return true. Eventually, the stale endpoint will be removed + from the roster, though. From then on, &BMidiEndpoint_IsValid; correctly returns false. @@ -255,35 +255,35 @@ - Each &bmidiendpoint; has a reference count associated with it, so that - &bmidiroster; can do proper bookkeeping. &bmidiendpoint_acquire; increments this reference - count, and &bmidiendpoint_release; decrements it. Once the count reaches zero, the endpoint + Each &BMidiEndpoint; has a reference count associated with it, so that + &BMidiRoster; can do proper bookkeeping. &BMidiEndpoint_Acquire; increments this reference + count, and &BMidiEndpoint_Release; decrements it. Once the count reaches zero, the endpoint is deleted. When you are done with the endpoint, whether local or remote, you should - always &bmidiendpoint_release; it! + always &BMidiEndpoint_Release; it! Upon construction, local endpoints start with a reference count of 1. Any - objects you obtain from &bmidiroster; using the NextXXX() or FindXXX() functions + objects you obtain from &BMidiRoster; using the NextXXX() or FindXXX() functions have their reference counts incremented in the process. If you forget to call - &bmidiendpoint_release;, the objects won't be properly cleaned up and you'll make a fool out + &BMidiEndpoint_Release;, the objects won't be properly cleaned up and you'll make a fool out of yourself. - After you &bmidiendpoint_release; an object, you are advised not to use it any further. If - you do, your app will probably crash. That also happens if you &bmidiendpoint_release; an + After you &BMidiEndpoint_Release; an object, you are advised not to use it any further. If + you do, your app will probably crash. That also happens if you &BMidiEndpoint_Release; an object too many times. - Typically, you don't need to call &bmidiendpoint_acquire;, unless you have two disparate + Typically, you don't need to call &BMidiEndpoint_Acquire;, unless you have two disparate parts of your application working with the same endpoint, and you don't want to - have to keep track of who needs to &bmidiendpoint_release; the endpoint. Now you simply have + have to keep track of who needs to &BMidiEndpoint_Release; the endpoint. Now you simply have both of them release it. @@ -292,7 +292,7 @@ - See also &bmidiendpoint_release;. + See also &BMidiEndpoint_Release;. @@ -312,7 +312,7 @@ - See also &bmidiendpoint_acquire; + See also &BMidiEndpoint_Acquire; @@ -329,25 +329,25 @@ MIDI objects created by an application are invisible to other applications - until they are published. To publish an object use the &bmidiendpoint_register; - method. The corresponding &bmidiendpoint_unregister; method will cause an object to + until they are published. To publish an object use the &BMidiEndpoint_Register; + method. The corresponding &BMidiEndpoint_Unregister; method will cause an object to once again become invisible to remote applications. - &bmidiroster; also has &bmidiroster_register; and &bmidiroster_unregister; methods. You may also use + &BMidiRoster; also has &BMidiRoster_Register; and &BMidiRoster_Unregister; methods. You may also use those methods to publish or hide your endpoints; both do the same thing. - Although it is considered bad style, calling &bmidiendpoint_register; on local endpoints that + Although it is considered bad style, calling &BMidiEndpoint_Register; on local endpoints that are already registered won't mess things up. The Midi Server will simply ignore - your request. Likewise for &bmidiendpoint_unregister;'ing more than once. Attempts to - &bmidiendpoint_register; or &bmidiendpoint_unregister; remote endpoints will fail, of course. + your request. Likewise for &BMidiEndpoint_Unregister;'ing more than once. Attempts to + &BMidiEndpoint_Register; or &BMidiEndpoint_Unregister; remote endpoints will fail, of course. - If you are &bmidiroster;::&startwatching; watching, you will + If you are &BMidiRoster;::&BMidiRoster_StartWatching; watching, you will not receive notifications for any local endpoints you register or unregister. Of course, other applications will be notified about your endpoints. @@ -365,7 +365,7 @@ - See also &bmidiendpoint_unregister;. + See also &BMidiEndpoint_Unregister;. @@ -384,7 +384,7 @@ - See also &bmidiendpoint_register;. + See also &BMidiEndpoint_Register;. @@ -410,18 +410,18 @@ Usage example: - BMessage props; - if (endpoint->GetProperties(&props) == B_OK) - { - ...add data to the message... - endpoint->SetProperties(&props); - } +BMessage props; +if (endpoint->GetProperties(&props) == B_OK) +{ + ...add data to the message... + endpoint->SetProperties(&props); +} - You are only allowed to call &bmidiendpoint_setproperties; on a local object. + You are only allowed to call &BMidiEndpoint_SetProperties; on a local object. @@ -483,7 +483,7 @@ - See also &bmidiendpoint_getproperties;. + See also &BMidiEndpoint_GetProperties;. @@ -504,20 +504,20 @@ Usage example: - BMessage props; - if (endpoint->GetProperties(&props) == B_OK) - { - ...examine the contents of the message... - } +BMessage props; +if (endpoint->GetProperties(&props) == B_OK) +{ + ...examine the contents of the message... +} - Note that &bmidiendpoint_getproperties; overwrites the contents of your BMessage. + Note that &BMidiEndpoint_GetProperties; overwrites the contents of your BMessage. - See also &bmidiendpoint_setproperties; + See also &BMidiEndpoint_SetProperties; diff --git a/src/documentation/haiku_book/midi/midi2producer.xml b/src/documentation/haiku_book/midi/midi2producer.xml index 488dbae23a..815800e7b9 100644 --- a/src/documentation/haiku_book/midi/midi2producer.xml +++ b/src/documentation/haiku_book/midi/midi2producer.xml @@ -4,26 +4,32 @@ BMidiProducer - Streams MIDI events to connected consumers + 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 + 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. + 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. - status_t Connect(BMidiConsumer *cons) + Connect() + + + status_t + Connect + BMidiConsumer * cons + - Connects a consumer to this producer + Connects a consumer to this producer. @@ -40,15 +46,21 @@ - See Also + See Also &BMidiProducer_Disconnect;. status_t Disconnect(BMidiConsumer *cons) + + status_t + Disconnect + BMidiConsumer * cons + + - Disconnects a consumer from this producer + Disconnects a consumer from this producer. @@ -62,53 +74,65 @@ - See Also + See Also &BMidiProducer_Connect;. - bool IsConnected(BMidiConsumer *cons) const + IsConnected() + + + bool + IsConnected + BMidiConsumer * cons + - Determines whether a consumer is connected to this producer + Determines whether a consumer is connected to this producer. - See Also and - + See Also &BMidiProducer_Connect; and + &BMidiProducer_Disconnect; BList *Connections() const + + BList * + Connections + const + + - Returns a list with all connected consumers + Returns a list with all connected consumers. - Returns a BList with pointers to BMidiEndpoint objects for all consumers that + 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: - 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; +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; 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 + is you) is responsible for freeing this list. The &BMidiEndpoint; objects in the + list have their reference counts bumped, so you need to &BMidiEndpoint;::&BMidiEndpoint_Release; them before you delete the list or they will go all leaky on you. diff --git a/src/documentation/license.xml b/src/documentation/license.xml index abb64287cf..e3c549fc8f 100644 --- a/src/documentation/license.xml +++ b/src/documentation/license.xml @@ -4,7 +4,7 @@ MIT License - + Copyright (c) 2003-2005, Haiku, Inc.