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