DARTWICShareProtocol

API

Transport-agnostic developer facade for the DARTWIC Share protocol. The caller supplies a ShareTransport. This class owns protocol semantics, handshake/readiness, typed channel and ARGUS operations, handler dispatch, and callback isolation. It never creates sockets or chooses a wire transport.

Namespace: DARTWIC::Share.

#include <dartwic/share/DARTWICShareProtocol.h>

Declaration

class DARTWICShareProtocol {
public:
    class Channels {
    public:
        // Send a field write and wait for acknowledgement; requires protocol readiness.
        void upsert(ChannelUpsert request) const;
        // Send a channel deletion and wait for acknowledgement.
        void remove(ChannelRemove request) const;
        // Send a nonempty batch of samples and wait for acknowledgement.
        void upsertBulk(ChannelBulkUpsert request) const;
        // Wait for channel snapshots from the peer.
        ChannelQueryResult query(ChannelQuery request) const;
        // Publish without acknowledgement. Missing owner/session/revision lineage is assigned locally; disconnected telemetry is dropped.
        void publishTelemetry(ChannelTelemetry telemetry) const;
        // Publish a generation of writes without acknowledgement.
        void publishTelemetry(FixedGenerationTelemetry telemetry) const;
        // Set incoming handlers before start to advertise their capabilities in Hello.
        void setHandlers(ChannelHandlers handlers) const;
    };
    class Argus {
    public:
        // Publish a message event without acknowledgement; assign a missing event ID and owner.
        void message(ArgusEvent event) const;
        // Publish a warning event without acknowledgement.
        void warning(ArgusEvent event) const;
        // Publish an error event without acknowledgement.
        void error(ArgusEvent event) const;
        // Publish an abort event without acknowledgement; return does not confirm remote execution.
        void abort(ArgusEvent event) const;
        // Publish a hold event without acknowledgement.
        void hold(ArgusEvent event) const;
        // Publish a prompt and return its event ID immediately; an optional callback receives a later response action.
        std::string prompt(ArgusEvent event,
                    std::function<void(const ArgusAction&)> response = {}) const;
        // Send a prompt response and wait for acknowledgement.
        void respond(std::string event_id, Value::Object payload) const;
        // Change an event status and wait for acknowledgement.
        void updateStatus(std::string event_id, std::string status) const;
        // Release a hold and wait for acknowledgement.
        void releaseHold(std::string event_id, Value::Object payload = {}) const;
        // Delete an event and wait for acknowledgement.
        void remove(std::string event_id) const;
        // Wait for matching events from the peer.
        ArgusQueryResult query(ArgusQuery request) const;
        // Publish event state without acknowledgement; disconnected telemetry is dropped.
        void publishTelemetry(ArgusEventTelemetry telemetry) const;
        // Set incoming handlers before start to advertise their capabilities in Hello.
        void setHandlers(ArgusHandlers handlers) const;
    };
    DARTWICShareProtocol(ShareProtocolConfig config, ShareTransportPtr transport);
    virtual ~DARTWICShareProtocol();
    DARTWICShareProtocol(const DARTWICShareProtocol&) = delete;
    DARTWICShareProtocol& operator=(const DARTWICShareProtocol&) = delete;
    // Start the transport and asynchronous Hello handshake.
    void start();
    // Stop the transport. When called outside the callback thread, drain already-dispatched user callbacks.
    void stop();
    // Equivalent to protocolReady().
    bool connected() const noexcept;
    // Test physical transport connectivity, independently of the Hello handshake.
    bool transportConnected() const noexcept;
    // Test whether a connected transport has completed a valid Share Hello.
    bool protocolReady() const noexcept;
    // Block until ready; throw RequestTimeoutError on timeout or DisconnectedError on disconnect/stop.
    void waitUntilReady(
            std::chrono::milliseconds timeout = std::chrono::milliseconds{5000}) const;
    TransportState state() const noexcept;
    std::string sessionId() const;
    std::string remoteNode() const;
    Capabilities remoteCapabilities() const;
    // Install a state callback. State and telemetry callbacks run serially on a protocol-owned thread and may issue synchronous requests.
    void onStateChanged(std::function<void(TransportState, std::string)> handler);
    Channels& channels() noexcept;
    const Channels& channels() const noexcept;
    Argus& argus() noexcept;
    const Argus& argus() const noexcept;
};