| // Copyright 2016 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. |
| |
| /// This file contains the definition of Link as well as the structure |
| /// of the data it holds. |
| |
| library fuchsia.modular; |
| |
| using fuchsia.mem; |
| |
| /// This interface is implemented by the story runner. The ModuleContext service |
| /// acts as a factory for it. |
| /// |
| /// An instance of Link holds one of two types of values: |
| /// |
| /// (1) A JSON string that can be modified incrementally or completely |
| /// overwritten, depending on the use of Set() and Update(). The JSON string |
| /// is set to "null" when the Link is created. |
| /// |
| /// (2) An entity reference that can be set or retrieved with SetEntity() and |
| /// GetEntity(). |
| /// |
| /// Each Module instance receives one Link instance for each parameter of its |
| /// action template in its ModuleContext. It receives its ModuleContext in |
| /// Module.Initialize() or in its service namespace. The Module can access its |
| /// Links by calling ModuleContext.GetLink() with the intent parameter name as |
| /// the link name. These instances are shared with the parent Module if there is |
| /// any, or with the StoryController client if the Module is a top level Module |
| /// of a Story. A Module can create additional Link instances by calling |
| /// ModuleContext.GetLink() with any other link name. Why would it do that? To |
| /// share the new Link instance with Modules it requests to start in turn, or to |
| /// record its own state in the story record, so that it is transferred to other |
| /// devices that run the same story, or to persist it for later resumption of the |
| /// story. |
| /// |
| /// A client may obtain another handle to the same Link instance by calling |
| /// GetLink() with the same name again. |
| /// |
| /// A client of Link can set the JSON string stored in the instance and register |
| /// a handler (an implementation of the LinkWatcher interface) to be notified of |
| /// changes to the JSON string in the Link. A client may or may not be notified |
| /// of changes it itself makes to the Link value, depending on whether it |
| /// registers with WatchAll() or Watch(), respectively. If the client registers |
| /// with Watch(), then it will not be notified of changes made through the same |
| /// Link connection. |
| /// |
| /// No service name: returned from ModuleContext.GetLink(). |
| protocol Link { |
| /// Gets the value at the given `path`, which is represented using the JSON |
| /// Pointer specification (https://tools.ietf.org/html/rfc6901). |
| /// |
| /// `json_data` is a UTF8 encoded string representing valid JSON. |
| /// |
| /// Returns null if `path` does not exist. Returns the entire JSON object |
| /// if `path` is either null or an empty array. Returns the string "null" if |
| /// the link is empty. |
| Get(vector<string>? path) -> (fuchsia.mem.Buffer? json_data); |
| |
| /// Set() overwrites the value/object/array at the given `path`. Set also |
| /// overwrites any values or arrays as necessary to ensure that `path` exists. |
| /// The `json_data` parameter must be a UTF8 encoded JSON string. |
| /// Either pass "null" to set the value to null, or use Erase to |
| /// completely remove a member of an object. To replace the root, pass null for |
| /// `path`. |
| /// |
| /// This call notifies Watchers, although this may be skipped if nothing |
| /// changed. |
| Set(vector<string>? path, fuchsia.mem.Buffer json_data); |
| |
| /// Erases the object member at the given `path`. If the path is not found or |
| /// does not match the current structure of the JSON, the path will not be |
| /// created and the call is ignored. The `path` parameter cannot be null or |
| /// zero length because the root is a value, not a key. This call notifies |
| /// Watchers, although this may be skipped if nothing changed. |
| Erase(vector<string> path); |
| |
| /// Returns the entity reference in this link. If no entity reference is |
| /// present, returns a null fidl string. |
| GetEntity() -> (string? entity_reference); |
| |
| /// Sets this to be an Entity Link with the given `entity_reference`. The |
| /// existing value of the link is overwritten. If `entity_reference` is null, |
| /// then any existing value in the link is overwritten with the JSON string |
| /// "null". |
| SetEntity(string? entity_reference); |
| |
| /// Registers a watcher, which is notified whenever the document changes. This |
| /// watcher will not be invoked for changes caused by calls made on this |
| /// handle. The Notify() callback method will be immediately invoked with the |
| /// value in the Link, even if it's empty. |
| /// |
| /// The LinkWatcher connection will be closed if the owning Link handle closed. |
| |
| /// All connections to a Link and LinkWatcher are closed once the story the |
| /// link belongs to is stopped. |
| Watch(LinkWatcher watcher); |
| |
| /// Like Watch(), but the watcher is notified also of changes made through the |
| /// same handle as the watcher is registered on. |
| WatchAll(LinkWatcher watcher); |
| |
| /// Waits for the completion of methods previously invoked on the same |
| /// connection. Allows to create sequentiality across service instances without |
| /// giving every method an empty return value. Nb. this makes no guarantees |
| /// about sequentiality with methods invoked on different connections, even to |
| /// the same Link instance. |
| Sync() -> (); |
| }; |
| |
| /// This interface is implemented by a client of Link. |
| /// |
| /// The Notify() method is invoked whenever the Link changes. The entire JSON |
| /// string in the Link will be sent. In other words, this isn't an incremental |
| /// notification. `json` cannot be null because an empty Link is the valid JSON |
| /// document "null". |
| /// |
| /// No service name: created by Module. |
| protocol LinkWatcher { |
| Notify(fuchsia.mem.Buffer json); |
| }; |