All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions | List of all members
BMidiLocalConsumer Class Reference

A consumer endpoint that is created by your own application. More...

#include <MidiConsumer.h>

Inherits BMidiConsumer.

Public Member Functions

 BMidiLocalConsumer (const char *name=NULL)
 Creates a new local consumer endpoint.
 
virtual void AllNotesOff (bool justChannel, bigtime_t time)
 Not used.
 
virtual void ChannelPressure (uchar channel, uchar pressure, bigtime_t time)
 Invoked when a Channel Pressure event is received.
 
virtual void ControlChange (uchar channel, uchar controlNumber, uchar controlValue, bigtime_t time)
 Invoked when a Controller Change event is received.
 
virtual void Data (uchar *data, size_t length, bool atomic, bigtime_t time)
 Invoked when raw MIDI is received.
 
int32 GetProducerID ()
 Returns the ID of the producer that most recently sent a MIDI event to this consumer.
 
virtual void KeyPressure (uchar channel, uchar note, uchar pressure, bigtime_t time)
 Invoked when a Polyphonic Pressure (Aftertouch) event is received.
 
virtual void NoteOff (uchar channel, uchar note, uchar velocity, bigtime_t time)
 Invoked when a Note Off event is received.
 
virtual void NoteOn (uchar channel, uchar note, uchar velocity, bigtime_t time)
 Invoked when a Note On event is received.
 
virtual void PitchBend (uchar channel, uchar lsb, uchar msb, bigtime_t time)
 Invoked when a Pitch Bend event is received.
 
virtual void ProgramChange (uchar channel, uchar programNumber, bigtime_t time)
 Invoked when a Program Change event is received.
 
void SetLatency (bigtime_t latency)
 Changes the published latency of the consumer.
 
void SetTimeout (bigtime_t when, void *data)
 Requests that the Timeout() hook will be called at some point.
 
virtual void SystemCommon (uchar status, uchar data1, uchar data2, bigtime_t time)
 Invoked when a System Common event is received.
 
virtual void SystemExclusive (void *data, size_t length, bigtime_t time)
 Invoked when a System Exclusive event is received.
 
virtual void SystemRealTime (uchar status, bigtime_t time)
 Invoked when a Real Time event is received.
 
virtual void TempoChange (int32 beatsPerMinute, bigtime_t time)
 Invoked when a Tempo Change event is received.
 
virtual void Timeout (void *data)
 Hook function that is called per your own request.
 
- Public Member Functions inherited from BMidiConsumer
bigtime_t Latency () const
 Returns the latency of this consumer.
 
- Public Member Functions inherited from BMidiEndpoint
status_t Acquire ()
 Increments the endpoint's reference count.
 
status_t GetProperties (BMessage *properties) const
 Reads the properties of the endpoint.
 
int32 ID () const
 Returns the ID of the endpoint.
 
bool IsConsumer () const
 Determines whether this endpoint is a BMidiConsumer.
 
bool IsLocal () const
 Determines whether this endpoint represents a local object.
 
bool IsPersistent () const
 Not used.
 
bool IsProducer () const
 Determines whether this endpoint is a BMidiProducer.
 
bool IsRemote () const
 Determines whether this endpoint is a proxy for a remote object.
 
bool IsValid () const
 Determines whether the endpoint still exists.
 
const char * Name () const
 Returns the name of the endpoint.
 
status_t Register ()
 Publishes the endpoint on the roster.
 
status_t Release ()
 Decrements the endpoint's reference count.
 
void SetName (const char *name)
 Changes the name of the endpoint.
 
status_t SetProperties (const BMessage *properties)
 Changes the properties of the endpoint.
 
status_t Unregister ()
 Hides the endpoint from the roster/.
 

Detailed Description

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 introduction 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.

Constructor & Destructor Documentation

◆ BMidiLocalConsumer()

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...
}

Member Function Documentation

◆ ChannelPressure()

void BMidiLocalConsumer::ChannelPressure ( uchar  channel,
uchar  pressure,
bigtime_t  time 
)
virtual

Invoked when a Channel Pressure event is received.

See also
BMidiLocalProducer::SprayChannelPressure()

◆ ControlChange()

void BMidiLocalConsumer::ControlChange ( uchar  channel,
uchar  controlNumber,
uchar  controlValue,
bigtime_t  time 
)
virtual

Invoked when a Controller Change event is received.

See also
BMidiLocalProducer::SprayControlChange()

◆ Data()

void BMidiLocalConsumer::Data ( uchar data,
size_t  length,
bool  atomic,
bigtime_t  time 
)
virtual

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
datathe MIDI event data
lengthbyte size of the data buffer
atomicwhether the data buffer contains a single complete MIDI event
timethe requested performance time of the event
See also
BMidiLocalProducer::SprayData()

◆ GetProducerID()

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.

◆ KeyPressure()

void BMidiLocalConsumer::KeyPressure ( uchar  channel,
uchar  note,
uchar  pressure,
bigtime_t  time 
)
virtual

Invoked when a Polyphonic Pressure (Aftertouch) event is received.

See also
BMidiLocalProducer::SprayKeyPressure()

◆ NoteOff()

void BMidiLocalConsumer::NoteOff ( uchar  channel,
uchar  note,
uchar  velocity,
bigtime_t  time 
)
virtual

Invoked when a Note Off event is received.

See also
BMidiLocalProducer::SprayNoteOff()

◆ NoteOn()

void BMidiLocalConsumer::NoteOn ( uchar  channel,
uchar  note,
uchar  velocity,
bigtime_t  time 
)
virtual

Invoked when a Note On event is received.

See also
BMidiLocalProducer::SprayNoteOn()

◆ PitchBend()

void BMidiLocalConsumer::PitchBend ( uchar  channel,
uchar  lsb,
uchar  msb,
bigtime_t  time 
)
virtual

Invoked when a Pitch Bend event is received.

See also
BMidiLocalProducer::SprayPitchBend()

◆ ProgramChange()

void BMidiLocalConsumer::ProgramChange ( uchar  channel,
uchar  programNumber,
bigtime_t  time 
)
virtual

Invoked when a Program Change event is received.

See also
BMidiLocalProducer::SprayProgramChange()

◆ SetLatency()

void BMidiLocalConsumer::SetLatency ( bigtime_t  latency)

Changes the published latency of the consumer.

See also
Latency()

◆ SetTimeout()

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
whenAn absolute time that's measured against the system clock.
dataA 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().

◆ SystemCommon()

void BMidiLocalConsumer::SystemCommon ( uchar  status,
uchar  data1,
uchar  data2,
bigtime_t  time 
)
virtual

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
BMidiLocalProducer::SpraySystemCommon()

◆ SystemExclusive()

void BMidiLocalConsumer::SystemExclusive ( void *  data,
size_t  length,
bigtime_t  time 
)
virtual

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
BMidiLocalProducer::SpraySystemExclusive()

◆ SystemRealTime()

void BMidiLocalConsumer::SystemRealTime ( uchar  status,
bigtime_t  time 
)
virtual

Invoked when a Real Time event is received.

See also
BMidiLocalProducer::SpraySystemRealTime()

◆ TempoChange()

void BMidiLocalConsumer::TempoChange ( int32  beatsPerMinute,
bigtime_t  time 
)
virtual

Invoked when a Tempo Change event is received.

See also
BMidiLocalProducer::SprayTempoChange()

◆ Timeout()

void BMidiLocalConsumer::Timeout ( void *  data)
virtual

Hook function that is called per your own request.

See also
SetTimeout()