JUCE
Loading...
Searching...
No Matches
Public Types | Public Member Functions | List of all members
juce::midi_ci::Device Class Reference

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:

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
 
Deviceoperator= (Device &&) noexcept
 
 ~Device () override
 Destructor, sends a message to invalidate this device's MUID.
 
void processMessage (ump::BytesOnGroup) override
 To be called with any message that should be processed by the device.
 
void sendDiscovery ()
 Sends an inquiry message.
 
void sendEndpointInquiry (MUID destination, Message::EndpointInquiry endpoint)
 Sends an endpoint inquiry message.
 
void sendProfileInquiry (MUID muid, ChannelInGroup address)
 Sends a profile inquiry to a particular device.
 
void sendProfileDetailsInquiry (MUID muid, ChannelInGroup address, Profile profile, std::byte target)
 Sends a profile details 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 sendProfileEnablement (MUID muid, ChannelInGroup address, Profile profile, int numChannels)
 Sets a profile on or off.
 
void sendPropertyCapabilitiesInquiry (MUID destination)
 Sends a property inquiry to a particular device.
 
ErasedScopeGuard sendPropertyGetInquiry (MUID destination, const PropertyRequestHeader &header, std::function< void(const PropertyExchangeResult &)> onResult)
 Sends an inquiry to get a property value from another device, invoking a callback once the full transaction has completed.
 
void sendPropertySetInquiry (MUID destination, const PropertyRequestHeader &header, Span< const std::byte > body, std::function< void(const PropertyExchangeResult &)> onResult)
 Sends an inquiry to set a property value on another device, invoking a callback once the full transaction has completed.
 
void sendPropertySubscriptionStart (MUID, const PropertySubscriptionHeader &header, std::function< void(const PropertyExchangeResult &)>)
 Sends an inquiry to start a subscription to a property on a device.
 
void sendPropertySubscriptionEnd (MUID, const String &subscribeId, std::function< void(const PropertyExchangeResult &)>)
 Sends an inquiry to end a subscription to a property on a device.
 
std::vector< SubscriptiongetOngoingSubscriptionsForMuid (MUID m) const
 Returns all of the subscriptions that we have requested from another device.
 
int countOngoingPropertyTransactions () const
 Returns the number of transactions initiated by us that are yet to receive complete replies.
 
void addListener (Listener &l)
 Adds a listener that will be notified when particular events occur.
 
void removeListener (Listener &l)
 Removes a listener that was previously added with addListener().
 
MUID getMuid () const
 Returns the MUID currently associated with this device.
 
Options getOptions () const
 Returns the configuration of this device.
 
std::vector< MUIDgetDiscoveredMuids () const
 Returns a list of all MUIDs that have been discovered by this device.
 
const ProfileHostgetProfileHost () 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.
 
ProfileHostgetProfileHost ()
 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 PropertyHostgetPropertyHost () 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.
 
PropertyHostgetPropertyHost ()
 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.
 
std::optional< Message::DiscoverygetDiscoveryInfoForMuid (MUID m) const
 Returns basic attributes about another device that was discovered.
 
const ChannelProfileStatesgetProfileStateForMuid (MUID m, ChannelAddress address) const
 Returns the states of the profiles on a particular channel of a device.
 
std::optional< int > getNumPropertyExchangeRequestsSupportedForMuid (MUID m) const
 Returns the number of simultaneous property exchange requests supported by a particular device.
 
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.
 
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.
 
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.
 
- Public Member Functions inherited from juce::midi_ci::DeviceMessageHandler
 DeviceMessageHandler ()=default
 
virtual ~DeviceMessageHandler ()=default
 
 DeviceMessageHandler (const DeviceMessageHandler &)=default
 
 DeviceMessageHandler (DeviceMessageHandler &&)=default
 
DeviceMessageHandleroperator= (const DeviceMessageHandler &)=default
 
DeviceMessageHandleroperator= (DeviceMessageHandler &&)=default
 

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.

Member Typedef Documentation

◆ Features

◆ Listener

◆ Options

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

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

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

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

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

◆ sendProfileSpecificData()

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

Sends profile data to a particular device.

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

◆ 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()

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

Sends an inquiry to get a property value from another device, invoking a callback once the full transaction has completed.

Parameters
destinationthe device whose property will be set
headerinformation about the property data that will be sent
onResultthis will be called once the result of the transaction is known. If the transaction cannot start for some reason (e.g. the request is malformed, or there are too many simultaneous requests) then the function will be called immediately. Otherwise, the function will be called once the destination device has confirmed receipt of the inquiry.
Returns
a token bounding the lifetime of the request. If you need to terminate the transaction before it has completed, you can call reset() on this token, or cause its destructor to run.

◆ sendPropertySetInquiry()

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

Sends an inquiry to set a property value on another device, invoking a callback once the full transaction has completed.

Parameters
destinationthe device whose property will be set
headerinformation about the property data that will be sent
bodythe property data payload to send. If the header specifies 'ascii' encoding, then you are responsible for ensuring that no byte of the payload data has its most significant bit set. Sending the message will fail if this is not the case. Otherwise, if another encoding is specified then the payload data may contain any byte values. You should not attempt to encode the data yourself; the payload will be automatically encoded before being sent.
onResultthis will be called once the result of the transaction is known. If the transaction cannot start for some reason (e.g. the destination does not support property exchange, the request is malformed, or there are too many simultaneous requests) then the function will be called immediately. Otherwise, the function will be called once the destination device has confirmed receipt of the inquiry.

◆ sendPropertySubscriptionStart()

void juce::midi_ci::Device::sendPropertySubscriptionStart ( MUID  ,
const PropertySubscriptionHeader header,
std::function< void(const PropertyExchangeResult &)>   
)

Sends an inquiry to start a subscription to a property on a device.

The provided callback will be called to indicate whether starting the subscription succeeded or failed. When the remote device indicates that its property value has changed, DeviceListener::propertySubscriptionReceived will be called with information about the update.

◆ sendPropertySubscriptionEnd()

void juce::midi_ci::Device::sendPropertySubscriptionEnd ( MUID  ,
const String subscribeId,
std::function< void(const PropertyExchangeResult &)>   
)

Sends an inquiry to end a subscription to a property on a device.

The provided callback will be called to indicate whether the subscriber acknowledged receipt of the message. Note that the remote device may also choose to terminate the subscription of its own accord - in this case, the end request will be sent to DeviceListener::propertySubscriptionReceived.

◆ getOngoingSubscriptionsForMuid()

std::vector< Subscription > juce::midi_ci::Device::getOngoingSubscriptionsForMuid ( MUID  m) const

Returns all of the subscriptions that we have requested from another device.

Does not include subscriptions that other devices have requested from us.

◆ countOngoingPropertyTransactions()

int juce::midi_ci::Device::countOngoingPropertyTransactions ( ) const

Returns the number of transactions initiated by us that are yet to receive complete replies.

Does not include the count of unfinished requests addressed to us by other devices.

See also
PropertyHost::countOngoingTransactions()

◆ 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()

◆ removeListener()

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

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

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

◆ getOptions()

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

Returns the configuration of this device.

◆ getDiscoveredMuids()

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

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

◆ getProfileHost() [1/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.

◆ getProfileHost() [2/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.

◆ getPropertyHost() [1/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.

◆ getPropertyHost() [2/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.

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

◆ 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().

◆ 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().

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

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

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


The documentation for this class was generated from the following file: