blob: dcc02de45f3f677ee01b5a18e484fb2f9a5ad13a [file] [log] [blame]
// Copyright 2018 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;
enum ExecuteStatus {
OK = 0;
// Encountered an invalid command.
// The `story_id` provided does not exist or is not visible
// to this client.
// A story must contain at least one mod, and the commands given
// either don't add one, or remove the last one.
// The mod name specified in AddMod, RemoveMod or SendModCommand
// was not found, or is invalid.
// Resolution of the intent provided in AddMod returned zero results.
// Some error happened while executing the command.
enum ConfigureStoryError : int32 {
/// The story cannot be (re)configured because it was already created.
struct ExecuteResult {
ExecuteStatus status;
string? story_id;
string? error_message;
// Enables control of a session. A session, conceptually, is a single
// full-screen experience of a Fuchsia device. A device can run multiple
// sessions (ie, when one device powers multiple kiosks); that said, sessions
// are siloed from each other.
// A session, concretely, is a collection of stories, their state, the modules
// within them, any agents that run to support the mods and the various UI
// shells (session and story shells).
protocol PuppetMaster {
// Requests a capability to control a story by name. The name acts as the
// story's unique ID. Calling ControlStory() for the same story name will
// control the same story.
// The story name, as well as modification to the story, are durable and
// persist across device reboots. This allows the client to assign its own
// identifiers to stories. Clients wishing to guarantee a new story is
// created should generate a UUIDv4 or similar.
// `request` is closed if control cannot be granted.
// TODO(thatguy): We want story names to be scoped to the client's namespace.
ControlStory(string story_name, request<StoryPuppetMaster> request);
// Deletes a story associated to `story_name`.
// Any active StoryPuppetMaster connections to the Story will be closed.
DeleteStory(string story_name) -> ();
// Returns a list of all the names of stories in the session.
GetStories() -> (vector<string> story_names);
protocol StoryPuppetMaster {
// Enqueues the given `commands` in the order they are given.
// Can be called as many times as necessary to specify the full
// set of changes to the story.
// To execute all enqueued commands, call Execute().
Enqueue(vector<StoryCommand> commands);
// Executes the commands enqueued so far by Enqueue() in order and as
// a batch: no other commands from other clients will be interleaved.
// If an error occurs, execution is stopped and an error code
// and message are returned in `result`.
Execute() -> (ExecuteResult result);
// Set the `StoryInfo` extra field for a story that is to be
// created. This should be called before the first call to Execute().
// Any subsequent calls (either on the same channel or on a new
// StoryPuppetMaster for an existing story) are ignored.
// See story_info.fidl for details.
// DEPRECATED. This method is a no-op and will never return an error.
[Transitional = "Deprecated, no-op"]
SetStoryInfoExtra(vector<StoryInfoExtraEntry> story_info_extra)
-> () error ConfigureStoryError;
/// Attach the `annotations` to the story. If the story does not yet exist,
/// it will be created.
/// Existing annotations with the same key will be overwritten, or
/// deleted if new value is null.
Annotate(vector<Annotation>:MAX_ANNOTATIONS_PER_UPDATE annotations)
-> () error AnnotationError;
/// Attach the `annotations` to the module with the given `id`.
/// The module can be annotated before being added to the story, but if the
/// story does not yet exist, AnnotationError.NOT_FOUND is returned.
/// Existing annotations with the same key will be overwritten.
AnnotateModule(string module_id, vector<Annotation>:MAX_ANNOTATIONS_PER_UPDATE annotations)
-> () error AnnotationError;