// 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(StoryProviderWatcher? watcher) -> (vector<StoryInfo>:MAX story_infos);
    /// For transition purposes only.
    [Transitional = "Only use while GetStories is transitional"]
    GetStories2(StoryProviderWatcher? watcher) -> (vector<StoryInfo2>:MAX story_infos);

    /// Requests detailed information about the given story. If the story doesn't
    /// exist, returns null.
    [Transitional = "Use GetStoryInfo2 instead"]
    GetStoryInfo(string:MAX story_id) -> (StoryInfo? story_info);
    /// For transition purposes only.
    [Transitional = "Use only while GetStoryInfo is transitional"]
    GetStoryInfo2(string:MAX story_id) -> (StoryInfo2 story_info);

    /// 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(string:MAX story_id, request<StoryController> request);

    /// Registers a watcher for changes in the story collection.
    /// DEPRECATED: In favor of GetStories().
    Watch(StoryProviderWatcher watcher);
};

/// 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(StoryInfo story_info, StoryState story_state,
             StoryVisibilityState story_visibility_state);
    /// For transition purposes only.
    [Transitional = "Implement only while OnChange is transitional"]
    OnChange2(StoryInfo2 story_info, StoryState story_state,
              StoryVisibilityState story_visibility_state);

    /// 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(string:MAX story_id);
};

// Deprecated.
enum StoryVisibilityState {
    DEFAULT = 1;
    IMMERSIVE = 2;
};