@0xc0787ef6e3cb87e1;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

using import "resource.capnp".Resource;
using import "utils.capnp".OID;
using import "utils.capnp".Map;
using import "state.capnp".Update;
using import "measure.capnp".Measurement;

interface Notifiable {
    state @0 () -> Map(OID, AnyPointer);
    # Returns the current state of a resource.

    getStateOid @4 ( oid :OID ) -> ( state :AnyPointer );
    # Return only the state of the trait with the given OID

    subscribe @1 ( subscriber :Subscriber(Update) ) -> ( subscription :Subscription );
    # Subscribe to state updates. The passed in `subscriber` is an interface implemented on the
    # client side that a server calls to send update notifications.

    measurements @2 () -> Map(OID, AnyPointer);

    subscribeMeasurements @3 ( subscriber :Subscriber(Measurement) ) -> ( subscription: Subscription );
}

interface Subscriber(Update) {
    update @0 ( update :Update ) -> UpdateResult;
    # Called by a server when a new state was produced for this resource.  This method MAY not be
    # called when a resource was updated but did not change its state.  A server will only ever have
    # one running update call per client session, so a client can limit the rate of updates by not
    # resolving this call immediately.  A server will coalesce multiple updates into a single update
    # notification, meaning a client is not guaranteed to receive every intermediary state for a
    # resource.
}



struct UpdateResult { } # Empty struct to make `update` apply backpressure.

interface Subscription { 
    cancel @0 (); # Cancel this subscription, making the server not send anymore updates.
}