blob: eafde22b31559c0bf0381afb8cbdef028873faeb [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;
/// Sessionmgr passes a connection to this service to the SessionShell so it can
/// operate on stories for the user.
///
/// Closing a `StoryProvider` connection has no effect on the state of the
/// framework.
@discoverable
protocol StoryProvider {
/// Returns a list of existing stories. If `watcher` is provided, the client will
/// be notified of story changes (new stories, deleted stories, runtime
/// state changes).
@transitional("Use GetStories2 instead")
GetStories(resource struct {
watcher client_end:<StoryProviderWatcher, optional>;
}) -> (struct {
story_infos vector<StoryInfo>:MAX;
});
/// For transition purposes only.
@transitional("Only use while GetStories is transitional")
GetStories2(resource struct {
watcher client_end:<StoryProviderWatcher, optional>;
}) -> (resource struct {
story_infos vector<StoryInfo2>:MAX;
});
/// Requests detailed information about the given story. If the story doesn't
/// exist, returns null.
@transitional("Use GetStoryInfo2 instead")
GetStoryInfo(struct {
story_id string:MAX;
}) -> (struct {
story_info box<StoryInfo>;
});
/// For transition purposes only.
@transitional("Use only while GetStoryInfo is transitional")
GetStoryInfo2(struct {
story_id string:MAX;
}) -> (resource struct {
story_info StoryInfo2;
});
/// Obtains a controller for a previously created story identified by its story
/// ID. Obtaining the controller doesn't run it yet. If the story doesn't
/// exist, the interface request is closed.
GetController(resource struct {
story_id string:MAX;
request server_end:StoryController;
});
/// Registers a watcher for changes in the story collection.
/// DEPRECATED: In favor of GetStories().
Watch(resource struct {
watcher client_end:StoryProviderWatcher;
});
};
/// Implemented by clients of StoryProvider.
protocol StoryProviderWatcher {
/// Called in three different situations:
///
/// * Immediately when a new watcher is registered with one OnChange()
/// invocation with the current infor and state of each story known on the
/// current device.
///
/// * Every time a change to StoryInfo is applied to the record of the story.
///
/// * Every time the StoryState of the story changes.
///
/// The ID of the story the notifications are about are part of StoryInfo.
///
/// `story_state` is STOPPED if the story was just created or just became known
/// on this device and was not yet started on the current device. It's RUNNING
/// when the story is started on the current device.
///
/// `story_visibility_state` is deprecated and will always have a value of DEFAULT.
@transitional("Implement OnChange2 instead")
OnChange(struct {
story_info StoryInfo;
story_state StoryState;
story_visibility_state StoryVisibilityState;
});
/// For transition purposes only.
@transitional("Implement only while OnChange is transitional")
OnChange2(resource struct {
story_info StoryInfo2;
story_state StoryState;
story_visibility_state StoryVisibilityState;
});
/// Called when a story record is permanently deleted. The deletion could
/// have originated on this or on another device.
///
/// If the story is running on this device at the time it is deleted,
/// OnChange() will not be called first.
OnDelete(struct {
story_id string:MAX;
});
};
// Deprecated.
type StoryVisibilityState = strict enum {
DEFAULT = 1;
IMMERSIVE = 2;
};