// 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.sys;

type TerminationReason = strict enum {
    /// The channel closed without giving a termination reason.
    UNKNOWN = 0;
    /// Component ran and exited with a given return_code.
    EXITED = 1;
    /// The given URL given to launch was invalid.
    URL_INVALID = 2;
    /// The requested package could not be found.
    PACKAGE_NOT_FOUND = 3;
    /// An internal error happened during the launch process.
    INTERNAL_ERROR = 4;
    /// Process creation failed.
    PROCESS_CREATION_ERROR = 5;
    /// A Runner failed to start.
    RUNNER_FAILED = 6;
    /// A Runner terminated while attempting to run a component.
    RUNNER_TERMINATED = 7;
    /// Attempted to use an unsupported feature.
    UNSUPPORTED = 8;
    /// Attempted to create a component in a realm which is shutting down.
    REALM_SHUTTING_DOWN = 9;
    /// Insufficient privilege to start the component.
    ACCESS_DENIED = 10;
};

/// An interface for controlling components.
///
/// Closing this interface implicitly kills the controlled component unless
/// the `Detach` method has been called.
///
/// If the component exits, this interface will be closed.
///
/// Typically obtained via `Launcher.CreateComponent`.
closed protocol ComponentController {
    /// Terminates the component.
    ///
    /// This ComponentController connection is closed when the component has
    /// terminated.
    strict Kill();

    /// Decouples the lifetime of the component from this controller.
    ///
    /// After calling `Detach`, the component will not be implicitly killed when
    /// this interface is closed.
    strict Detach();

    // DEPRECATED: Use OnTerminated instead of Wait().
    // 3: Wait()

    /// Event that is triggered when the component is terminated.
    ///
    /// This event provides the return code of the process and reason for
    /// its termination. The return_code is only valid if the termination
    /// reason is EXITED. If the termination reason is not EXITED, the
    /// return code is guaranteed not to be 0.
    strict -> OnTerminated(struct {
        return_code int64;
        termination_reason TerminationReason;
    });

    /// Event that is triggered when the component's output directory is mounted.
    ///
    /// This event will not be triggered for every component, only those that
    /// serve a directory over their `PA_DIRECTORY_REQUEST` handle.
    strict -> OnDirectoryReady();
};