// Copyright 2021 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.sys2;

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

/// Describes the result of the Start command.
type StartResult = strict enum {
    /// The component start succeeded.
    STARTED = 0;

    /// The component was already running.
    ALREADY_STARTED = 1;
};

/// A protocol exposed in a component's hub to allow component tools
/// to resolve, bind, stop component manifests.
@discoverable
protocol LifecycleController {
    /// Resolves the component designated by the provided relative moniker
    /// relative to the component to which the protocol is scoped.
    ///
    /// The function returns once the component successfully resolves, or the
    /// operation fails.
    Resolve(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Creates a child component instance dynamically. This method is equivalent to
    /// fuchsia.component/Realm.CreateChild. See its documentation for more details.
    ///
    /// `parent_moniker` is the moniker of the component that owns the collection
    /// in which the child will be created, relative to the component to which
    /// the protocol is scoped.
    CreateChild(resource struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        collection fuchsia.component.decl.CollectionRef;
        decl fuchsia.component.decl.Child;
        args fuchsia.component.CreateChildArgs;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Destroys a dynamically-created component instance. This method is equivalent to
    /// fuchsia.component/Realm.DestroyChild. See its documentation for more details.
    ///
    /// `parent_moniker` is the moniker of the component that owns the collection
    /// in which the child will be destroyed, relative to the component to which
    /// the protocol is scoped.
    DestroyChild(struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        child fuchsia.component.decl.ChildRef;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Starts the component designated by the provided relative moniker
    /// relative to the component to which the protocol is scoped.
    ///
    /// The function returns once the component has started, or the operation
    /// fails. It returns a StartResult enum to indicate success (Started or
    /// AlreadyStarted).
    Start(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {
        result StartResult;
    }) error fuchsia.component.Error;

    /// Stops the component designated by the provided relative moniker
    /// relative to the component to which the protocol is scoped.
    ///
    /// The function returns once the component successfully stops, or the
    /// operation fails.
    Stop(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        is_recursive bool;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Retrieves the storage admin using the parent moniker and the capability
    /// name
    ///
    /// The function returns once the storage admin has been served, or the
    /// operation fails.
    /// TODO(http://fxbug.dev/97774): Move `GetStorageAdmin` out of `lifecycle_controller`
    GetStorageAdmin(resource struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        capability string:MAX_CAPABILITY_ID_LENGTH;
        admin_server server_end:StorageAdmin;
    }) -> (struct {}) error fuchsia.component.Error;
};