// 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;

/// A multi-typed data entity.
protocol Entity {
    /// Returns the types associated with this entity. Each entry in |types|
    /// references a well-known content type.
    GetTypes() -> (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()|.
    GetData(string type) -> (fuchsia.mem.Buffer? data);

    /// Sets the data for a particular type. This will precipitate an |OnUpdated|
    /// event with the associated type.
    WriteData(string type, fuchsia.mem.Buffer data)
        -> (EntityWriteStatus status);

    /// Gets the entity reference for this entity, which can be persisted and
    /// then later used to locate this entity. These references are weak
    /// references and are not sufficient to keep the entity alive.
    GetReference() -> (string entity_reference);

    /// Begins watching for data changes on a particular type. The watcher
    /// immediately fires |OnUpdated| with the current value for the requested
    /// type (or null if the type is not present). Closing the |Entity| interface
    /// does not close the watcher.
    Watch(string type, EntityWatcher watcher);
};

protocol EntityWatcher {
    /// Fires on data updates for a particular type. If the type is initially not
    /// present, a null |data| pointer is produced. The type may only transition
    /// from absent to present at most once, as there is no deletion.
    ///
    /// No deduplication is performed.
    OnUpdated(fuchsia.mem.Buffer? data);
};

enum EntityWriteStatus {
    OK = 0;
    /// Indicates a failure of the entity provider to write the update.
    ERROR = 1;
    /// Entity providers are not necessarily required to support entity mutation.
    READ_ONLY = 2;
};