ump_session.hpp

Go to the documentation of this file.

#pragma once
 
// UmpSession — Pulp's MIDI 2.0 UMP session handle.
//
// One `UmpSession` per app or plugin instance. On macOS it owns the
// underlying `MIDIClientRef` (CoreMIDI 2.0). On platforms that don't yet
// have a UMP backend the session degrades to virtual-endpoints-only, which
// is enough for unit tests and for in-process loopback.
//
// Design notes:
//   - The session is the only entity that knows how to talk to the
//     OS MIDI subsystem; everything else hangs off it.
//   - Endpoint lifetime is tied to the session: dropping the session
//     drops every endpoint it minted.
//   - Discovery returns a snapshot. We deliberately don't expose a
//     push-style "endpoint added" stream from this surface — the
//     existing `MidiSystem::set_port_change_callback()` already
//     handles hotplug for the legacy MIDI 1.0 stream, and re-running
//     `enumerate()` is cheap.
//   - Virtual endpoints are returned as `std::shared_ptr` so a test can keep
//     a direct handle. The session holds its own `shared_ptr`s and closes /
//     drops them during teardown; a caller-retained handle keeps the endpoint
//     object alive after that.
 
#include <pulp/midi/ump_endpoint.hpp>
#include <pulp/midi/ump_virtual_endpoint.hpp>
 
#include <memory>
#include <string>
#include <vector>
 
namespace pulp::midi {

struct UmpSessionConfig {
    std::string name = "Pulp UMP Session";
    bool enable_os_backend = true;
};

enum class UmpOpenStatus {
    Ok,
    NotFound,
    OsBackendUnavailable,
    OsError,
};
 
class UmpSession {
public:
    UmpSession();
    explicit UmpSession(UmpSessionConfig cfg);
    ~UmpSession();
 
    UmpSession(const UmpSession&) = delete;
    UmpSession& operator=(const UmpSession&) = delete;

    bool os_backend_active() const noexcept;

    std::vector<UmpEndpointInfo> enumerate_endpoints() const;

    UmpEndpoint* open_endpoint(const std::string& id,
                               UmpOpenStatus* status = nullptr);

    std::shared_ptr<VirtualUmpEndpoint> register_virtual_endpoint(
        VirtualUmpEndpointConfig cfg);

    bool unregister_virtual_endpoint(const std::string& id);

    std::size_t virtual_endpoint_count() const;

    bool wire_virtual_loopback(const std::string& from_id,
                               const std::string& to_id);
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
} // namespace pulp::midi