// 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 (UserShell) 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);

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

  // Stops this story if it is running, else does nothing. Returns when the
  // story is stopped.
  4: Stop() -> ();

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

  // Adds a module matching the provided Intent to the story.
  //
  // A module is selected via Module Resolution (docs/module_resolution.md).
  // The started module will see one Link per |intent.parameters| entry available
  // with the same name as the noun. For example, if intent.parameters[0].name ==
  // 'foo', the started module can call ModuleContext.GetLink('foo', ...) in
  // order to access the Link.
  //
  // |parent_module_path| is the path to the module that is adding the Intent.
  // |module_name| is the name of the started module as exposed to the parent
  //               module.
  // |intent| is the intent that will be used for module resolution.
  // |surface_relation| is used to determine how the started module will be
  //                    presented.
  12: AddModule(vector<string>? parent_module_path, string module_name,
                Intent intent, SurfaceRelation? surface_relation);

  // 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.
  7: GetActiveModules(StoryModulesWatcher? watcher) -> (vector<ModuleData> module_data);

  // Lists all known modules in the story, as recorded in the ledger.
  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.
  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.
  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.
  2: OnModuleAdded(ModuleData module_data);
};

// Implemented by the client calling StoryController.GetActiveModules().
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().
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);
};