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

/// 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.sys2/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 CollectionRef;
        decl ChildDecl;
        args fuchsia.component.CreateChildArgs;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Destroys a dynamically-created component instance. This method is equivalent to
    /// fuchsia.sys2/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 ChildRef;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Binds to the component designated by the provided relative moniker
    /// relative to the component to which the protocol is scoped.
    ///
    /// The function returns once the component is successfully bound, or the
    /// operation fails.
    Bind(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {}) 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;
};