Instances of this type are responsible for parsing and interpreting incoming MIDI-CI messages, and for sending MIDI-CI messages to other devices. More...

#include <juce_CIDevice.h>

Inheritance diagram for juce::midi_ci::Device:

[legend]

Collaboration diagram for juce::midi_ci::Device:

[legend]

Public Types
using	Features = DeviceFeatures

using	Listener = DeviceListener

using	Options = DeviceOptions

Public Member Functions
	Device (const Options &opt)
	Constructs a device using the provided options.

	Device (Device &&) noexcept

	~Device () override
	Destructor, sends a message to invalidate this device's MUID.

void	abortPropertyRequest (RequestKey)
	Cancels a request started with sendPropertyGetInquiry() or sendPropertySetInquiry().

void	addListener (Listener &l)
	Adds a listener that will be notified when particular events occur.

SubscriptionKey	beginSubscription (MUID m, const PropertySubscriptionHeader &header)
	Attempts to begin a subscription with the provided attributes.

void	endSubscription (SubscriptionKey)
	Ends a previously-started subscription.

var	getChannelListForMuid (MUID x) const
	After DeviceListener::propertyExchangeCapabilitiesReceived() has been received for a particular device, this function will return that device's ChannelList if available, or a null var otherwise.

var	getDeviceInfoForMuid (MUID x) const
	After DeviceListener::propertyExchangeCapabilitiesReceived() has been received for a particular device, this function will return that device's DeviceInfo if available, or a null var otherwise.

std::vector< MUID >	getDiscoveredMuids () const
	Returns a list of all MUIDs that have been discovered by this device.

std::optional< Message::Discovery >	getDiscoveryInfoForMuid (MUID m) const
	Returns basic attributes about another device that was discovered.

std::optional< RequestID >	getIdForRequestKey (RequestKey) const
	Returns the request id corresponding to a particular request.

MUID	getMuid () const
	Returns the MUID currently associated with this device.

std::optional< int >	getNumPropertyExchangeRequestsSupportedForMuid (MUID m) const
	Returns the number of simultaneous property exchange requests supported by a particular device.

std::vector< RequestKey >	getOngoingRequests () const
	Returns all the ongoing requests.

std::vector< SubscriptionKey >	getOngoingSubscriptions () const
	Returns all the subscriptions that have been initiated by this device.

Options	getOptions () const
	Returns the configuration of this device.

ProfileHost *	getProfileHost ()
	If you set withProfileConfigurationSupported when constructing this device, this will return a pointer to an object that can be used to modify the states of the profiles for this device.

const ProfileHost *	getProfileHost () const
	If you set withProfileConfigurationSupported when constructing this device, this will return a pointer to an object that can be used to query the states of the profiles for this device.

const ChannelProfileStates *	getProfileStateForMuid (MUID m, ChannelAddress address) const
	Returns the states of the profiles on a particular channel of a device.

PropertyHost *	getPropertyHost ()
	If you set withPropertyExchangeSupported when constructing this device, this will return a pointer to an object that can be used to modify the states of the properties for this device.

const PropertyHost *	getPropertyHost () const
	If you set withPropertyExchangeSupported when constructing this device, this will return a pointer to an object that can be used to query the states of the properties for this device.

std::optional< String >	getResourceForKey (SubscriptionKey key) const
	If the provided subscription has not been cancelled, this returns the name of the subscribed resource.

var	getResourceListForMuid (MUID x) const
	After DeviceListener::propertyExchangeCapabilitiesReceived() has been received for a particular device, this function will return that device's ResourceList if available, or a null var otherwise.

std::optional< String >	getSubscribeIdForKey (SubscriptionKey key) const
	If the provided subscription has started successfully, this returns the subscribeId assigned to the subscription by the remote device.

Device &	operator= (Device &&) noexcept

void	processMessage (ump::BytesOnGroup) override
	To be called with any message that should be processed by the device.

void	removeListener (Listener &l)
	Removes a listener that was previously added with addListener().

void	sendDiscovery ()
	Sends an inquiry message.

void	sendEndpointInquiry (MUID destination, Message::EndpointInquiry endpoint)
	Sends an endpoint inquiry message.

bool	sendPendingMessages ()
	Sends any cached messages that need retrying.

void	sendProfileDetailsInquiry (MUID muid, ChannelInGroup address, Profile profile, std::byte target)
	Sends a profile details inquiry to a particular device.

void	sendProfileEnablement (MUID muid, ChannelInGroup address, Profile profile, int numChannels)
	Sets a profile on or off.

void	sendProfileInquiry (MUID muid, ChannelInGroup address)
	Sends a profile inquiry to a particular device.

void	sendProfileSpecificData (MUID muid, ChannelInGroup address, Profile profile, Span< const std::byte >)
	Sends profile data to a particular device.

void	sendPropertyCapabilitiesInquiry (MUID destination)
	Sends a property inquiry to a particular device.

std::optional< RequestKey >	sendPropertyGetInquiry (MUID m, const PropertyRequestHeader &header, std::function< void(const PropertyExchangeResult &)> onResult)
	Initiates an inquiry to fetch a property from a particular device.

std::optional< RequestKey >	sendPropertySetInquiry (MUID m, const PropertyRequestHeader &header, Span< const std::byte > body, std::function< void(const PropertyExchangeResult &)> onResult)
	Initiates an inquiry to set a property on a particular device.

Private Attributes
std::unique_ptr< Impl >	pimpl

Detailed Description

Instances of this type are responsible for parsing and interpreting incoming MIDI-CI messages, and for sending MIDI-CI messages to other devices.

Each Device can act both as a target for messages, and as a source of messages intended to inspect/configure other devices.

The member functions of Device are generally used to inspect other devices. Member functions starting with 'send' are used to send or request information from other devices; registered DeviceListeners will be notified when the Device receives a response, and then member functions named matching 'get.*ForMuid' can be used to retrieve the result of the inquiry.

If the Device does not have local profiles or properties, then responses to all incoming messages will be generated automatically using the information supplied during construction.

If the Device has profiles or properties, then you should implement a ProfileDelegate and/or a PropertyDelegate as appropriate, and pass this delegate during construction. Each Delegate will receive callbacks when a remote device makes a request of the local device, such as enabling/disabling a profile, or setting/getting property data.

Sometimes the local device must send notifications when updating its profile or property state, for example when profiles are added, or when a subscribed property is changed. Methods to send these notifications are found on the ProfileHost and PropertyHost classes.

@tags{Audio}

Member Typedef Documentation

◆ Features

using juce::midi_ci::Device::Features = DeviceFeatures

◆ Listener

using juce::midi_ci::Device::Listener = DeviceListener

◆ Options

using juce::midi_ci::Device::Options = DeviceOptions

Constructor & Destructor Documentation

◆ Device() [1/2]

juce::midi_ci::Device::Device ( const Options & opt )

explicit

Constructs a device using the provided options.

◆ Device() [2/2]

juce::midi_ci::Device::Device ( Device && )

noexcept

◆ ~Device()

juce::midi_ci::Device::~Device ( )

override

Destructor, sends a message to invalidate this device's MUID.

Member Function Documentation

◆ abortPropertyRequest()

void juce::midi_ci::Device::abortPropertyRequest ( RequestKey )

Cancels a request started with sendPropertyGetInquiry() or sendPropertySetInquiry().

This sends a property notify message indicating that the responder no longer needs to process the initial request.

◆ addListener()

void juce::midi_ci::Device::addListener ( Listener & l )

Adds a listener that will be notified when particular events occur.

Check the members of the Listener class to see the kinds of events that are reported. To receive notifications through Listener::propertySubscriptionReceived(), you must first request a subscription using sendPropertySubscriptionStart().

See also: Listener, removeListener()

◆ beginSubscription()

SubscriptionKey juce::midi_ci::Device::beginSubscription	(	MUID	m,
		const PropertySubscriptionHeader &	header
	)

Attempts to begin a subscription with the provided attributes.

Once the subscription is no longer required, cancel it by passing the SubscriptionKey to endSubscription().

◆ endSubscription()

void juce::midi_ci::Device::endSubscription ( SubscriptionKey )

Ends a previously-started subscription.

◆ getChannelListForMuid()

var juce::midi_ci::Device::getChannelListForMuid ( MUID x ) const

After DeviceListener::propertyExchangeCapabilitiesReceived() has been received for a particular device, this function will return that device's ChannelList if available, or a null var otherwise.

◆ getDeviceInfoForMuid()

var juce::midi_ci::Device::getDeviceInfoForMuid ( MUID x ) const

After DeviceListener::propertyExchangeCapabilitiesReceived() has been received for a particular device, this function will return that device's DeviceInfo if available, or a null var otherwise.

◆ getDiscoveredMuids()

std::vector< MUID > juce::midi_ci::Device::getDiscoveredMuids ( ) const

Returns a list of all MUIDs that have been discovered by this device.

◆ getDiscoveryInfoForMuid()

std::optional< Message::Discovery > juce::midi_ci::Device::getDiscoveryInfoForMuid ( MUID m ) const

Returns basic attributes about another device that was discovered.

If there's no record of the provided device, this will return nullopt.

◆ getIdForRequestKey()

std::optional< RequestID > juce::midi_ci::Device::getIdForRequestKey ( RequestKey ) const

Returns the request id corresponding to a particular request.

If the request could not be found (it never started, or already finished), then this returns nullopt.

◆ getMuid()

MUID juce::midi_ci::Device::getMuid ( ) const

Returns the MUID currently associated with this device.

This may change, e.g. if another device reports that it shares the same MUID.

◆ getNumPropertyExchangeRequestsSupportedForMuid()

std::optional< int > juce::midi_ci::Device::getNumPropertyExchangeRequestsSupportedForMuid ( MUID m ) const

Returns the number of simultaneous property exchange requests supported by a particular device.

If there's no record of this device's property capabilities (including the case where the device doesn't support property exchange at all) this will return nullopt.

Devices don't report property capabilities unless asked; you can request capabilities using inquirePropertyCapabilities().

◆ getOngoingRequests()

std::vector< RequestKey > juce::midi_ci::Device::getOngoingRequests ( ) const

Returns all the ongoing requests.

◆ getOngoingSubscriptions()

std::vector< SubscriptionKey > juce::midi_ci::Device::getOngoingSubscriptions ( ) const

Returns all the subscriptions that have been initiated by this device.

◆ getOptions()

Options juce::midi_ci::Device::getOptions ( ) const

Returns the configuration of this device.

◆ getProfileHost() [1/2]

ProfileHost * juce::midi_ci::Device::getProfileHost ( )

If you set withProfileConfigurationSupported when constructing this device, this will return a pointer to an object that can be used to modify the states of the profiles for this device.

◆ getProfileHost() [2/2]

const ProfileHost * juce::midi_ci::Device::getProfileHost ( ) const

If you set withProfileConfigurationSupported when constructing this device, this will return a pointer to an object that can be used to query the states of the profiles for this device.

◆ getProfileStateForMuid()

const ChannelProfileStates * juce::midi_ci::Device::getProfileStateForMuid	(	MUID	m,
		ChannelAddress	address
	)		const

Returns the states of the profiles on a particular channel of a device.

If the state is unknown, returns nullptr.

Devices don't report profile capabilities unless asked; you can request capabilities using inquireProfile().

◆ getPropertyHost() [1/2]

PropertyHost * juce::midi_ci::Device::getPropertyHost ( )

If you set withPropertyExchangeSupported when constructing this device, this will return a pointer to an object that can be used to modify the states of the properties for this device.

◆ getPropertyHost() [2/2]

const PropertyHost * juce::midi_ci::Device::getPropertyHost ( ) const

If you set withPropertyExchangeSupported when constructing this device, this will return a pointer to an object that can be used to query the states of the properties for this device.

◆ getResourceForKey()

std::optional< String > juce::midi_ci::Device::getResourceForKey ( SubscriptionKey key ) const

If the provided subscription has not been cancelled, this returns the name of the subscribed resource.

◆ getResourceListForMuid()

var juce::midi_ci::Device::getResourceListForMuid ( MUID x ) const

After DeviceListener::propertyExchangeCapabilitiesReceived() has been received for a particular device, this function will return that device's ResourceList if available, or a null var otherwise.

◆ getSubscribeIdForKey()

std::optional< String > juce::midi_ci::Device::getSubscribeIdForKey ( SubscriptionKey key ) const

If the provided subscription has started successfully, this returns the subscribeId assigned to the subscription by the remote device.

◆ operator=()

Device & juce::midi_ci::Device::operator= ( Device && )

noexcept

◆ processMessage()

void juce::midi_ci::Device::processMessage ( ump::BytesOnGroup )

overridevirtual

To be called with any message that should be processed by the device.

This should only be passed complete CI messages - you might find the Extractor class useful for parsing a stream of Universal MIDI Packets and extracting the CI messages. Note that this function does not synchronise with any other member function of this class. This means that you must not call this directly from the MIDI input thread if there's any chance of other member functions being called on the same instance simultaneously from other threads. It's probably easiest to send all messages onto the main thread and to limit interactions with the Device to that thread.

Implements juce::midi_ci::DeviceMessageHandler.

◆ removeListener()

void juce::midi_ci::Device::removeListener ( Listener & l )

Removes a listener that was previously added with addListener().

◆ sendDiscovery()

void juce::midi_ci::Device::sendDiscovery ( )

Sends an inquiry message.

You can use DeviceListener::deviceAdded to be notified when new devices are discovered.

This will clear the internal cache of discovered devices, and repopulate it as discovery response messages are received.

◆ sendEndpointInquiry()

void juce::midi_ci::Device::sendEndpointInquiry	(	MUID	destination,
		Message::EndpointInquiry	endpoint
	)

Sends an endpoint inquiry message.

Check the MIDI-CI spec for an explanation of the different endpoint message status codes.

Received responses will be sent to DeviceListener::endpointReceived. Responses are not cached by the Device; if you need to cache endpoint responses, you can keep your own map of MUID->response, update it in endpointReceived, and remove entries in DeviceListener::deviceRemoved.

◆ sendPendingMessages()

bool juce::midi_ci::Device::sendPendingMessages ( )

Sends any cached messages that need retrying.

Returns: true if there are no more messages to send, or false otherwise

◆ sendProfileDetailsInquiry()

void juce::midi_ci::Device::sendProfileDetailsInquiry	(	MUID	muid,
		ChannelInGroup	address,
		Profile	profile,
		std::byte	target
	)

Sends a profile details inquiry to a particular device.

DeviceListener::profileDetailsReceived will be called when the device replies.

◆ sendProfileEnablement()

void juce::midi_ci::Device::sendProfileEnablement	(	MUID	muid,
		ChannelInGroup	address,
		Profile	profile,
		int	numChannels
	)

Sets a profile on or off.

Pass 0 or less to disable the profile, or a positive number to enable it.

This also goes for group/block profiles. If the request is addressed to a group/block, then a positive number will cause a "profile on" message to be sent, and a non-positive number will cause a "profile off" message to be sent. The channel count of the sent message will always be zero for messages addressed to groups/blocks.regardless of the value of the numChannels argument.

◆ sendProfileInquiry()

void juce::midi_ci::Device::sendProfileInquiry	(	MUID	muid,
		ChannelInGroup	address
	)

Sends a profile inquiry to a particular device.

DeviceListener::profileStateReceived will be called when the device replies.

◆ sendProfileSpecificData()

void juce::midi_ci::Device::sendProfileSpecificData	(	MUID	muid,
		ChannelInGroup	address,
		Profile	profile,
		Span< const std::byte >
	)

Sends profile data to a particular device.

◆ sendPropertyCapabilitiesInquiry()

void juce::midi_ci::Device::sendPropertyCapabilitiesInquiry ( MUID destination )

Sends a property inquiry to a particular device.

If the device supports properties, this will also automatically request the ResourceList property, and then the ChannelList and DeviceInfo properties if they are present in the ResourceList.

◆ sendPropertyGetInquiry()

std::optional< RequestKey > juce::midi_ci::Device::sendPropertyGetInquiry	(	MUID	m,
		const PropertyRequestHeader &	header,
		std::function< void(const PropertyExchangeResult &)>	onResult
	)

Initiates an inquiry to fetch a property from a particular device.

Parameters

m	the MUID of the device to query
header	specifies the resource to query, along with format/encoding options
onResult	called when the transaction completes; not called if the transaction fails to start

Returns: a key uniquely identifying this request, if the transaction begins successfully, or nullopt otherwise

◆ sendPropertySetInquiry()

std::optional< RequestKey > juce::midi_ci::Device::sendPropertySetInquiry	(	MUID	m,
		const PropertyRequestHeader &	header,
		Span< const std::byte >	body,
		std::function< void(const PropertyExchangeResult &)>	onResult
	)

Initiates an inquiry to set a property on a particular device.