// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.modular;

using fuchsia.mem;

/// EntityProviders (agents) must implement and provide the |EntityProvider|
/// service if they create entity references (using |EntityReferenceFactory|).
/// This service is used by the framework to provide data for an |Entity|
/// interface for an entity. This interface is requested by the framework in
/// the agent's *application* outgoing services, and is closed by the framework
/// when there are no more |Entity|s that need to be provided.
///
/// In the below methods, |cookie| will have been previously passed to
/// |EntityReferenceFactory.CreateReference()|, though this may have been in an
/// earlier or remote app instance. Entity providers should attempt to resolve
/// unfamiliar cookies or else treat the entities as empty and read-only.
[Discoverable]
protocol EntityProvider {
    /// Returns the types associated with the requested entity. Each entry in
    /// |type| references a well-known content type.
    ///
    /// If the cookie cannot be resolved, the provider should produce an empty
    /// vector.
    GetTypes(string cookie) -> (vector<string> types);

    /// Given one of the types returned from |GetTypes()| above, returns
    /// associated short-form data, or null if the type is absent from
    /// |GetTypes()|.
    ///
    /// If the cookie cannot be resolved, the provider should return null.
    GetData(string cookie, string type) -> (fuchsia.mem.Buffer? data);

    /// Sets the data for a particular type. This must precipitate an |OnUpdate|
    /// event with the associated type.
    ///
    /// If the cookie cannot be resolved, the provider should no-op with
    /// |EntityWriteStatus::READ_ONLY|.
    WriteData(string cookie, string type, fuchsia.mem.Buffer data)
        -> (EntityWriteStatus status);

    /// Begins watching for data changes on a particular type. The watcher must
    /// immediately fire |OnUpdated| with the current value for the requested
    /// type (or null if the type is not present).
    ///
    /// No deduplication of events should be performed.
    ///
    /// At most one update may be in-flight at a time on a particular watcher;
    /// once a client is ready for another update, it will call the callback. At
    /// most one update should be queued for dispatch for a particular watcher;
    /// older updates should be dropped.
    ///
    /// If the cookie cannot be resolved, the provider should emit a single event
    /// with null data.
    Watch(string cookie, string type, EntityWatcher watcher);
};