ump_endpoint.hpp

Go to the documentation of this file.

#pragma once
 
// UMP Endpoint — abstract handle to a MIDI 2.0 UMP source/destination.
//
// A UMP endpoint is a single bidirectional logical port — on CoreMIDI 2.0 it
// wraps a `MIDIEndpointRef`, on Windows it wraps a MIDIEndpointConnection
// (WinRT MIDI 2.0), on Linux it wraps an ALSA Rawmidi UMP node. The
// Pulp surface is intentionally OS-agnostic: callers see UmpPacket in,
// UmpPacket out.
//
// Design notes:
//   - Endpoints are owned by a UmpSession. Calling code never news them
//     directly; it asks the session for one (or registers a virtual one).
//   - The receive callback fires on whatever thread the OS chose for
//     MIDI delivery (CoreMIDI: a dedicated MIDIClient thread; WinRT: the
//     UMP callback thread). Callers must not block.
//   - Send is non-blocking and lock-free where the OS allows it.
//   - Endpoints expose a stable string id (CoreMIDI unique-id; WinRT
//     EndpointDeviceId; ALSA card:device) so callers can persist a
//     selection across runs.
//
// Versus the older `MidiInput` / `MidiOutput` pair: those operate on
// MIDI 1.0 byte streams (with the WinRT/CoreMIDI backends translating
// internally). `UmpEndpoint` is the UMP-native surface; both layers
// will coexist while Pulp finishes the UMP migration.
 
#include <pulp/midi/ump.hpp>
 
#include <cstdint>
#include <functional>
#include <string>
#include <vector>
 
namespace pulp::midi {

struct UmpEndpointDirection {
    bool can_receive = false;  // we can read UMP packets from it
    bool can_send    = false;  // we can write UMP packets to it
};

struct UmpEndpointInfo {
    std::string id;
    std::string name;
    bool is_virtual = false;
    UmpEndpointDirection direction;
};

using UmpReceiveCallback = std::function<void(const UmpPacket& packet,
                                              double timestamp_sec)>;

class UmpEndpoint {
public:
    virtual ~UmpEndpoint() = default;

    virtual const UmpEndpointInfo& info() const noexcept = 0;

    virtual void set_receive_callback(UmpReceiveCallback cb) = 0;

    virtual bool send(const UmpPacket& packet) = 0;

    virtual bool is_open() const noexcept = 0;
};
 
} // namespace pulp::midi