sdk/fidl/fuchsia.session/launcher.fidl

// Copyright 2019 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.session;

using fuchsia.url;
using fuchsia.component.decl;

/// A protocol used to launch sessions.
@discoverable
closed protocol Launcher {
    /// Launches the session detailed in `configuration`.
    ///
    /// If a session is currently running, the component associated with the running
    /// session will be destroyed.
    ///
    /// + `configuration` describes the session to launch.
    /// * error `LaunchError.INVALID_ARGS` if `configuration.session_url` is not set.
    /// * error `LaunchError.NOT_FOUND` if `configuration.session_url`
    ///   could not be resolved.
    /// * error `LaunchError.DESTROY_COMPONENT_FAILED` if an existing session component
    ///   could not be destroyed. The existing session remains running at this point.
    /// * error `LaunchError.CREATE_COMPONENT_FAILED` if the session component
    ///   could not be started. No session will be running at this point.
    strict Launch(struct {
        configuration LaunchConfiguration;
    }) -> () error LaunchError;
};

/// An error that occurs when launching a session.
type LaunchError = flexible enum {
    /// The session's `LaunchConfiguration` is malformed.
    INVALID_ARGS = 1;

    /// There was an error resolving the session's component URL.
    NOT_FOUND = 2;

    /// The session component could not be destroyed.
    DESTROY_COMPONENT_FAILED = 3;

    /// The session component could not be created.
    CREATE_COMPONENT_FAILED = 4;
};

/// Describes a session to launch.
type LaunchConfiguration = table {
    /// The component URL of the session.
    1: session_url string:fuchsia.url.MAX_URL_LENGTH;

    /// Configuration capabilities that will be offered to the session.
    ///
    /// In the intended use case, the session component would use a particular
    /// configuration capability with `transitional` availability. When such a
    /// transitional capability is not offered to the session, the config value
    /// from the package will be used. When it is offered using
    /// `config_capabilities`, then the config value specified here will be
    /// used. As such, one may override config values of the session component
    /// that are set up following this pattern.
    @available(added=HEAD)
    2: config_capabilities vector<fuchsia.component.decl.Configuration>:MAX;
};