sdk/fidl/fuchsia.sys2/lifecycle_controller.fidl

// 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 instance was started.
    STARTED = 0;

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

/// Mutates the component instance state in a realm.
@discoverable
protocol LifecycleController {
    /// Starts the instance identified by the given moniker.
    ///
    /// The function returns once the instance has been started.
    Start(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {
        result StartResult;
    }) error fuchsia.component.Error;

    /// Stops the instance identified by the given moniker.
    ///
    /// The function returns once the instance has been stopped.
    Stop(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        is_recursive bool;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Resolves the instance identified by the given moniker.
    ///
    /// The function returns once the instance has been resolved
    Resolve(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Unresolves 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 unresolves, or the
    /// operation fails.
    Unresolve(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Creates a new child instance under a collection. This method is similar to
    /// [`fuchsia.component/Realm.CreateChild`].
    ///
    /// `parent_moniker` is the moniker of the instance that owns the collection.
    ///
    /// The function returns once the child instance has been added to the topology.
    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 child instance under a collection. This method is similar to
    /// [`fuchsia.component/Realm.DestroyChild`].
    ///
    /// `parent_moniker` is the moniker of the instance that owns the collection.
    ///
    /// The function returns once the child instance no longer exists in the topology.
    DestroyChild(struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        child fuchsia.component.decl.ChildRef;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Opens a [`fuchsia.sys2/StorageAdmin`] protocol for the exposed storage capability of an
    /// instance identified by its moniker. This protocol is served by component manager.
    ///
    /// TODO(http://fxbug.dev/97774): Move this function to [`fuchsia.sys2/RealmQuery`]
    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;
};