blob: 286f3c9156210603a50ad0cac156062f6bcb0b94 [file] [log] [blame]
// 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;
using fuchsia.mem;
/// This interface is exposed to all Module instances in a story. It allows to
/// create Link instances and run more Module instances.
interface ModuleContext {
/// Gets a Link instance with the given name.
/// The Link instance has a name so that it can be recognized when the story
/// is resumed. The name is unique in the scope of the Module instance. If
/// the method is called again with the same argument by the same Module
/// instance, a new connection to the same Link instance is obtained. It's
/// up to the Module instance to ensure the name is unique within the scope
/// of itself.
/// TODO(thatguy): When no modules use null link names any more, make name
/// required.
1: GetLink(string? name, request<Link> link);
/// Starts a new Module instance and adds it to the story. The Module to
/// execute is identified by the contents of [intent] and the Module instance
/// is given a [name] in the scope of the starting Module instance. The view
/// for the Module is given to the story shell for display.
/// Providing a [surface_relation] advises the StoryShell how to layout
/// surfaces that the new module creates. If [surface_relation] is null then
/// a default relation is used.
/// If the method is called again with the same [name] by the same Module
/// instance, but with different arguments, the existing Module instance is
/// restarted with the changed arguments. If the other arguments don't
/// change, just an additional ModuleController connection is made.
15: AddModuleToStory(string name, Intent intent,
request<ModuleController> module_controller,
SurfaceRelation? surface_relation)
-> (StartModuleStatus status);
/// Like AddModuleToStory(), but requests a [view_owner] explicitly to embed
/// the view of the requested Module instance in the view of the requesting
/// Module instance, instead of relying on the story shell for display. If a
/// Module instance with the same [name] and [intent] is already running,
/// [view_owner] is closed.
3: EmbedModule(string name, Intent intent,
request<ModuleController> module_controller,
request<fuchsia.ui.viewsv1token.ViewOwner> view_owner)
-> (StartModuleStatus status);
/// DEPRECATED: no longer implemented.
6: StartContainerInShell(string container_name,
SurfaceRelation parent_relation,
vector<ContainerLayout> layout,
vector<ContainerRelationEntry> relationships,
vector<ContainerNode> nodes);
/// DEPRECATED: ComponentContext is now available in the
/// namespace/environment for Modules.
7: GetComponentContext(request<ComponentContext> request);
/// Gets the id for this story which may be used to create a suggestion
/// proposal to resume this story, especially by agents.
9: GetStoryId() -> (string story_id);
/// Requests that the current story and module gain focus. It's up to the story
/// shell and session shell to honor that request.
10: RequestFocus();
/// DEPRECATED in favor of using StartOngoingActivity().
11: Active();
/// When a module calls [RemoveSelfFromStory()] the framework will stop the
/// module and remove it from the story. If there are no more running modules
/// in the story the story will be deleted.
16: RemoveSelfFromStory();
/// Requests to update the visibility state of the current story within the
/// session shell. The framework will decide whether to honor this request, then
/// forward it to the session shell.
/// Modules should not have any knowledge of the story's visibility state, nor
/// should it ever operate with any assumption of the visibility state.
/// Note that the framework keeps this state only in memory, which means that
/// across reboots, the story visibility state will revert back to DEFAULT.
/// This makes it unsafe for any component outside the framework to make
/// assumptions about the story visibility state. Also, this differs from other
/// UI states such as focus state, which is persisted across reboots.
13: RequestStoryVisibilityState(StoryVisibilityState visibility_state);
/// Declares that activity of the given [type] is ongoing in this module.
/// This information is forwarded to the session shell
/// (cf. StoryProvider.WatchActivity() and StoryActivityWatcher).
/// Modules should close [request] when the ongoing activity has stopped, and
/// this will also signal to the session shell that the ongoing activity has
/// stopped. For now, pausing media should count as a stopped ongoing activity,
/// and when it is resumed it should be started as a new ongoing activity.
/// Conversely, media playing in a continuous playlist (i.e playing the next
/// video or song) should be treated as the same ongoing activity.
/// Modules must request a connection per ongoing activity; a single connection
/// may not be re-used for multiple ongoing activities.
14: StartOngoingActivity(OngoingActivityType type,
request<OngoingActivity> request);
/// Creates a [fuchsia.modular.Entity] with the given [type] and [data]. The
/// lifetime of the created entity is tied to the lifetime of the current story,
/// but can be dereferenced by modules and agents outside the scope of the story.
/// [entity_request] will be connected to the created entity, or closed if the
/// creation fails.
/// The returned [reference] is the entity reference for the created entity, or
/// null if the entity creation failed.
17: CreateEntity(string type, fuchsia.mem.Buffer data, request<Entity> entity_request)
-> (string? entity_reference);
/// Communicates the status of an Intent to a Module.
enum StartModuleStatus {
/// This interface defines the protocol over which a Module can communicate about
/// an ongoing activity to the framework. It is provided to Modules via
/// ModuleContext.StartOngoingActivity().
interface OngoingActivity {
enum OngoingActivityType {
VIDEO = 1;
AUDIO = 2;