sdk/fidl/fuchsia.sys2/lifecycle_controller.fidl - fuchsia - Git at Google

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

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

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

     // ---------------------------------------------------------------
     // The methods below are considered deprecated and will be removed
     // in an upcoming API release.
     // ---------------------------------------------------------------

     /// Starts the instance identified by the given moniker. Relative
     /// monikers must start with "./".
     ///
     /// The function returns once the instance has been started.
     @available(added=7, deprecated=11, removed=12, note="Use StartInstance instead")
     strict Start(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> (struct {
         result StartResult;
     }) error fuchsia.component.Error;

     /// Stops the instance identified by the given moniker. Relative
     /// monikers must start with "./".
     ///
     /// The function returns once the instance has been stopped.
     ///
     /// Note: `is_recursive` is no longer supported by component manager.
     ///       Setting it to true will return Error::Unsupported.
     @available(added=7, deprecated=11, removed=12, note="Use StopInstance instead")
     strict Stop(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
         is_recursive bool;
     }) -> () error fuchsia.component.Error;

     /// Resolves the instance identified by the given moniker. Relative
     /// monikers must start with "./".
     ///
     /// The function returns once the instance has been resolved
     @available(added=7, deprecated=11, removed=12, note="Use ResolveInstance instead")
     strict Resolve(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> () error fuchsia.component.Error;

     /// Unresolves the component designated by the provided moniker. Relative
     /// monikers must start with "./".
     ///
     /// The function returns once the component successfully unresolves, or the
     /// operation fails.
     @available(added=7, deprecated=11, removed=12, note="Use UnresolveInstance instead")
     strict Unresolve(struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
     }) -> () 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.
     @available(added=7, deprecated=11, removed=12, note="Use CreateInstance instead")
     strict 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;
     }) -> () 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.
     @available(added=7, deprecated=11, removed=12, note="Use DestroyInstance instead")
     strict DestroyChild(struct {
         parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
         child fuchsia.component.decl.ChildRef;
     }) -> () 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(https://fxbug.dev/42180039): Move this function to [`fuchsia.sys2/RealmQuery`]
     @available(added=11, deprecated=11, removed=12)
     strict GetStorageAdmin(resource struct {
         moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
         capability string:fuchsia.component.MAX_CAPABILITY_ID_LENGTH;
         admin_server server_end:StorageAdmin;
     }) -> () error fuchsia.component.Error;
 };

 /// Describes the result of the Start command.
 @available(added=7, deprecated=11, removed=12, note="Use StartInstance instead")
 type StartResult = strict enum {
     /// The instance was started.
     STARTED = 0;

     /// The instance was already running.
     ALREADY_STARTED = 1;
 };
	// 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;
	};

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

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

	// ---------------------------------------------------------------
	// The methods below are considered deprecated and will be removed
	// in an upcoming API release.
	// ---------------------------------------------------------------

	/// Starts the instance identified by the given moniker. Relative
	/// monikers must start with "./".
	///
	/// The function returns once the instance has been started.
	@available(added=7, deprecated=11, removed=12, note="Use StartInstance instead")
	strict Start(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> (struct {
	result StartResult;
	}) error fuchsia.component.Error;

	/// Stops the instance identified by the given moniker. Relative
	/// monikers must start with "./".
	///
	/// The function returns once the instance has been stopped.
	///
	/// Note: `is_recursive` is no longer supported by component manager.
	/// Setting it to true will return Error::Unsupported.
	@available(added=7, deprecated=11, removed=12, note="Use StopInstance instead")
	strict Stop(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	is_recursive bool;
	}) -> () error fuchsia.component.Error;

	/// Resolves the instance identified by the given moniker. Relative
	/// monikers must start with "./".
	///
	/// The function returns once the instance has been resolved
	@available(added=7, deprecated=11, removed=12, note="Use ResolveInstance instead")
	strict Resolve(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> () error fuchsia.component.Error;

	/// Unresolves the component designated by the provided moniker. Relative
	/// monikers must start with "./".
	///
	/// The function returns once the component successfully unresolves, or the
	/// operation fails.
	@available(added=7, deprecated=11, removed=12, note="Use UnresolveInstance instead")
	strict Unresolve(struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	}) -> () 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.
	@available(added=7, deprecated=11, removed=12, note="Use CreateInstance instead")
	strict 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;
	}) -> () 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.
	@available(added=7, deprecated=11, removed=12, note="Use DestroyInstance instead")
	strict DestroyChild(struct {
	parent_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	child fuchsia.component.decl.ChildRef;
	}) -> () 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(https://fxbug.dev/42180039): Move this function to [`fuchsia.sys2/RealmQuery`]
	@available(added=11, deprecated=11, removed=12)
	strict GetStorageAdmin(resource struct {
	moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
	capability string:fuchsia.component.MAX_CAPABILITY_ID_LENGTH;
	admin_server server_end:StorageAdmin;
	}) -> () error fuchsia.component.Error;
	};

	/// Describes the result of the Start command.
	@available(added=7, deprecated=11, removed=12, note="Use StartInstance instead")
	type StartResult = strict enum {
	/// The instance was started.
	STARTED = 0;

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