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

#include <MidiProducer.h>

Public Member Functions
	BMidiLocalProducer (const char *name=NULL)
	Creates a new local producer endpoint.

virtual void	Connected (BMidiConsumer *cons)
	Invoked when a new consumer is connected to this producer.

virtual void	Disconnected (BMidiConsumer *cons)
	Invoked when a consumer is disconnected from this producer.

void	SprayChannelPressure (uchar channel, uchar pressure, bigtime_t time=0) const
	Sends a Channel Pressure event to all connected consumers.

void	SprayControlChange (uchar channel, uchar controlNumber, uchar controlValue, bigtime_t time=0) const
	Sends a Controller Change event to all connected consumers.

void	SprayData (void *data, size_t length, bool atomic=false, bigtime_t time=0) const
	Sends raw MIDI data downstream to all connected consumers.

void	SprayKeyPressure (uchar channel, uchar note, uchar pressure, bigtime_t time=0) const
	Sends a Polyphonic Pressure (Aftertouch) event to all connected consumers.

void	SprayNoteOff (uchar channel, uchar note, uchar velocity, bigtime_t time=0) const
	Sends a Note Off event to all connected consumers.

void	SprayNoteOn (uchar channel, uchar note, uchar velocity, bigtime_t time=0) const
	Sends a Note On event to all connected consumers.

void	SprayPitchBend (uchar channel, uchar lsb, uchar msb, bigtime_t time=0) const
	Sends a Pitch Bend event to all connected consumers.

void	SprayProgramChange (uchar channel, uchar programNumber, bigtime_t time=0) const
	Sends a Program Change event to all connected consumers.

void	SpraySystemCommon (uchar status, uchar data1, uchar data2, bigtime_t time=0) const
	Sends a System Common event to the connected consumers.

void	SpraySystemExclusive (void *data, size_t length, bigtime_t time=0) const
	Sends a System Exclusive event to all connected consumers.

void	SpraySystemRealTime (uchar status, bigtime_t time=0) const
	Sends a Real Time event to the connected consumers.

void	SprayTempoChange (int32 beatsPerMinute, bigtime_t time=0) const
	Sends a Tempo Change event to the connected consumers.

Public Member Functions inherited from BMidiProducer
status_t	Connect (BMidiConsumer *cons)
	Connects a consumer to this producer.

BList *	Connections () const
	Returns a list with all connected consumers.

status_t	Disconnect (BMidiConsumer *cons)
	Disconnects a consumer from this producer.

bool	IsConnected (BMidiConsumer *cons) const
	Determines whether a consumer is connected to this producer.

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 producer endpoint that is created by your own application.

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.

Constructor & Destructor Documentation

◆ BMidiLocalProducer()

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

Member Function Documentation

◆ Connected()

void BMidiLocalProducer::Connected ( BMidiConsumer * cons )

virtual

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.

Parameters

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: Disconnected()

◆ Disconnected()

void BMidiLocalProducer::Disconnected ( BMidiConsumer * cons )

virtual

Invoked when a consumer is disconnected from this producer.

See also: Connected()

◆ SprayChannelPressure()

void BMidiLocalProducer::SprayChannelPressure	(	uchar	channel,
		uchar	pressure,
		bigtime_t	time = `0`
	)		const

Sends a Channel Pressure event to all connected consumers.

See also: BMidiLocalConsumer::ChannelPressure()

◆ SprayControlChange()

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: Midi2Defs.h; BMidiLocalConsumer::ControlChange()

◆ SprayData()

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.

See also: BMidiLocalConsumer::Data()

◆ SprayKeyPressure()

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: BMidiLocalConsumer::KeyPressure()

◆ SprayNoteOff()

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: BMidiLocalConsumer::NoteOff()

◆ SprayNoteOn()

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: BMidiLocalConsumer::NoteOn()

◆ SprayPitchBend()

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: BMidiLocalConsumer::PitchBend()

◆ SprayProgramChange()

void BMidiLocalProducer::SprayProgramChange	(	uchar	channel,
		uchar	programNumber,
		bigtime_t	time = `0`
	)		const

Sends a Program Change event to all connected consumers.

See also: BMidiLocalConsumer::ProgramChange()

◆ SpraySystemCommon()

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:

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: BMidiLocalConsumer::SystemCommon()

◆ SpraySystemExclusive()

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: BMidiLocalConsumer::SystemExclusive()

◆ SpraySystemRealTime()

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:

0xf8	`B_TIMING_CLOCK`
0xfa	`B_START`
0xfb	`B_CONTINUE`
0xfc	`B_STOP`
0xfe	`B_ACTIVE_SENSING`
0xff	`B_SYSTEM_RESET`

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: BMidiLocalConsumer::SystemRealTime()

◆ SprayTempoChange()

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: BMidiLocalConsumer::TempoChange()

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BMidiLocalProducer()

Member Function Documentation

◆ Connected()

◆ Disconnected()

◆ SprayChannelPressure()

◆ SprayControlChange()

◆ SprayData()

◆ SprayKeyPressure()

◆ SprayNoteOff()

◆ SprayNoteOn()

◆ SprayPitchBend()

◆ SprayProgramChange()

◆ SpraySystemCommon()

◆ SpraySystemExclusive()

◆ SpraySystemRealTime()

◆ SprayTempoChange()