diff --git a/src/documentation/haiku_book/Haiku_Book.xml b/src/documentation/haiku_book/Haiku_Book.xml
index e5593df5ec..87e592455d 100644
--- a/src/documentation/haiku_book/Haiku_Book.xml
+++ b/src/documentation/haiku_book/Haiku_Book.xml
@@ -38,7 +38,12 @@
JeromeDuval
-
+
+
+ Matthijs
+ Hollemans
+
+
diff --git a/src/documentation/haiku_book/midi/intro.xml b/src/documentation/haiku_book/midi/intro.xml
index a8c2415c76..debc88d5a9 100644
--- a/src/documentation/haiku_book/midi/intro.xml
+++ b/src/documentation/haiku_book/midi/intro.xml
@@ -8,9 +8,41 @@
Introduction
- The Midi Kit provides classes capable of understanding the MIDI file format and synthesising the sounds described within. Furthermore, it also provides mechanisms for communicating with MIDI compliant hardware via messages.
+ The Midi Kit is the API that implements support for generating, processing, and
+ playing music in MIDI format. MIDI, which
+ stands for 'Musical Instrument Digital Interface', is a well-established
+ standard for representing and communicating musical data.
+
- There are two versions of the Midi Kit, the latter reportedly much more up-to-date and more compatible with other applications. Though sadly it is undocumented. For more information consult the headers (At least until such time as this document is further updated).
-
+
+ The BeOS comes with two different, but compatible Midi Kits. This documentation
+ focuses on the "new" Midi Kit, or midi2 as we like to call it, that was
+ introduced with BeOS R5. The old kit, which we'll refer to as midi1, is more
+ complete than the new kit, but less powerful.
+
+
+
+ Both kits let you create so-called MIDI endpoints, but the endpoints from midi1
+ cannot be shared between different applications. The midi2 kit solves that
+ problem, but unlike midi1 it does not include a General MIDI softsynth, nor
+ does it have a facility for reading and playing Standard MIDI Files. Don't
+ worry: both kits are compatible and you can mix-and-match them in your
+ applications.
+
+
+
+ The main differences between the two kits:
+
+ Instead of one BMidi object that both produces and consumes events, we have
+ BMidiProducer and BMidiConsumer.
+ Applications are capable of sharing MIDI producers and consumers with other
+ applications via the centralized Midi Roster.
+ Physical MIDI ports are now sharable without apps "stealing" events from each
+ other.
+ Applications can now send/receive raw MIDI byte streams (useful if an
+ application has its own MIDI parser/engine).
+ Channels are numbered 0..15, not 1..16
+ Timing is now specified in microseconds instead of milliseconds.
+
diff --git a/src/documentation/haiku_book/midi/midi1.xml b/src/documentation/haiku_book/midi/midi1.xml
new file mode 100644
index 0000000000..d23aa13234
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi1.xml
@@ -0,0 +1,66 @@
+
+
+
+
+ The Old Midi 1 Kit
+
+ The old Midi Kit, or midi1 for short, goes all the way back to DR8, when the
+ BeOS only ran on BeBoxen. Fortunately for us, it is pretty well documented:
+
+ Midi
+ Kit chapter in the online Be Book
+ Midi
+ Kit section of the old Be Developer Library
+ Be Newsletter Volume 1, Issue 49 - Introduces the MIDI synth
+ Be Newsletter Volume 1, Issue 52 - Follow-up on issue 49
+ Be Newsletter Volume 1, Issue 91 - How to use BSynth
+ Be Newsletter Volume 1, Issue 102 - Axe sample code
+ Be Newsletter Volume 1, Issue 104 - How to use BMidiPort
+ Be Newsletter Volume 2, Issue 23 - EdMidi sample code
+ Be Newsletter Volume 2, Issue 37 - How to use the MIDI synth
+ Be Newsletter Volume 3, Issue 37 - Whistle sample code
+
+
+
+ To summarize, there are four basic MIDI classes:
+
+ BMidi is the base class for most other classes from the Midi Kit.
+ BMidiPort can talk to a MIDI hardware port.
+ BMidiStore can read, write, and perform Standard MIDI files.
+ BMidiText is a debugging aid that dumps MIDI messages to stdout
+
+
+
+
+ The following classes let you use the Midi Kit's General MIDI synthesizer:
+
+ BSynth controls the synthesizer.
+ BMidiSynth connects a BMidi object to the synth.
+ BMidiSynthFile connects a MIDI file to the synth
+ BSamples lets you access the synth's sound data stream
+
+
+
+ To make MIDI data stream through your application, you create a "network" of
+ BMidi-derived objects that send and receive MIDI messages.
+
+
+
+ The old Midi Kit is slowly fading into obscurity. You may want to use the
+ 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 ;-)
+
+
+
+ Especially the synth classes are not completely functional, but enough to
+ play back General MIDI tunes. They should be backwards compatible with the
+ majority of BeOS MIDI applications. Not all methods of BSynth, BMidiSynth,
+ and BMidiSynthFile are implemented because some of them are rather obscure.
+ BSamples is a complete no-op; in other words, with the Haiku Midi Kit
+ you cannot push waveform data into the output stream of the softsynth.
+
+
diff --git a/src/documentation/haiku_book/midi/midi2.xml b/src/documentation/haiku_book/midi/midi2.xml
new file mode 100644
index 0000000000..df7b8a45fc
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2.xml
@@ -0,0 +1,362 @@
+
+
+
+The Midi 2 Kit
+
+
+ Concepts
+
+
+ A brief overview of the elements that comprise the Midi Kit:
+
+ Endpoints. This is what the Midi Kit is all about: sending MIDI messages
+ between endpoints. An endpoint is like a MIDI In or MIDI Out socket on your
+ equipment; it either receives information or it sends information. Endpoints
+ that send MIDI events are called \b producers; the endpoints that receive those
+ events are called \b consumers. An endpoint that is created by your own
+ application is called \b local; endpoints from other applications are \b
+ remote. You can access remote endpoints using \b proxies.
+
+ Filters. A filter is an object that has a consumer and a producer
+ endpoint. It reads incoming events from its consumer, performs some operation,
+ and tells its producer to send out the results. In its current form, the Midi
+ Kit doesn't provide any special facilities for writing filters.
+
+ Midi Roster. The roster is the list of all published producers and
+ consumers. By publishing an endpoint, you allow other applications to talk to
+ it. You are not required to publish your endpoints, in which case only your own
+ application can use them.
+
+ Midi Server. The Midi Server does the behind-the-scenes work. It
+ manages the roster, it connects endpoints, it makes sure that endpoints can
+ communicate, and so on. The Midi Server is started automatically when BeOS
+ boots, and you never have to deal with it directly. Just remember that it runs
+ the show.
+
+ libmidi. The BMidi* classes live inside two shared libraries: libmidi.so
+ and libmidi2.so. If you write an application that uses old Midi Kit, you must
+ link it to libmidi.so. Applications that use the new Midi Kit must link to
+ libmidi2.so. If you want to mix-and-match both kits, you should also link to
+ both libraries.
+
+
+
+ The concepts captured in an image
+
+
+
+
+ An overview of the MIDI kit.
+
+
+
+
+
+ Midi Kit != Media Kit
+
+
+ Be chose not to integrate the Midi Kit into the Media Kit as another media
+ type, mainly because MIDI doesn't require any of the format negotiation that
+ other media types need. Although the two kits look similar -- both have a
+ "roster" for finding or registering "consumers" and "producers" -- there are
+ some very important differences.
+
+
+
+ The first and most important point to note is that BMidiConsumer and
+ BMidiProducer in the Midi Kit are NOT directly analogous to BBufferConsumer and
+ BBufferProducer in the Media Kit! In the Media Kit, consumers and producers are
+ the data consuming and producing properties of a media node. A filter in the
+ Media Kit, therefore, inherits from both BBufferConsumer and BBufferProducer,
+ and implements their virtual member functions to do its work.
+
+
+
+ In the Midi Kit, consumers and producers act as endpoints of MIDI data
+ connections, much as media_source and media_destination do in the Media Kit.
+ Thus, a MIDI filter does not derive from BMidiConsumer and BMidiProducer;
+ instead, it contains BMidiConsumer and BMidiProducer objects for each of its
+ distinct endpoints that connect to other MIDI objects. The Midi Kit does not
+ allow the use of multiple virtual inheritance, so you can't create an object
+ that's both a BMidiConsumer and a BMidiProducer.
+
+
+
+ This also contrasts with the old Midi Kit's conception of a BMidi object, which
+ stood for an object that both received and sent MIDI data. In the new Midi Kit,
+ the endpoints of MIDI connections are all that matters. What lies between the
+ endpoints, i.e., how a MIDI filter is actually structured, is entirely at your
+ discretion.
+
+
+
+ Also, rather than use token structs like media_node to make connections via the
+ MediaRoster, the new kit makes the connections directly via the BMidiProducer
+ object.
+
+
+
+
+ Remote and local objects
+
+
+ The Midi Kit makes a distinction between remote and local MIDI objects. You can
+ only create local MIDI endpoints, which derive from either BMidiLocalConsumer
+ or BMidiLocalProducer. Remote endpoints are endpoints that live in other
+ applications, and you access them through BMidiRoster.
+
+
+
+ BMidiRoster only gives you access to BMidiEndpoints, BMidiConsumers, and
+ BMidiProducers. When you want to talk to remote MIDI objects, you do so through
+ the proxy objects that BMidiRoster provides. Unlike BMidiLocalConsumer and
+ BMidiLocalProducer, these classes do not provide a lot of functions. That is
+ intentional. In order to hide the details of communication with MIDI endpoints
+ in other applications, the Midi Kit must hide the details of how a particular
+ endpoint is implemented.
+
+
+
+ So, what can you do with remote objects? Only what BMidiConsumer,
+ BMidiProducer, and BMidiEndpoint will let you do. You can connect objects, get
+ the properties of these objects -- and that's about it.
+
+
+
+
+ Creating and Destroying Objects
+
+
+ The constructors and destructors of most midi2 classes are private, which mean
+ you cannot directly create them using the C++ new operator, on the
+ stack, or as globals. Nor can you delete them. Instead, these
+ objects are obtained through BMidiRoster. The only two exceptions to this rule
+ are BMidiLocalConsumer and BMidiLocalProducer. These two objects may be
+ directly created and subclassed by developers.
+
+
+
+
+ Reference Counting
+
+
+ Each MIDI endpoint has a reference count associated with it, so that the Midi
+ Roster can do proper bookkeeping. When you construct a BMidiLocalProducer or
+ BMidiLocalConsumer endpoint, it starts with a reference count of 1. In
+ addition, BMidiRoster increments the reference count of any object it hands to
+ you as a result of BMidiRoster::NextEndpoint() or
+ BMidiRoster::FindEndpoint(). Once the count hits
+ 0, the endpoint will be deleted.
+
+
+
+ This means that, to delete an endpoint, you don't call the delete
+ operator directly; instead, you call BMidiEndpoint::Release(). To balance this call,
+ there's also an BMidiEndpoint::Acquire(), in case you have two disparate parts of
+ your application working with the endpoint, and you don't want to have to keep
+ track of who needs to Release() the endpoint.
+
+
+
+ When you're done with any endpoint object, you must Release() it. This is true
+ for both local and remote objects. Repeat after me: Release() when you're done.
+
+
+
+
+ MIDI Events
+
+
+ To make some actual music, you need to BMidiProducer::Connect()
+ your consumers to your producers. Then you tell the producer to
+ "spray" MIDI events to all the connected consumers. The consumers are notified
+ of these incoming events through a set of hook functions.
+
+
+
+ The Midi Kit already provides a set of commonly used spray functions, such as
+ BMidiLocalProducer::SprayNoteOn(), BMidiLocalProducer::SprayControlChange(), and so
+ on. These correspond one-to-one with the message types from the MIDI spec. You
+ don't need to be a MIDI expert to use the kit, but of course some knowledge of
+ the protocol helps. If you are really hardcore, you can also use the
+ BMidiLocalProducer::SprayData() to send raw MIDI events to
+ the consumers.
+
+
+
+ At the consumer side, a dedicated thread invokes a hook function for every
+ incoming MIDI event. For every spray function, there is a corresponding hook
+ function, e.g. BMidiLocalConsumer::NoteOn() and
+ BMidiLocalConsumer::ControlChange(). The hardcore MIDI
+ fanatics among you will be pleased to know that you can also tap into the
+ BMidiLocalConsumer::Data() hook and get your hands dirty with
+ the raw MIDI data.
+
+
+
+
+ Time
+
+ The spray and hook functions accept a bigtime_t parameter named "time". This
+ indicates when the MIDI event should be performed. The time is given in
+ microseconds since the computer booted. To get the current tick measurement,
+ you call the system_time() function from the Kernel Kit.
+
+
+
+ If you override a hook function in one of your consumer objects, it should look
+ at the time argument, wait until the designated time, and then perform its
+ action. The preferred method is to use the Kernel Kit's
+ snooze_until() function, which sends the consumer thread to sleep
+ until the requested time has come. (Or, if the time has already passed, returns
+ immediately.)
+
+
+
+ Like this:
+
+ void MyConsumer::NoteOn(
+ uchar channel, uchar note, uchar velocity, bigtime_t time)
+ {
+ snooze_until(time, B_SYSTEM_TIMEBASE);
+ ...do your thing...
+ }
+
+
+
+
+ If you want your producers to run in real time, i.e. they produce MIDI data
+ that needs to be performed immediately, you should pass time 0 to the spray
+ functions (which also happens to be the default value). Since time 0 has
+ already passed, snooze_until() returns immediately, and the
+ consumer will process the events as soon as they are received.
+
+
+
+ To schedule MIDI events for a performance time that lies somewhere in the
+ future, the producer must take into account the consumer's latency. Producers
+ should attempt to get notes to the consumer by or before
+ (scheduled_performance_time - latency). The time argument is still the
+ scheduled performance time, so if your consumer has latency, it should snooze
+ like this before it starts to perform the events:
+
+ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
+
+
+
+
+ Note that a typical producer sends out its events as soon as it can; unlike a
+ consumer, it does not have to snooze.
+
+
+
+
+ Other Timing Issues
+
+
+ Each consumer object uses a Kernel Kit port to receive MIDI events from
+ connected producers. The queue for this port is only 1 message deep. This means
+ that if the consumer thread is asleep in a snooze_until(), it will
+ not read its port. Consequently, any producer that tries to write a new event
+ to this port will block until the consumer thread is ready to receive a new
+ message. This is intentional, because it prevents producers from generating and
+ queueing up thousands of events.
+
+
+
+ This mechanism, while simple, puts on the producer the responsibility for
+ sorting the events in time. Suppose your producer sends three Note On events,
+ the first on t + 0, the second on t + 4, and the third on t + 2. This last
+ event won't be received until after t + 4, so it will be two ticks too late. If
+ this sort of thing can happen with your producer, you should somehow sort the
+ events before you spray them. Of course, if you have two or more producers
+ connected to the same consumer, it is nearly impossible to sort this all out
+ (pardon the pun). So it is not wise to send the same kinds of events from more
+ than one producer to one consumer at the same time.
+
+
+
+ The article Introduction to MIDI, Part 2 in Haiku
+ Newsletter 36 describes this problem in more detail, and provides a
+ solution. Go read it now!
+
+
+
+
+ Writing a Filter
+
+
+ A typical filter contains a consumer and a producer endpoint. It receives
+ events from the consumer, processes them, and sends them out again using the
+ producer. The consumer endpoint is a subclass of BMidiLocalConsumer, whereas
+ the producer is simply a BMidiLocalProducer, not a subclass. This is a common
+ configuration, because consumers work by overriding the event hooks to do work
+ when MIDI data arrives. Producers work by sending an event when you call their
+ member functions. You should hardly ever need to derive from BMidiLocalProducer
+ (unless you need to know when the producer gets connected or disconnected,
+ perhaps), but you'll always have to override one or more of
+ BMidiLocalConsumer's member functions to do something useful with incoming
+ data.
+
+
+
+ Filters should ignore the time argument from the spray and hook functions, and
+ simply pass it on unchanged. Objects that only filter data should process the
+ event as quickly as possible and be done with it. Do not
+ snooze_until() in the consumer endpoint of a filter!
+
+
+
+
+ API Differences
+
+
+ As far as the end user is concerned, the OpenBeOS Midi Kit is mostly the same
+ as the BeOS R5 kits, although there are a few small differences in the API
+ (mostly bug fixes):
+
+ BMidiEndpoint::IsPersistent() always returns false.
+ The B_MIDI_CHANGE_LATENCY notification is now properly sent. The Be kit
+ incorrectly set be:op to B_MIDI_CHANGED_NAME, even though the rest of the
+ message was properly structured.
+ If creating a local endpoint fails, you can still Release() the object
+ without crashing into the debugger.
+
+
+
+
+
+ See Also
+
+
+ More about the Midi Kit:
+
+ Be Newsletter Volume 3, Issue 47 - Motor Mix sample code
+ Be Newsletter Volume 4, Issue 3 - Overview of the new kit
+ Haiku
+ Newsletter 33, Introduction to MIDI, Part 1
+ Haiku
+ Newsletter 36, Introduction to MIDI, Part 2
+ Sample code and other goodies at the
+ OpenBeOS Midi Kit team page
+
+
+
+
+ Information about MIDI in general:
+
+ MIDI Manufacturers Association
+ MIDI Tutorials
+ MIDI Specification
+ Standard MIDI File Format
+ Jim Menard's MIDI Reference
+
+
+
+
+
+
diff --git a/src/documentation/haiku_book/midi/midi2api.xml b/src/documentation/haiku_book/midi/midi2api.xml
new file mode 100644
index 0000000000..9198036b60
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2api.xml
@@ -0,0 +1,26 @@
+
+
+
+
+
+
+
+
+
+]>
+
+
+ Midi 2 Kit API
+
+ &midi2defs;
+ &midi2roster;
+ &midi2consumer;
+ &midi2producer;
+ &midi2endpoint;
+ &midi2localconsumer;
+ &midi2localproducer;
+
+
diff --git a/src/documentation/haiku_book/midi/midi2concepts.png b/src/documentation/haiku_book/midi/midi2concepts.png
new file mode 100644
index 0000000000..2278a4d53b
Binary files /dev/null and b/src/documentation/haiku_book/midi/midi2concepts.png differ
diff --git a/src/documentation/haiku_book/midi/midi2consumer.xml b/src/documentation/haiku_book/midi/midi2consumer.xml
new file mode 100644
index 0000000000..bceea347d4
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2consumer.xml
@@ -0,0 +1,64 @@
+
+
+
+ BMidiConsumer
+
+
+ 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.
+
+
+
+ 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 BMidiConsumer::Latency() const
+
+
+ The latency is measured in microseconds. Producers should attempt to get MIDI
+ events to this consumer by (when - latency). You do this by subtracting
+ the latency from the performance time when you spray the events (provided that
+ you spray these events ahead of time, of course).
+
+
+
+ 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
+
+
+
+ Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply
+ reports 100ms, then prodA will schedule its events for (t - 100), which is
+ really 200ms too late. (Of course, producers send out their events as soon as
+ possible, so depending on the load of the system, everything may work out just
+ fine.)
+
+
+
+ ConsB should report the latency of the consumer that is hooked up to its
+ output, consC, in addition to its own latency. In other words, the full
+ downstream latency. So, the reported latency in this case would be 300ms. This
+ also means that appB should change the latency of consB when prodB makes or
+ breaks a connection, and when consC reports a latency change. (If multiple
+ consumers are connected to prodB, you should take the slowest one.)
+ Unfortunately, the Midi Kit provides no easy mechanism for doing any of this,
+ so you are on your own here.
+
+
+
diff --git a/src/documentation/haiku_book/midi/midi2defs.xml b/src/documentation/haiku_book/midi/midi2defs.xml
new file mode 100644
index 0000000000..da672f140d
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2defs.xml
@@ -0,0 +1,285 @@
+
+
+
+ Midi Defs
+
+
+ The Midi2Defs.h defines a series of constants that are used throughout
+ the Kit.
+
+
+
+
diff --git a/src/documentation/haiku_book/midi/midi2endpoint.xml b/src/documentation/haiku_book/midi/midi2endpoint.xml
new file mode 100644
index 0000000000..95ef673262
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2endpoint.xml
@@ -0,0 +1,452 @@
+
+
+
+ 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
+ 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
+ the name and properties of endpoints that were created locally.
+
+
+
+ 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
+ deleted. However, for good style and bonus points you should really
+ BMidiProducer::Disconnect() and Unregister() the object
+ yourself and not rely on the destructor to do this.
+
+
+
+ const char* BMidiEndpoint::Name() const
+
+
+ Returns the name of the endpoint.
+
+
+
+ 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.
+
+
+
+ See also
+
+
+
+
+ void BMidiEndpoint::SetName(const char* name)
+
+
+ Changes the name of the endpoint.
+
+
+
+ Names don't have to be unique, but it is recommended that you give any
+ endpoints you publish meaningful and unique names, so users can easily
+ recognize what each endpoint does. There is no limit to the size of endpoint
+ names.
+
+
+
+ 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.
+
+
+
+ name The new name. If you pass NULL, the name simply won't be changed.
+
+
+
+ See also
+
+
+
+
+ int32 BMidiEndpoint::ID() const
+
+
+ Returns the ID of the endpoint
+
+
+
+ An ID uniquely identifies an endpoint in the system. The ID is a signed 32-bit
+ number that is assigned by the Midi Server when the endpoint is created. (So
+ even if a local endpoint is not published, it still has a unique ID.) Valid IDs
+ range from 1 to 0x7FFFFFFF, the largest value an int32 can have. 0 and negative
+ values are not valid IDs.
+
+
+
+
+ bool BMidiEndpoint::IsProducer() const
+
+
+ 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);
+ ....
+ }
+
+
+
+
+
+ bool BMidiEndpoint::IsConsumer() const
+
+
+ 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);
+ ....
+ }
+
+
+
+
+
+ bool BMidiEndpoint::IsRemote() const
+
+
+ Determines whether this endpoint is a proxy for a remote object.
+
+
+
+ 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
+ see it.
+
+
+
+
+ bool BMidiEndpoint::IsLocal() const
+
+
+ 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.
+
+
+
+
+ bool BMidiEndpoint::IsPersistent() const
+
+
+ Not used
+
+
+
+ The purpose of this function is unclear, and as a result it doesn't do anything
+ in the Haiku implementation of the Midi Kit.
+
+
+
+ Always returns false.
+
+
+
+
+ bool BMidiEndpoint::IsValid() const
+
+
+ Determines whether the endpoint still exists
+
+
+
+ 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.
+
+
+
+ Don't worry, operations on invalid objects, such as 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.
+ (The only time a local endpoint is not valid is when there was a problem
+ constructing it.)
+
+
+
+ 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.
+
+
+
+
+ status_t BMidiEndpoint::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
+ is deleted.
+
+
+
+ When you are done with the endpoint, whether local or remote, you should
+ always 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
+ 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
+ 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
+ object too many times.
+
+
+
+ Typically, you don't need to call 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
+ both of them release it.
+
+
+
+ Always returns B_OK.
+
+
+
+ See also
+
+
+
+
+ status_t BMidiEndpoint::Release()
+
+
+ Decrements the endpoint's reference count
+
+
+
+ Always returns B_OK.
+
+
+
+ See also
+
+
+
+
+ status_t BMidiEndpoint::Register()
+
+
+ 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.
+
+
+
+ BMidiRoster also has Register() and 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
+ 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.
+
+
+
+ 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.
+
+
+
+ Existing connections will not be broken when an object is unregistered, but
+ future remote connections will be denied. When objects are destroyed, they
+ automatically become unregistered.
+
+
+
+ Returns B_OK on success, or a negative error code (typically B_ERROR) if
+ something went wrong.
+
+
+
+ See also
+
+
+
+
+ status_t BMidiEndpoint::Unregister()
+
+
+ Hides the endpoint from the roster
+
+
+
+ See also
+
+
+
+
+ status_t BMidiEndpoint::SetProperties(const BMessage* props)
+
+
+ Changes the properties of the endpoint
+
+
+
+ Endpoints can have properties, which is any kind of information that might be
+ useful to associate with a MIDI object. The properties are stored in a
+ BMessage.
+
+
+
+ Usage example:
+
+
+ BMessage props;
+ if (endpoint->GetProperties(&props) == B_OK)
+ {
+ ...add data to the message...
+ endpoint->SetProperties(&props);
+ }
+
+
+
+
+
+ You are only allowed to call SetProperties() on a local object.
+
+
+
+ Properties should follow a protocol, so different applications will know how to
+ read each other's properties. The current protocol is very limited -- it only
+ allows you to associate icons with your endpoints. Be planned to publish a more
+ complete protocol that included additional information, such as vendor/model
+ names, copyright/version info, category, etc., but they never got around to it.
+
+
+
+ Large Icon Property
+
+
+
+
+
+ property
+ Large (32x32) icon
+
+
+ field name
+ "be:large_icon"
+
+
+ field type
+ 'ICON'
+
+
+
+
+
+
+ Small Icon Property
+
+
+
+
+
+ property
+ Small (16x16) ico
+
+
+ field name
+ "be:mini_icon"
+
+
+ field type
+ 'MICN'
+
+
+
+
+
+
+ The MidiUtil package (downloadable from the Haiku website) contains a number
+ of convenient functions to associate icons with endpoints, so you don't have to
+ write that code all over again.
+
+
+
+ See also
+
+
+
+
+ status_t BMidiEndpoint::GetProperties(BMessage* props) const
+
+
+ Reads the properties of the endpoint
+
+
+
+ Usage example:
+
+
+ BMessage props;
+ if (endpoint->GetProperties(&props) == B_OK)
+ {
+ ...examine the contents of the message...
+ }
+
+
+
+
+ Note that GetProperties() overwrites the contents of your BMessage.
+
+
+
+ See also
+
+
+
diff --git a/src/documentation/haiku_book/midi/midi2localconsumer.xml b/src/documentation/haiku_book/midi/midi2localconsumer.xml
new file mode 100644
index 0000000000..2b5b1d81fe
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2localconsumer.xml
@@ -0,0 +1,371 @@
+
+
+
+ BMidiLocalConsumer
+
+
+ A consumer endpoint that is created by your own application
+
+
+
+ If you want to create a consumer that reacts to MIDI events, you should
+ subclass BMidiLocalConsumer.
+
+
+
+ Each local consumer has its own thread that receives and dispatches the MIDI
+ events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to
+ a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so
+ on. Calls to these hook functions are serialized -- they will never have to be
+ re-entrant. They also should not be called from outside the thread that is
+ invoking them.
+
+
+
+ Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer
+ doesn't provide default implementations for them, so you don't have to call a
+ hook's default implementation if you override it. For complete control, you can
+ also override Data().
+
+
+
+ Most hook functions take a channel argument. Even though MIDI channels are
+ really numbered 1 through 16, the hook functions work with channels 0 through
+ 15. The performance time for the event is specified in microseconds relative to
+ the system time base. A performance time that is 0 (or really any time in the
+ past) means "play as soon as possible". See the
+ for more information about timing and consumers.
+
+
+
+ The thread driving the consumer's events is a very high priority real time
+ thread. Events should be handled as quickly as possible (not counting
+ snoozing). If non-time-critical computation is needed it may be wise to queue
+ events up for a lower priority thread to handle them external to the main event
+ thread.
+
+
+
+ BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
+
+
+ Creates a new local consumer endpoint.
+
+
+
+ The new endpoint is not visible to other applications until you Register() it.
+
+
+
+ You can tell the constructor what the name of the new consumer will be. If you
+ pass NULL (or use the default argument), then the consumer's name will be an
+ empty string. It won't be NULL, since endpoint names cannot be NULL.
+
+
+
+ There is no guarantee that the endpoint will be successfully created. For
+ example, the Midi Server may not be running. Therefore, you should always call
+ IsValid() after creating a new endpoint to make sure that everything went okay.
+ If not, Release() the object to reclaim memory and abort gracefully.
+
+
+
+
+ MyConsumer* cons = new MyConsumer(...);
+ if (!cons->IsValid())
+ {
+ cons->Release();
+ ...exit gracefully...
+ }
+
+
+
+
+
+ void BMidiLocalConsumer::SetLatency(bigtime_t latency)
+
+
+ Changes the published latency of the consumer.
+
+
+
+
+
+ int32 BMidiLocalConsumer::GetProducerID()
+
+
+ Returns the ID of the producer that most recently sent a MIDI event to
+ this consumer.
+
+
+
+ You can call this from one of the hooks to determine which producer the event
+ came from.
+
+
+
+
+ void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
+
+
+ Requests that the Timeout() hook will be called at some point
+
+
+
+ This method asks the consumer thread to call the Timeout() hook as soon as
+ possible after the timeout expires. For every call to SetTimeout(), the
+ Timeout() hook is only called once. Note: the term "timeout" may be a little
+ misleading; the hook will always be called, even if events are received
+ in the mean time. Apparently, this facility is handy for dealing with early
+ events.
+
+
+
+
+ Note that the event thread blocks on the consumer's port as long as no events
+ arrive. By default no timeout is set, and as a result the thread blocks
+ forever. Your call to SetTimeout() doesn't change this. The new timeout value
+ will go into effect the next time the thread tries to read from the port, i.e.
+ after the first event has been received. If no event ever comes in, the
+ Timeout() hook will never be called. This also means that you cannot cancel a
+ timeout once you have set it. To repeat, calling SetTimeout() only takes effect
+ after at least one new event has been received.
+
+
+
+ Parameters:
+
+ when An absolute time that's
+ measured against the system clock.
+ data A pointer to a "cookie" that
+ you can pass along to Timeout(). The data is not copied, so
+ you must ensure that the pointer remains valid until Timeout() is
+ called. You typically delete the data inside Timeout().
+
+
+
+
+
+ void BMidiLocalConsumer::Timeout(void* data)
+
+
+ Hook function that is called per your own request.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::Data(
+ uchar* data, size_t length, bool atomic, bigtime_t time)
+
+
+ Invoked when raw MIDI is received
+
+
+
+ What the default implementation of Data() does depends on the value of atomic.
+ If atomic is true, the data received comprises a single MIDI event; i.e. one
+ status byte followed by the appropriate number of data bytes and nothing else.
+ In this case, Data() calls the event-specific hook function that corresponds to
+ that status byte. This optimization is used by the Midi Kit to allow faster
+ dispatch of events generated by the specific Spray functions from
+ BMidiLocalProducer.
+
+
+
+ If atomic is false, Data() ignores the MIDI event. If you want a consumer to
+ handle non-atomic events, you have to override Data() and program this
+ yourself. In that case, you probably also want to call the default
+ implementation to handle the "normal" MIDI events.
+
+
+
+ Data() is rarely overridden, but you can override it if you want to. If you do,
+ remember that the data buffer is owned by the Midi Kit. Do not attempt to
+ modify or free it, lest you wish to be laughed at by other developers.
+
+
+
+ Parameters:
+
+ data the MIDI event data
+ length byte size of the data buffer
+ atomic whether the data buffer contains
+ a single complete MIDI event
+ time the requested performance time of the event
+
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::NoteOff(
+ uchar channel, uchar note, uchar velocity, bigtime_t time)
+
+
+ Invoked when a Note Off event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::NoteOn(
+ uchar channel, uchar note, uchar velocity, bigtime_t time)
+
+
+ Invoked when a Note On event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::KeyPressure(
+ uchar channel, uchar note, uchar pressure, bigtime_t time)
+
+
+ Invoked when a Polyphonic Pressure (Aftertouch) event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::ControlChange(
+ uchar channel, uchar controlNumber, uchar controlValue, bigtime_t time)
+
+
+ Invoked when a Controller Change event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::ProgramChange(
+ uchar channel, uchar programNumber, bigtime_t time)
+
+
+ Invoked when a Program Change event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::ChannelPressure(
+ uchar channel, uchar pressure, bigtime_t time)
+
+
+ Invoked when a Channel Pressure event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::PitchBend(
+ uchar channel, uchar lsb, uchar msb, bigtime_t time)
+
+
+ Invoked when a Pitch Bend event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::SystemExclusive(
+ void* data, size_t length, bigtime_t time)
+
+
+
+ Invoked when a System Exclusive event is received
+
+
+
+ The data does not include the sysex start and end control bytes (0xF0 and 0xF7),
+ only the payload of the sysex message.
+
+
+
+ The data belongs to the Midi Kit and is only valid for the duration of this
+ event. You may not modify or free it.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::SystemCommon(
+ uchar status, uchar data1, uchar data2, bigtime_t time)
+
+
+ Invoked when a System Common event is received.
+
+
+
+ Not all data bytes are used for all common events. Unused bytes are set to 0.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::SystemRealTime(
+ uchar status, bigtime_t time)
+
+
+ Invoked when a Real Time event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
+
+
+ Invoked when a Tempo Change event is received
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
+
+
+ Not used
+
+
+
diff --git a/src/documentation/haiku_book/midi/midi2localproducer.xml b/src/documentation/haiku_book/midi/midi2localproducer.xml
new file mode 100644
index 0000000000..c2339b7054
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2localproducer.xml
@@ -0,0 +1,401 @@
+
+
+
+ BMidiLocalProducer
+
+
+ You create a BMidiLocalProducer if you want your application to send MIDI
+ events. You use the various spray functions to send events to all connected
+ consumers. If no consumers are connected to the producer, any calls to the
+ spray functions are ignored.
+
+
+
+ Most spray functions accept a channel argument. Even though MIDI channels are
+ really numbered 1 through 16, the spray functions work with channels 0 through
+ 15. You can also specify the performance time for the event using the time
+ argument. Specify 0 (or any time in the past) to perform the event "now", i.e.
+ as soon as possible. You can also schedule events to be performed in the
+ future, by passing a time such as system_time() + 5000000, which means 5
+ seconds from now.
+
+
+
+ Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly
+ ever need to derive a class from BMidiLocalProducer. The only reason for
+ subclassing is when you need to know when the producer gets connected or
+ disconnected.
+
+
+
+ Also unlike consumers, local producers have no thread of control directly
+ associated with them. If you want to send out the MIDI events from a different
+ thread, you will have to create one yourself.
+
+
+
+ BMidiLocalProducer::BMidiLocalProducer(const char *name = NULL)
+
+
+ Creates a new local producer endpoint.
+
+
+
+ The new endpoint is not visible to other applications until you Register() it.
+
+
+
+ You can tell the constructor what the name of the new producer will be. If you
+ pass NULL (or use the default argument), then the producer's name will be an
+ empty string. It won't be NULL, since endpoint names cannot be NULL.
+
+
+
+ There is no guarantee that the endpoint will be successfully created. For
+ example, the Midi Server may not be running. Therefore, you should always call
+ IsValid() after creating a new endpoint to make sure that everything went okay.
+ If not, Release() the object to reclaim memory and abort gracefully.
+
+
+
+
+ BMidiLocalProducer* prod = new BMidiLocalProducer(...);
+ if (!prod->IsValid())
+ {
+ prod->Release();
+ ...exit gracefully...
+ }
+
+
+
+
+
+ void BMidiLocalProducer::Connected(BMidiConsumer* cons)
+
+
+ Invoked when a new consumer is connected to this producer
+
+
+
+ Although typical notifications (i.e. from BMidiRoster's "watching" facility)
+ are only sent if it is some other app that is performing the operation,
+ Connected() is also called if you are making the connection yourself.
+
+
+
+ If you override this hook, you don't have to call the default implementation,
+ because that does nothing.
+
+
+
+ cons The newly connected consumer. The reference count of the consumer
+ object is not increased, so you should not Release() it. However, if you want
+ to keep track of the consumer beyond this function, you should first Acquire()
+ it, and Release() it when you are done.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::Disconnected(BMidiConsumer* cons)
+
+
+ Invoked when a consumer is disconnected from this producer.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SprayData(
+ void* data, size_t length, bool atomic = false, bigtime_t time = 0) const
+
+
+ Sends raw MIDI data downstream to all connected consumers
+
+
+
+ Typically you won't have to call SprayData(); the other spray functions will do
+ just fine. If you do call it, remember that you retain ownership of the data
+ and that you are responsible for freeing it at some point. (Even though data is
+ not declared const, the function does not change it.)
+
+
+
+ With atomic set to false, you can send a MIDI message in segments (perhaps for
+ a large sysex dump). However, when you do this, you are on your own. The Midi
+ Kit only tags the data as being non-atomic, but offers no additional support.
+ The default implementation of BMidiLocalConsumer completely ignores such
+ events. To handle non-atomic MIDI data, you should override the
+ BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
+ BMidiLocalProducer's other spray functions always send atomic data.
+
+
+
+ Parameters:
+
+ data the MIDI event data
+ length byte size of the data buffer
+ atomic whether the data buffer contains
+ a single complete MIDI event
+ time the required performance time of the event
+
+
+
+
+
+ void BMidiLocalProducer::SprayNoteOff(
+ uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
+
+
+ Sends a Note Off event to all connected consumers
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SprayNoteOn(
+ uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
+
+
+ Sends a Note On event to all connected consumers
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SprayKeyPressure(
+ uchar channel, uchar note, uchar pressure, bigtime_t time = 0) const
+
+
+ Sends a Polyphonic Pressure (Aftertouch) event to all connected
+ consumers.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SprayControlChange(
+ uchar channel, uchar controlNumber, uchar controlValue,
+ bigtime_t time = 0) const
+
+
+ Sends a Controller Change event to all connected consumers.
+
+
+
+ See Also and
+
+
+
+
+
+ BMidiLocalProducer::SprayProgramChange(
+ uchar channel, uchar programNumber, bigtime_t time = 0) const
+
+
+ Sends a Program Change event to all connected consumers
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SprayChannelPressure(
+ uchar channel, uchar pressure, bigtime_t time = 0) const
+
+
+ Sends a Channel Pressure event to all connected consumers
+
+
+
+ See also
+
+
+
+
+ void BMidiLocalProducer::SprayPitchBend(
+ uchar channel, uchar lsb, uchar msb, bigtime_t time = 0) const
+
+
+ Sends a Pitch Bend event to all connected consumers
+
+
+
+ See Also
+
+
+
+
+
+ void BMidiLocalProducer::SpraySystemExclusive(
+ void* data, size_t length, bigtime_t time = 0) const
+
+
+ Sends a System Exclusive event to all connected consumers
+
+
+
+ You retain ownership of the data and are responsible for freeing it. Even
+ though data is not declared const, the function does not change it. Even though
+ the amount of data may be quite large, this function always sends sysex
+ messages as an atomic block of data.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SpraySystemCommon(
+ uchar status, uchar data1, uchar data2, bigtime_t time = 0) const
+
+
+ Sends a System Common event to the connected consumers
+
+
+
+ The status byte must be one of the following:
+
+
+ System Status
+
+
+
+
+
+
+ 0xF1
+ B_MIDI_TIME_CODE
+ data1 only
+
+
+ 0xF2
+ B_SONG_POSITION
+ data1 and data2
+
+
+ 0xF3
+ B_SONG_SELECT
+ data1 only
+
+
+ 0xF5
+ B_CABLE_MESSAGE
+ data1 only
+
+
+ 0xF6
+ B_TUNE_REQUEST
+ no data
+
+
+ 0xF7
+ B_SYS_EX_END
+ no data
+
+
+
+
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SpraySystemRealTime(
+ uchar status, bigtime_t time = 0) const
+
+
+ Sends a Real Time event to the connected consumers
+
+
+
+ The status byte must be one of the following:
+
+
+
+
+
+ Because of their high priority, the MIDI specification allows real time
+ messages to "interleave" with other MIDI messages. A large sysex dump, for
+ example, may be interrupted by a real time event. The Midi Kit, however,
+ doesn't care. If you (or another producer) have just sent a big system
+ exclusive to a consumer, any following real time message will simply have to
+ wait until the consumer has dealt with the sysex.
+
+
+
+ See Also
+
+
+
+
+ void BMidiLocalProducer::SprayTempoChange(
+ int32 bpm, bigtime_t time = 0) const
+
+ Sends a Tempo Change event to the connected consumers.
+
+
+
+ This kind of Tempo Change event is not really part of the MIDI spec, rather
+ it is an extension from the SMF (Standard MIDI File) format.
+
+
+
+ See Also
+
+
+
diff --git a/src/documentation/haiku_book/midi/midi2producer.xml b/src/documentation/haiku_book/midi/midi2producer.xml
new file mode 100644
index 0000000000..173288da09
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2producer.xml
@@ -0,0 +1,115 @@
+
+
+
+ BMidiProducer
+
+
+ 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.
+
+
+
+ status_t BMidiProducer::Connect(BMidiConsumer* cons)
+
+
+ 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.
+
+
+
+ Returns 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.
+
+
+
+ See Also
+
+
+
+
+ status_t BMidiProducer::Disconnect(BMidiConsumer* cons)
+
+
+ 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.
+
+
+
+ Returns B_OK on success, or an error code if there was no connection to break
+
+
+
+ See Also
+
+
+
+
+ bool BMidiProducer::IsConnected(BMidiConsumer* cons) const
+
+
+ Determines whether a consumer is connected to this producer
+
+
+
+ See Also and
+
+
+
+
+
+ BList* BMidiProducer::Connections() const
+
+
+ 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:
+
+
+
+
+ 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
+ you delete the list or they will go all leaky on you.
+
+
+
diff --git a/src/documentation/haiku_book/midi/midi2roster.xml b/src/documentation/haiku_book/midi/midi2roster.xml
new file mode 100644
index 0000000000..d2ea39b740
--- /dev/null
+++ b/src/documentation/haiku_book/midi/midi2roster.xml
@@ -0,0 +1,540 @@
+
+
+
+ BMidiRoster
+
+
+ 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);
+ }
+
+
+
+
+ BMidiEndpoint* BMidiRoster::NextEndpoint(int32* id)
+
+
+ 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 BMidiEndpoint::Release() it when you are
+ done.
+
+
+
+
+ BMidiProducer* BMidiRoster::NextProducer(int32* id)
+
+
+ Returns the next producer from the roster
+
+
+
+ Like NextEndpoint(), but only returns producer endpoints.
+
+
+
+ See Also and
+ .
+
+
+
+
+ BMidiConsumer* BMidiRoster::NextConsumer(int32* id)
+
+
+ Returns the next consumer from the roster
+
+
+
+ Like NextEndpoint(), but only returns consumer endpoints.
+
+
+
+ See Also and
+ .
+
+
+
+
+ BMidiEndpoint* BMidiRoster::FindEndpoint(
+ int32 id, bool localOnly = false)
+
+
+ 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 \link BMidiEndpoint::Release() Release() \endlink an endpoint
+ when you are done with it:
+
+ BMidiEndpoint* endp = BMidiRoster::FindEndpoint(someID);
+ if (endp != NULL)
+ {
+ ...do stuff with the endpoint...
+ endp->Release();
+ }
+
+
+
+
+
+ BMidiProducer* BMidiRoster::FindProducer(
+ int32 id, bool localOnly = false)
+
+
+ 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 and
+ .
+
+
+
+
+ BMidiConsumer* BMidiRoster::FindConsumer(
+ int32 id, bool localOnly = false)
+
+
+ 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 and
+ .
+
+
+
+
+ void BMidiRoster::StartWatching(const BMessenger* msngr)
+
+
+ Start receiving notifications from the Midi Roster
+
+
+
+ When you start watching, BMidiRoster sends you notifications for all currently
+ publishedremote 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
+ BMidiProducer::Connect()'s to a producer, or when they
+ BMidiProducer::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;
+ }
+ }
+
+
+
+
+ See Also"The possible be:op codes (BMidiOp)".
+
+
+
+
+ void BMidiRoster::StopWatching()
+
+
+ Stop receiving notifications from the Midi Roster
+
+
+
+ See Also
+
+
+
+
+ status_t BMidiRoster::Register(BMidiEndpoint* object)
+
+
+ Publishes an endpoint to other applications
+
+
+
+ Calls BMidiEndpoint's BMidiEndpoint::Register()
+ method to publish an endpoint, which makes it visible to other applications.
+
+
+
+
+ status_t BMidiRoster::Unregister(BMidiEndpoint* object)
+
+
+ Hides an endpoint from other applications
+
+
+
+ Calls BMidiEndpoint's BMidiEndpoint::Unregister()
+ method to hide a previously published endpoint from other applications
+
+
+
+
+ BMidiRoster* BMidiRoster::MidiRoster()
+
+
+ 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.
+
+
+
diff --git a/src/documentation/haiku_book/midikit.xml b/src/documentation/haiku_book/midikit.xml
index 6176effe54..4b3141fe39 100644
--- a/src/documentation/haiku_book/midikit.xml
+++ b/src/documentation/haiku_book/midikit.xml
@@ -4,5 +4,8 @@
The Midi Kit
+
+
+