public/fidl/fuchsia.modular/story/story_controller.fidl

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

library fuchsia.modular;

using fuchsia.ui.viewsv1token;

// Used by the clients of StoryProvider (SessionShell) to interact with a single
// story. Created by StoryProvider.
//
// If |StoryController| is closed, the |StoryState| associated with this story
// does not change.
interface StoryController {
    // Gets information associated with the story.
    1: GetInfo() -> (StoryInfo info, StoryState state);

    // DEPRECATED in favor of RequestStart().
    //
    // Runs the story controlled by this |StoryController| instance if not yet
    // running or requested to start, else does nothing. |view_owner| is an
    // interface request for the view of the story shell of this story. If the
    // story is already running, the view owner request is dropped. If Stop()
    // requests are pending when this request is issued, the request is queued
    // until the Stop() requests complete.
    3: Start(request<fuchsia.ui.viewsv1token.ViewOwner> view_owner);

    // Requests to runsthe story controlled by this |StoryController| instance.
    // When the story starts, if not yet running, the view of the newly started
    // story shell will be passed in a call to SessionShell.AttachView().
    14: RequestStart();

    // Requests to stop the story controlled by this |StoryController|. If Start()
    // requests are pending when this request is issued, the request is queued
    // until the Start() requests complete. Before stopping the story, a snapshot
    // of the story will be taken and saved. Returns when the story is stopped.
    4: Stop() -> ();

    // Creates a new view with the given |view_owner| request to display
    // snapshots. Takes a snapshot for the story controlled by this
    // |StoryController| and then loads the snapshot to the created view such that
    // it is rendered. The callback will be invoked once the view has been created
    // and the snapshot has been loaded.
    13: TakeAndLoadSnapshot(request<fuchsia.ui.viewsv1token.ViewOwner> view_owner) -> ();

    // Registers a watcher for changes of the story state.
    //
    // Note that stories can stop themselves at any time and it is advisable
    // for the holder of a StoryController to provide a watcher.
    5: Watch(StoryWatcher watcher);

    // Lists the active modules in the story. Active modules are those with a
    // controller.
    //
    // Notifications for state changes on the module can be obtained through
    // the ModuleController's OnStateChanged() event.
    //
    // Notifications for changes to this list are provided through
    // StoryModulesWatcher.OnNewModule(), if a watcher is supplied in the call.
    //
    // DEPRECATED: StoryController is only to be used for Story concepts
    // (metadata about, and requesting changes to runtime state).
    7: GetActiveModules(StoryModulesWatcher? watcher) -> (vector<ModuleData> module_data);

    // Lists all known modules in the story, as recorded in the ledger.
    //
    // DEPRECATED: StoryController is only to be used for Story concepts
    // (metadata about, and requesting changes to runtime state).
    8: GetModules() -> (vector<ModuleData> module_data);

    // Obtains a ModuleController for the module at the given path. If no module
    // exists at that path, the request is dropped. This is mostly to receive
    // state update events.
    //
    // TODO(mesch): This is EXPERIMENTAL. We want something like this for story
    // crafting, but giving the same module controller to the story crafting
    // client as to the parent module or story runner might not be right yet.
    //
    // DEPRECATED: StoryController is only to be used for Story concepts
    // (metadata about, and requesting changes to runtime state).
    9: GetModuleController(vector<string> module_path, request<ModuleController> request);

    // DEPRECATED: MI4-1084
    10: GetActiveLinks(StoryLinksWatcher? watcher) -> (vector<LinkPath> link_data);

    // Gets a connection to a link in the story with the specified |link_path|. If
    // link does not exist yet, it is implicitly created when it is first
    // accessed.
    //
    // DEPRECATED: StoryController is only to be used for Story concepts
    // (metadata about, and requesting changes to runtime state).
    11: GetLink(LinkPath link_path, request<Link> link);
};

// Implemented by the client calling StoryController.Watch().
interface StoryWatcher {
    // Called with the current state right after registration, and subsequently
    // when the state changes.
    1: OnStateChange(StoryState new_state);

    // Called when a module is added to a story.
    //
    // TODO(mesch): Remove, use StoryModulesWatcher instead.
    //
    // DEPRECATED: StoryController is only to be used for Story concepts
    // (metadata about, and requesting changes to runtime state).
    2: OnModuleAdded(ModuleData module_data);

    // Called when a module is focused in the story.
    // EXPERIMENTAL
    //
    // DEPRECATED: StoryController is only to be used for Story concepts
    // (metadata about, and requesting changes to runtime state).
    3: OnModuleFocused(vector<string> module_path);
};

// Implemented by the client calling StoryController.GetActiveModules().
//
// DEPRECATED: StoryController is only to be used for Story concepts
// (metadata about, and requesting changes to runtime state).
interface StoryModulesWatcher {
    // Called when a module becomes active in the story, i.e. when a module
    // controller for it is created. After this notification, the ModuleController
    // can be obtained with GetModuleController() and further notifications can be
    // obtained from watchers and connection error handlers on the controller.
    //
    // This is EXPERIMENTAL. We certainly can make this simpler once we know it is
    // what we need.
    1: OnNewModule(ModuleData module_data);

    // Called when a module becomes inactive in the story, i.e. when the module
    // controller is destroyed because its parent or the story runner called
    // Stop() for it. This is not called when modules are torn down because the
    // story as a whole is stopped.
    2: OnStopModule(ModuleData module_data);
};

// Implemented by the client calling StoryController.GetActiveLinks().
//
// DEPRECATED: StoryController is only to be used for Story concepts
// (metadata about, and requesting changes to runtime state).
interface StoryLinksWatcher {
    // Called when a link becomes active in the story, i.e. when it is loaded into
    // memory and connected with modules and watchers. After this notification,
    // the Link can be obtained with GetLink() and further notifications can be
    // obtained from watchers on the Link and connection error handlers on the
    // LinkWatcher.
    //
    // Note that the Link remains active until there are no connections to it
    // left. Hence in order to obtain a notification when the Link becomes
    // inactive, a client must give up the Link connection after registering a
    // LinkWatcher, and listen for the LinkWatcher connection to go down.
    //
    // This is EXPERIMENTAL. We certainly can make this simpler once we know it is
    // what we need.
    1: OnNewLink(LinkPath link_path);
};