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

    /// Requests detailed information about the given story. If the story doesn't
    /// exist, returns null.
    [Transitional = "Use GetStoryInfo2 instead"]
    GetStoryInfo(string story_id) -> (StoryInfo? story_info);
    /// For transition purposes only.
    [Transitional = "Use only while GetStoryInfo is transitional"]
    GetStoryInfo2(string 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 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
    ///    kept on the current device, including a new story created on another
    ///    device becoming known on this device for the first time.
    ///
    ///  * Every time the StoryState of the story changes on this device. The
    ///    StoryState on another device of a story known on this device is not made
    ///    known on this device.
    ///
    ///  * Every time the StoryVisibilityState of the story changes on this device.
    ///    The StoryVisibilityState on another device of a story known on this
    ///    device is not made known on this device.
    ///
    ///    I.e. if the story is started or stopped on *another* device, it does
    ///    *not* cause an OnChange() call on *this* device. Cf. OnDelete() below.
    ///
    /// 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 DEFAULT until a mod on the current device
    /// requests for the visibility state to be changed.
    [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 story_id);
};