blob: 81d40f8b4f9c4ac323dedf4269ecae22f9af2ab1 [file] [log] [blame]
// 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.
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);