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