Loading...
Searching...
No Matches
Allows creating new connections to endpoints, and also creating new virtual endpoints. More...
Public Member Functions | |
| String | getName () const |
| Returns the name that was provided when creating this session, or an empty string if the session is not alive. | |
| Input | connectInput (const EndpointId &, PacketProtocol) |
| Creates a connection to a particular endpoint. | |
| Output | connectOutput (const EndpointId &) |
| Creates a connection to a particular endpoint. | |
| VirtualEndpoint | createVirtualEndpoint (const String &name, const DeviceInfo &deviceInfo, const String &productInstanceID, PacketProtocol protocol, Span< const Block > initialBlocks, BlocksAreStatic) |
| Returns a new VirtualEndpoint if virtual endpoints are supported and the configuration is valid. | |
| LegacyVirtualInput | createLegacyVirtualInput (const String &name) |
| Creates a MIDI 1.0-compatible input port. | |
| LegacyVirtualOutput | createLegacyVirtualOutput (const String &name) |
| Creates a MIDI 1.0-compatible output port. | |
| bool | isAlive () const |
| True if this session was created successfully and is currently alive. | |
| operator bool () const | |
| Session (const Session &) | |
| Session (Session &&) noexcept | |
| Session & | operator= (const Session &) |
| Session & | operator= (Session &&) noexcept |
| ~Session () | |
Allows creating new connections to endpoints, and also creating new virtual endpoints.
The session is internally reference counted, meaning that the system resources represented by the session won't be released until the Session object, along with every Input, Output, VirtualEndpoint, LegacyVirtualInput, and LegacyVirtualOutput that it created has been destroyed.
Internally, sessions cache open connections, so that multiple Inputs or Outputs to the same endpoint will share resources associated with that connection. Therefore, in order to minimise resource usage, you should create as few sessions as possible, and re-use them when creating new connections. It may still make sense to have a separate session for logically discrete components of your project, e.g. a multi-window application where each window has its own document with an associated MIDI configuration.
| universal_midi_packets::Session::Session | ( | const Session & | ) |
References Session().
Referenced by operator=(), operator=(), Session(), Session(), and ~Session().
| universal_midi_packets::Session::~Session | ( | ) |
References Session().
| String universal_midi_packets::Session::getName | ( | ) | const |
Returns the name that was provided when creating this session, or an empty string if the session is not alive.
| Input universal_midi_packets::Session::connectInput | ( | const EndpointId & | , |
| PacketProtocol | ) |
Creates a connection to a particular endpoint.
On failure, returns a disconnected connection (i.e. isAlive() returns false). Passing an EndpointId denoting an endpoint that can only receive messages will fail.
Incoming messages will be automatically converted to the specified protocol, regardless of their actual protocol 'on the wire'.
If the session is not alive, this will always fail and return an Input that is not alive.
| Output universal_midi_packets::Session::connectOutput | ( | const EndpointId & | ) |
Creates a connection to a particular endpoint.
On failure, returns a disconnected connection (i.e. isAlive() returns false). Passing an EndpointId denoting an endpoint that can only send messages will fail.
If the session is not alive, this will always fail and return an Output that is not alive.
| VirtualEndpoint universal_midi_packets::Session::createVirtualEndpoint | ( | const String & | name, |
| const DeviceInfo & | deviceInfo, | ||
| const String & | productInstanceID, | ||
| PacketProtocol | protocol, | ||
| Span< const Block > | initialBlocks, | ||
| BlocksAreStatic | ) |
Returns a new VirtualEndpoint if virtual endpoints are supported and the configuration is valid.
If creating the endpoint fails, this will return an invalid VirtualEndpoint.
To actually send and receive messages through this endpoint, use connectInput() and connectOutput(), passing the result of VirtualEndpoint::getId(). This will create an Input or Output that can be used in the same way as for any other kind of device.
If the function blocks are static, all blocks must be marked as active. If the function blocks are not static, then blocks may be initially inactive. The number of declared function blocks may not change while the device is active, so if you need a dynamic number of blocks, mark the block layout as non-static and mark any initially unused blocks as inactive.
Only a maximum of 32 blocks are allowed on an endpoint. If you pass more than 32 blocks, this function will fail.
This function may also fail if virtual devices are not available on the current platform.
Some platforms (older macOS, older Linux) support virtual MIDI 1.0 devices but not virtual UMP devices. On such platforms, this function will fail. You may wish to check for this case, and to call createLegacyVirtualInput() and/or createLegacyVirtualOutput() as a fall-back.
If the session is not alive, this will always fail and return a VirtualEndpoint that is not alive.
On Android, this function will only ever succeed on newer platforms (API level >= 35). You may need to call Endpoints::setVirtualMidiUmpServiceActive() to make the virtual UMP service available. You can listen for state changes in the virtual MIDI service using EndpointsListener::virtualMidiServiceActiveChanged(). A maximum of one VirtualEndpoint may be alive at any time on Android, and attempting to create additional virtual endpoints will fail.
References name.
| LegacyVirtualInput universal_midi_packets::Session::createLegacyVirtualInput | ( | const String & | name | ) |
Creates a MIDI 1.0-compatible input port.
Where supported by platform APIs, this will explicitly create a single-group MIDI 1.0 port.
To use the input, pass the result of LegacyVirtualInput::getId() to connectInput().
There are some special cases to keep in mind:
References name.
| LegacyVirtualOutput universal_midi_packets::Session::createLegacyVirtualOutput | ( | const String & | name | ) |
Creates a MIDI 1.0-compatible output port.
Where supported by platform APIs, this will explicitly create a single-group MIDI 1.0 port.
To use the output, pass the result of LegacyVirtualOutput::getId() to connectOutput().
There are some special cases to keep in mind:
References name.
| bool universal_midi_packets::Session::isAlive | ( | ) | const |
True if this session was created successfully and is currently alive.
Referenced by operator bool().
|
explicit |
References isAlive().
