// 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.policy;
using fuchsia.ui.views;

/// This interface is implemented by a session shell and is used by the
/// sessionmgr to hand to the session shell views of stories, or to notify that
/// the view of a story is about to be closed.
@discoverable
protocol SessionShell {
    /// Displays the given story view. The story this view belongs to is
    /// identified by `view_id.story_id`.
    /// DEPRECATED.  For transitional purposes only.
    @transitional
    AttachView(resource struct {
        view_id ViewIdentifier;
        view_holder_token fuchsia.ui.views.ViewHolderToken;
    });
    @transitional
    AttachView2(resource struct {
        view_id ViewIdentifier;
        view_holder_token fuchsia.ui.views.ViewHolderToken;
    });

    /// Instructs the session shell to detach the view identified by `view_id`
    /// that was previously provided by AttachView() from the UI of the session
    /// shell. The view will be closed soon after DetachView() returns, or when a
    /// timeout is reached.
    ///
    /// It is customary for the session shell to display a placeholder before a
    /// view is attached for a given view identifier, or after it was detached.
    ///
    /// If the story identified by `view_id.story_id` is about to be deleted, the
    /// Shell will observe a call to StoryProviderWatcher.OnDelete() sometime
    /// after DetachView() returns.
    ///
    /// If the session for which this session shell is responsible for is being
    /// terminated, or the session shell is stopped because it's replaced by
    /// another session shell, DetachView() will *not* be called at all, and the
    /// shell will rather observe a call to Lifecycle.Terminate().
    DetachView(struct {
        view_id ViewIdentifier;
    }) -> ();
};

/// Identifies a view provided to a session shell. The values of the `story_id`
/// field match those used in the `StoryProvider` interface, allowing
/// identification of the same story across interfaces.
///
/// This is a struct rather than a naked string:MAX to allow for future evolution of
/// the identifier without changing the `SessionShell` API itself.
type ViewIdentifier = struct {
    story_id string:MAX;
};

/// This interface allows a `SessionShell` to request capabilities from its
/// creator in a way that is more explicit about the services that are
/// offered than a generic `ServiceProvider`.
@discoverable
protocol SessionShellContext {
    GetComponentContext(resource struct {
        request server_end:ComponentContext;
    });
    GetPresentation(resource struct {
        request server_end:fuchsia.ui.policy.Presentation;
    });
    GetStoryProvider(resource struct {
        request server_end:StoryProvider;
    });

    /// Restarts the session.
    Restart();

    /// Deprecated: Equivalent to Restart().
    @transitional
    Logout();
};