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.
@available(added=7)
library fuchsia.sys2;

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

// Errors that can occur from resolving a component instance
@available(added=11)
type ResolveError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
    // The package containing the component manifest could not be found.
    PACKAGE_NOT_FOUND = 4;
    // The component manifest could not be found in the package.
    MANIFEST_NOT_FOUND = 5;
    // The component failed a policy check.
    @available(added=19)
    POLICY_ERROR = 6;
};

// Errors that can occur from starting a component instance
@available(added=11)
type StartError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
    // The package containing the component manifest could not be found.
    PACKAGE_NOT_FOUND = 4;
    // The component manifest could not be found in the package.
    MANIFEST_NOT_FOUND = 5;
    // The component failed a policy check.
    @available(added=19)
    POLICY_ERROR = 6;
    // The input was invalid.
    @available(added=HEAD)
    INVALID_ARGUMENTS = 7;
};

// Errors that can occur from stopping a component instance
@available(added=11)
type StopError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
};

// Errors that can occur from destroying a component instance
@available(added=11)
type DestroyError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
    // The given child reference is invalid.
    BAD_CHILD_REF = 4;
    // The instance identified by the given moniker exists but has not been
    // resolved.
    @available(added=20)
    INSTANCE_NOT_RESOLVED = 5;
};

// Errors that can occur from unresolving a component instance
@available(added=11)
type UnresolveError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The given moniker is invalid.
    BAD_MONIKER = 3;
};

// Errors that can occur from creating a component instance
@available(added=11)
type CreateError = flexible enum {
    // An unexpected error occurred.
    INTERNAL = 1;
    // The instance identified by the given moniker could not be found.
    INSTANCE_NOT_FOUND = 2;
    // The instance identified by the given moniker already exists.
    INSTANCE_ALREADY_EXISTS = 3;
    // The given moniker is invalid.
    BAD_MONIKER = 4;
    // The given child declaration is invalid.
    BAD_CHILD_DECL = 5;
    // The parent instance does not have a collection with the given name.
    COLLECTION_NOT_FOUND = 6;
    // A given dynamic offer is invalid.
    BAD_DYNAMIC_OFFER = 7;
    // The specified collection does not allow dynamic offers.
    DYNAMIC_OFFERS_FORBIDDEN = 8;
    // The specified collection does not allow eager startup.
    @available(removed=19)
    EAGER_STARTUP_FORBIDDEN = 9;
    // The specified collection does not allow numbered handles.
    NUMBERED_HANDLES_FORBIDDEN = 10;
};

/// Mutates the component instance state in a realm.
@discoverable(server="platform")
closed protocol LifecycleController {
    /// Starts the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The client can pass in the server end of a channel
    /// for the fuchsia.component.Binder protocol. This protocol
    /// will notify the client when the instance has stopped.
    ///
    /// The function returns once the instance has been started. Calling
    /// StartInstance() when the instance is already running is a no-op, but
    /// it will connect the Binder channel if a valid handle is provided.
    @available(added=11)
    strict StartInstance(resource struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        binder server_end:fuchsia.component.Binder;
    }) -> () error StartError;

    @available(added=22)
    strict StartInstanceWithArgs(resource struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        binder server_end:fuchsia.component.Binder;
        args fuchsia.component.StartChildArgs;
    }) -> () error StartError;

    /// Stops the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been stopped.
    @available(added=11)
    strict StopInstance(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error StopError;

    /// Resolves the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been resolved.
    @available(added=11)
    strict ResolveInstance(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error ResolveError;

    /// Unresolves the component designated by the provided moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the instance has been unresolved.
    @available(added=11)
    strict UnresolveInstance(struct {
        moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> () error UnresolveError;

    /// Creates a new child instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the child instance has been added to the topology.
    @available(added=11)
    strict CreateInstance(resource struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        collection fuchsia.component.decl.CollectionRef;
        decl fuchsia.component.decl.Child;
        args fuchsia.component.CreateChildArgs;
    }) -> () error CreateError;

    /// Destroys the instance identified by the given moniker. Relative
    /// monikers must start with "./".
    ///
    /// The function returns once the child instance no longer exists in the topology.
    @available(added=11)
    strict DestroyInstance(struct {
        parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        child fuchsia.component.decl.ChildRef;
    }) -> () error DestroyError;
};