From 6caa106f8b7afa1b7d2e8179d38f23aa4e65c585 Mon Sep 17 00:00:00 2001 From: Niels Sascha Reedijk Date: Thu, 14 Sep 2006 10:51:16 +0000 Subject: [PATCH] Update the format of the midi2endpoint.xml file. This is a proposition on what the files should look like. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@18833 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- .../haiku_book/midi/midi2api.xml | 29 +++ .../haiku_book/midi/midi2consumer.xml | 2 +- .../haiku_book/midi/midi2endpoint.xml | 213 ++++++++++++------ .../haiku_book/midi/midi2producer.xml | 2 +- .../haiku_book/midi/midi2roster.xml | 2 +- 5 files changed, 174 insertions(+), 74 deletions(-) diff --git a/src/documentation/haiku_book/midi/midi2api.xml b/src/documentation/haiku_book/midi/midi2api.xml index 9198036b60..17a2aca9d3 100644 --- a/src/documentation/haiku_book/midi/midi2api.xml +++ b/src/documentation/haiku_book/midi/midi2api.xml @@ -10,6 +10,35 @@ +BMidiRoster"> +Register()"> +Unregister()"> +StartWatching()"> + +BMidiEndpoint"> +Name()"> +SetName()"> +ID()"> +Register()"> +Unregister()"> +IsProducer()"> +IsConsumer()"> +IsRemote()"> +IsLocal()"> +IsPersistent()"> +IsValid()"> +Acquire()"> +Release()"> +SetProperties()"> +GetProperties()"> + +BMidiLocalConsumer"> +BMidiLocalConsumer"> + +BMidiLocalProducer"> + +BMidiProducer"> +BMidiConsumer"> ]> diff --git a/src/documentation/haiku_book/midi/midi2consumer.xml b/src/documentation/haiku_book/midi/midi2consumer.xml index e2848f47ba..135d835ca6 100644 --- a/src/documentation/haiku_book/midi/midi2consumer.xml +++ b/src/documentation/haiku_book/midi/midi2consumer.xml @@ -1,6 +1,6 @@ - + BMidiConsumer diff --git a/src/documentation/haiku_book/midi/midi2endpoint.xml b/src/documentation/haiku_book/midi/midi2endpoint.xml index 230160a21e..e717c8bba1 100644 --- a/src/documentation/haiku_book/midi/midi2endpoint.xml +++ b/src/documentation/haiku_book/midi/midi2endpoint.xml @@ -4,29 +4,37 @@ 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 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 Unregister() the object + BMidiProducer::Disconnect() and &bmidiendpoint_unregister; the object yourself and not rely on the destructor to do this. + Member Functions + - const char* Name() const + Name() + + + const char * + Name + const + Returns the name of the endpoint. @@ -35,16 +43,21 @@ 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 Name() will return an empty string, not NULL. + then &bmidiendpoint_name; will return an empty string, not NULL. - See also + See also &bmidiendpoint_setname;. - void SetName(const char* name) + SetName() + + + void SetName + constchar *name + Changes the name of the endpoint. @@ -59,8 +72,8 @@ Even though you can call this function on both remote and local objects, you - are only allowed to change the names of local endpoints; SetName() calls on - remote endpoints are ignored. + are only allowed to change the names of local endpoints; &bmidiendpoint_setname; + calls on remote endpoints are ignored. @@ -68,15 +81,19 @@ - See also + See also &bmidiendpoint_name;. - int32 ID() const + int32 BMidiEndpoint::ID() const + + + int32 Name const + - Returns the ID of the endpoint + Returns the ID of the endpoint. @@ -89,10 +106,14 @@ - bool IsProducer() const + IsProducer() + + + bool IsProducer const + - Determines whether this endpoint is a BMidiProducer + Determines whether this endpoint is a &bmidiproducer;. @@ -109,10 +130,14 @@ - bool IsConsumer() const + IsConsumer() + + + bool IsConsumer const + - Determines whether this endpoint is a BMidiConsumer + Determines whether this endpoint is a &bmidiconsumer;. @@ -128,7 +153,11 @@ - bool IsRemote() const + IsRemote() + + + bool IsRemote const + Determines whether this endpoint is a proxy for a remote object. @@ -136,29 +165,37 @@ An endpoint is "remote" when it is created by another application. Obviously, - the remote object is 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. - bool IsLocal() const + IsLocal() + + + bool IsLocal const + - Determines whether this endpoint represents a local object + Determines whether this endpoint represents a local object. An endpoint is "local" when it is created by this application; in other words, - a BMidiLocalConsumer or BMidiLocalProducer. + a &bmidilocalconsumer; or &bmidilocalproducer;. - bool IsPersistent() const + IsPersistent() + + + bool IsPersistent const + - Not used + Not used. @@ -172,7 +209,11 @@ - bool IsValid() const + IsValid() + + + bool IsValid const + Determines whether the endpoint still exists @@ -180,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, Unregister()'s that endpoint? Even though you still have a - BMidiEndpoint proxy object, the real endpoint no longer exists. You can use - 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 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 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.) @@ -197,48 +238,52 @@ If the application that created the remote endpoint crashes, then there is no guarantee that the Midi Server immediately recognizes this. In that case, - IsValid() may still return true. Eventually, the stale endpoint will be removed - from the roster, though. From then on, 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. - status_t Acquire() + status_t BMidiEndpoint::Acquire() + + + status_t Acquire + Increments the endpoint's reference count - Each BMidiEndpoint has a reference count associated with it, so that - BMidiRoster can do proper bookkeeping. Acquire() increments this reference - count, and 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 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 - 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 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 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 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 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. @@ -247,15 +292,19 @@ - See also + See also &bmidiendpoint_release;. - status_t Release() + status_t BMidiEndpoint::Release() + + + status_t Release + - Decrements the endpoint's reference count + Decrements the endpoint's reference count. @@ -263,38 +312,42 @@ - See also + See also &bmidiendpoint_acquire; - status_t Register() + Register() + + + status_t Register + - Publishes the endpoint on the roster + Publishes the endpoint on the roster. MIDI objects created by an application are invisible to other applications - until they are published. To publish an object use the Register() method. The - corresponding Unregister() method will cause an object to once again become - invisible to remote applications. + 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 Register() and 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 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 Unregister()'ing more than once. Attempts to - Register() or 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;::&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. @@ -312,27 +365,39 @@ - See also + See also &bmidiendpoint_unregister;. - status_t Unregister() + Unregister() + + + + status_t Unregister + + + - Hides the endpoint from the roster + Hides the endpoint from the roster. - See also + See also &bmidiendpoint_register;. - status_t SetProperties(const BMessage* properties) + SetProperties() + + + status_t SetProperties + constBMessage *properties + - Changes the properties of the endpoint + Changes the properties of the endpoint. @@ -356,7 +421,7 @@ - You are only allowed to call SetProperties() on a local object. + You are only allowed to call &bmidiendpoint_setproperties; on a local object. @@ -418,12 +483,18 @@ - See also + See also &bmidiendpoint_getproperties;. - status_t GetProperties(BMessage* properties) const + GetProperties() + + + status_t GetProperties + BMessage *properties + const + Reads the properties of the endpoint @@ -442,11 +513,11 @@ - Note that GetProperties() overwrites the contents of your BMessage. + Note that &bmidiendpoint_getproperties; overwrites the contents of your BMessage. - See also + See also &bmidiendpoint_setproperties; diff --git a/src/documentation/haiku_book/midi/midi2producer.xml b/src/documentation/haiku_book/midi/midi2producer.xml index 118401fb1f..488dbae23a 100644 --- a/src/documentation/haiku_book/midi/midi2producer.xml +++ b/src/documentation/haiku_book/midi/midi2producer.xml @@ -1,6 +1,6 @@ - + BMidiProducer diff --git a/src/documentation/haiku_book/midi/midi2roster.xml b/src/documentation/haiku_book/midi/midi2roster.xml index 7048feb723..093b39a416 100644 --- a/src/documentation/haiku_book/midi/midi2roster.xml +++ b/src/documentation/haiku_book/midi/midi2roster.xml @@ -1,6 +1,6 @@ - + BMidiRoster