sdk/fidl/fuchsia.component.decl/use.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.
 library fuchsia.component.decl;

 using fuchsia.data;
 using fuchsia.io;

 /// Declares a capability used by a component, which was offered to it.
 type Use = flexible union {
     1: service UseService;
     2: protocol UseProtocol;
     3: directory UseDirectory;
     4: storage UseStorage;
     @available(removed=14)
     5: event UseEvent;
     @available(removed=14)
     6: event_stream_deprecated UseEventStreamDeprecated;
     7: event_stream UseEventStream;
     @available(added=HEAD)
     8: runner UseRunner;
     @available(added=20)
     9: config UseConfiguration;
 };

 /// Declares a service used by a component, which was offered to it.
 ///
 /// To learn more about services, see:
 /// https://fuchsia.dev/fuchsia-src/glossary#service
 type UseService = table {
     /// (Required) The provider of the protocol relative to the component
     /// itself. Must be `parent`, `framework`, `self`, or `child`.
     1: source Ref;

     /// (Required) Name identifying the service, by which it was presented to
     /// this component.
     2: source_name name;

     /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
     /// If this field is absent, `source_name` identifies a capability directly routed
     /// by `source`. If set, `source_name` identifies a capability nested inside this
     /// dictionary.
     @available(added=HEAD)
     6: source_dictionary dictionary_path;

     /// (Required) The path where the capability should be installed in the
     /// component's namespace.
     ///
     /// Must be an absolute path starting with /.
     3: target_path string:MAX_PATH_LENGTH;

     /// (Required) The dependency type this use represents.
     ///
     /// A component which offers a capability to a child from itself and uses a
     /// capability from the same child, must mark the dependency as `weak`.  A
     /// `weak` dependency implies that the capability may become unavailable at
     /// any point. Taking a strong dependency on a child's capability will
     /// cause this the child to shut down before its parent. When using a weak
     /// dependency, the parent shuts down before the child.
     4: dependency_type DependencyType;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     5: availability Availability;
 };

 /// Declares a protocol used by a component, which was offered to it.
 ///
 /// A protocol is a service with a single instance, provided by a single FIDL
 /// protocol.
 type UseProtocol = table {
     /// (Required) The provider of the protocol relative to the component
     /// itself. Must be `parent`, `framework`, `debug`, `capability` or `child`.
     1: source Ref;

     /// (Required) Name identifying the protocol, by which it was presented to this
     /// component.
     2: source_name name;

     /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
     /// If this field is absent, `source_name` identifies a capability directly routed
     /// by `source`. If set, `source_name` identifies a capability nested inside this
     /// dictionary.
     @available(added=HEAD)
     6: source_dictionary dictionary_path;

     /// (Required) The path where the capability should be installed in the component's
     /// namespace.
     ///
     /// Must be an absolute path starting with /.
     3: target_path string:MAX_PATH_LENGTH;

     /// (Required) The dependency type this use represents.
     ///
     /// A component which offers a capability to a child from itself and uses a
     /// capability from the same child, must mark the dependency as `weak`.  A
     /// `weak` dependency implies that the capability may become unavailable at
     /// any point. Taking a strong dependency on a child's capability will
     /// cause this the child to shut down before its parent. When using a weak
     /// dependency, the parent shuts down before the child.
     4: dependency_type DependencyType;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     5: availability Availability;
 };

 /// Declares a directory used by a component, which was offered to it.
 type UseDirectory = table {
     /// (Required) The provider of the directory relative to the component
     /// itself. Must be `parent`, `framework`,  or `child`.
     1: source Ref;

     /// (Required) Name identifying the directory, by which it was presented to
     /// this component.
     2: source_name name;

     /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
     /// If this field is absent, `source_name` identifies a capability directly routed
     /// by `source`. If set, `source_name` identifies a capability nested inside this
     /// dictionary.
     @available(added=HEAD)
     8: source_dictionary dictionary_path;

     /// (Required) The path where the capability should be installed in the
     /// component's namespace.
     ///
     /// Must be an absolute path starting with /.
     3: target_path string:MAX_PATH_LENGTH;

     /// (Required) The rights required by the component to use this directory.
     4: rights fuchsia.io.Rights;

     /// (Optional) The subdirectory of this directory to use instead of the
     /// root.
     5: subdir string:MAX_PATH_LENGTH;

     /// (Required) The dependency type this use represents.
     ///
     /// A component which offers a capability to a child from itself and uses a
     /// capability from the same child, must mark the dependency as `weak`.  A
     /// `weak` dependency implies that the capability may become unavailable at
     /// any point. Taking a strong dependency on a child's capability will
     /// cause this the child to shut down before its parent. When using a weak
     /// dependency, the parent shuts down before the child.
     6: dependency_type DependencyType;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     7: availability Availability;
 };

 /// Declares storage used by a component, which was offered to it.
 type UseStorage = table {
     /// (Required) Name identifying the storage, by which it was presented to
     /// this component.
     1: source_name name;

     /// (Required) The path where the capability should be installed in the
     /// component's namespace.
     ///
     /// Must be an absolute path starting with /.
     2: target_path string:MAX_PATH_LENGTH;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     3: availability Availability;
 };

 /// Declares an event used by a component, which was offered to it.
 @available(removed=14)
 type UseEvent = table {
     /// (Required) The provider of the event. Must be `realm` or `framework`. If
     /// the availability is set to `optional`, then this must be set to
     /// `parent`.
     1: source Ref;

     /// (Required) Name identifying the event which was presented to this
     /// component.
     2: source_name name;

     /// (Required) The name which the component will use to refer to this event.
     3: target_name name;

     /// (Optional) Filter for the event. The structure of the filter depends on
     /// the event type. May be absent for some events. (TODO: which ones?)
     4: filter fuchsia.data.Dictionary;

     /// (Required) The dependency type this use represents.
     ///
     /// A component which offers a capability to a child from itself and uses a
     /// capability from the same child, must mark the dependency as `weak`.  A
     /// `weak` dependency implies that the capability may become unavailable at
     /// any point. Taking a strong dependency on a child's capability will
     /// cause this the child to shut down before its parent. When using a weak
     /// dependency, the parent shuts down before the child.
     5: dependency_type DependencyType;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     6: availability Availability;
 };

 /// Declares a static EventStream used by a component.
 @available(removed=14)
 type UseEventStreamDeprecated = table {
     /// (Required) The name of the event stream.
     1: name name;

     /// (Required) The set of events to which this EventStream is subscribed.
     /// Note: This vector must be non-empty.
     2: subscriptions vector<EventSubscription>:MAX_NUM_EVENT_STREAM_SUBSCRIPTIONS;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     3: availability Availability;
 };

 /// Declares an EventStream used by a component.
 type UseEventStream = table {
     /// (Required) The names of the event streams.
     1: source_name name;

     /// (Required) The provider of the event. Must be `parent`, `framework`, or `child`.
     2: source Ref;

     /// (Optional) When an event is used from framework, the scope is required
     /// to specify the child (or array of children) which the event will be
     /// about. When the event is used from parent, the scope can be used to
     /// downscope the event to a certain child scope, otherwise the event will
     /// carry the scope coming from the parent.
     3: scope vector<Ref>:MAX;

     /// (Required) The path where the capability should be installed in the
     /// component's namespace. Must be an absolute path starting with /.
     4: target_path name;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     5: availability Availability;

     /// (Optional) Filter for the event stream. The structure of the filter
     /// depends on the event stream type. Only supported for the
     /// `CapabilityRequested` event type.
     @available(added=9)
     6: filter fuchsia.data.Dictionary;
 };

 /// Declares runner used by a component.
 @available(added=HEAD)
 type UseRunner = table {
     /// (Required) The provider of the runner relative to the component.
     /// Must be `parent`, `child`, `framework`, or `environment`.
     1: source Ref;

     /// (Required) Name identifying the runner, by which it was presented to this
     /// component.
     2: source_name name;

     /// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
     /// If this field is absent, `source_name` identifies a capability directly routed
     /// by `source`. If set, `source_name` identifies a capability nested inside this
     /// dictionary.
     @available(added=HEAD)
     3: source_dictionary dictionary_path;
 };

 @available(added=20)
 type UseConfiguration = table {
     /// (Required) The provider of the configuration relative to the component
     /// itself. Must be `parent`, `self`, `child`.
     1: source Ref;

     /// (Required) Name identifying the configuration, by which it was presented to this
     /// component.
     2: source_name name;

     /// (Required) The name that the component sees for this configuration.
     /// This must match a key in the 'config' schema for this component. The
     /// matching config field's type must match this configuration type.
     3: target_name name;

     /// (Optional, defaults to `REQUIRED`) The availability of this capability.
     /// If set to `required`, the component is likely to malfunction if this
     /// capability is not provided. If set to `optional`, the component can
     /// handle the capability's absence.
     4: availability Availability;

     /// (Required) The type of this config value. If `target_name` matches a
     /// key in the `config` schema, then this type must match that type.
     5: type ConfigType;

     /// (Optional): If this is set, this is the value that will be provided via routing
     /// if the capability is successfully routed from void.
     6: default ConfigValue;
 };
	// 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.component.decl;

	using fuchsia.data;
	using fuchsia.io;

	/// Declares a capability used by a component, which was offered to it.
	type Use = flexible union {
	1: service UseService;
	2: protocol UseProtocol;
	3: directory UseDirectory;
	4: storage UseStorage;
	@available(removed=14)
	5: event UseEvent;
	@available(removed=14)
	6: event_stream_deprecated UseEventStreamDeprecated;
	7: event_stream UseEventStream;
	@available(added=HEAD)
	8: runner UseRunner;
	@available(added=20)
	9: config UseConfiguration;
	};

	/// Declares a service used by a component, which was offered to it.
	///
	/// To learn more about services, see:
	/// https://fuchsia.dev/fuchsia-src/glossary#service
	type UseService = table {
	/// (Required) The provider of the protocol relative to the component
	/// itself. Must be `parent`, `framework`, `self`, or `child`.
	1: source Ref;

	/// (Required) Name identifying the service, by which it was presented to
	/// this component.
	2: source_name name;

	/// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
	/// If this field is absent, `source_name` identifies a capability directly routed
	/// by `source`. If set, `source_name` identifies a capability nested inside this
	/// dictionary.
	@available(added=HEAD)
	6: source_dictionary dictionary_path;

	/// (Required) The path where the capability should be installed in the
	/// component's namespace.
	///
	/// Must be an absolute path starting with /.
	3: target_path string:MAX_PATH_LENGTH;

	/// (Required) The dependency type this use represents.
	///
	/// A component which offers a capability to a child from itself and uses a
	/// capability from the same child, must mark the dependency as `weak`. A
	/// `weak` dependency implies that the capability may become unavailable at
	/// any point. Taking a strong dependency on a child's capability will
	/// cause this the child to shut down before its parent. When using a weak
	/// dependency, the parent shuts down before the child.
	4: dependency_type DependencyType;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	5: availability Availability;
	};

	/// Declares a protocol used by a component, which was offered to it.
	///
	/// A protocol is a service with a single instance, provided by a single FIDL
	/// protocol.
	type UseProtocol = table {
	/// (Required) The provider of the protocol relative to the component
	/// itself. Must be `parent`, `framework`, `debug`, `capability` or `child`.
	1: source Ref;

	/// (Required) Name identifying the protocol, by which it was presented to this
	/// component.
	2: source_name name;

	/// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
	/// If this field is absent, `source_name` identifies a capability directly routed
	/// by `source`. If set, `source_name` identifies a capability nested inside this
	/// dictionary.
	@available(added=HEAD)
	6: source_dictionary dictionary_path;

	/// (Required) The path where the capability should be installed in the component's
	/// namespace.
	///
	/// Must be an absolute path starting with /.
	3: target_path string:MAX_PATH_LENGTH;

	/// (Required) The dependency type this use represents.
	///
	/// A component which offers a capability to a child from itself and uses a
	/// capability from the same child, must mark the dependency as `weak`. A
	/// `weak` dependency implies that the capability may become unavailable at
	/// any point. Taking a strong dependency on a child's capability will
	/// cause this the child to shut down before its parent. When using a weak
	/// dependency, the parent shuts down before the child.
	4: dependency_type DependencyType;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	5: availability Availability;
	};

	/// Declares a directory used by a component, which was offered to it.
	type UseDirectory = table {
	/// (Required) The provider of the directory relative to the component
	/// itself. Must be `parent`, `framework`, or `child`.
	1: source Ref;

	/// (Required) Name identifying the directory, by which it was presented to
	/// this component.
	2: source_name name;

	/// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
	/// If this field is absent, `source_name` identifies a capability directly routed
	/// by `source`. If set, `source_name` identifies a capability nested inside this
	/// dictionary.
	@available(added=HEAD)
	8: source_dictionary dictionary_path;

	/// (Required) The path where the capability should be installed in the
	/// component's namespace.
	///
	/// Must be an absolute path starting with /.
	3: target_path string:MAX_PATH_LENGTH;

	/// (Required) The rights required by the component to use this directory.
	4: rights fuchsia.io.Rights;

	/// (Optional) The subdirectory of this directory to use instead of the
	/// root.
	5: subdir string:MAX_PATH_LENGTH;

	/// (Required) The dependency type this use represents.
	///
	/// A component which offers a capability to a child from itself and uses a
	/// capability from the same child, must mark the dependency as `weak`. A
	/// `weak` dependency implies that the capability may become unavailable at
	/// any point. Taking a strong dependency on a child's capability will
	/// cause this the child to shut down before its parent. When using a weak
	/// dependency, the parent shuts down before the child.
	6: dependency_type DependencyType;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	7: availability Availability;
	};

	/// Declares storage used by a component, which was offered to it.
	type UseStorage = table {
	/// (Required) Name identifying the storage, by which it was presented to
	/// this component.
	1: source_name name;

	/// (Required) The path where the capability should be installed in the
	/// component's namespace.
	///
	/// Must be an absolute path starting with /.
	2: target_path string:MAX_PATH_LENGTH;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	3: availability Availability;
	};

	/// Declares an event used by a component, which was offered to it.
	@available(removed=14)
	type UseEvent = table {
	/// (Required) The provider of the event. Must be `realm` or `framework`. If
	/// the availability is set to `optional`, then this must be set to
	/// `parent`.
	1: source Ref;

	/// (Required) Name identifying the event which was presented to this
	/// component.
	2: source_name name;

	/// (Required) The name which the component will use to refer to this event.
	3: target_name name;

	/// (Optional) Filter for the event. The structure of the filter depends on
	/// the event type. May be absent for some events. (TODO: which ones?)
	4: filter fuchsia.data.Dictionary;

	/// (Required) The dependency type this use represents.
	///
	/// A component which offers a capability to a child from itself and uses a
	/// capability from the same child, must mark the dependency as `weak`. A
	/// `weak` dependency implies that the capability may become unavailable at
	/// any point. Taking a strong dependency on a child's capability will
	/// cause this the child to shut down before its parent. When using a weak
	/// dependency, the parent shuts down before the child.
	5: dependency_type DependencyType;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	6: availability Availability;
	};

	/// Declares a static EventStream used by a component.
	@available(removed=14)
	type UseEventStreamDeprecated = table {
	/// (Required) The name of the event stream.
	1: name name;

	/// (Required) The set of events to which this EventStream is subscribed.
	/// Note: This vector must be non-empty.
	2: subscriptions vector<EventSubscription>:MAX_NUM_EVENT_STREAM_SUBSCRIPTIONS;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	3: availability Availability;
	};

	/// Declares an EventStream used by a component.
	type UseEventStream = table {
	/// (Required) The names of the event streams.
	1: source_name name;

	/// (Required) The provider of the event. Must be `parent`, `framework`, or `child`.
	2: source Ref;

	/// (Optional) When an event is used from framework, the scope is required
	/// to specify the child (or array of children) which the event will be
	/// about. When the event is used from parent, the scope can be used to
	/// downscope the event to a certain child scope, otherwise the event will
	/// carry the scope coming from the parent.
	3: scope vector<Ref>:MAX;

	/// (Required) The path where the capability should be installed in the
	/// component's namespace. Must be an absolute path starting with /.
	4: target_path name;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	5: availability Availability;

	/// (Optional) Filter for the event stream. The structure of the filter
	/// depends on the event stream type. Only supported for the
	/// `CapabilityRequested` event type.
	@available(added=9)
	6: filter fuchsia.data.Dictionary;
	};

	/// Declares runner used by a component.
	@available(added=HEAD)
	type UseRunner = table {
	/// (Required) The provider of the runner relative to the component.
	/// Must be `parent`, `child`, `framework`, or `environment`.
	1: source Ref;

	/// (Required) Name identifying the runner, by which it was presented to this
	/// component.
	2: source_name name;

	/// (Optional) Path in a dictionary provided by `source` which contains `source_name`.
	/// If this field is absent, `source_name` identifies a capability directly routed
	/// by `source`. If set, `source_name` identifies a capability nested inside this
	/// dictionary.
	@available(added=HEAD)
	3: source_dictionary dictionary_path;
	};

	@available(added=20)
	type UseConfiguration = table {
	/// (Required) The provider of the configuration relative to the component
	/// itself. Must be `parent`, `self`, `child`.
	1: source Ref;

	/// (Required) Name identifying the configuration, by which it was presented to this
	/// component.
	2: source_name name;

	/// (Required) The name that the component sees for this configuration.
	/// This must match a key in the 'config' schema for this component. The
	/// matching config field's type must match this configuration type.
	3: target_name name;

	/// (Optional, defaults to `REQUIRED`) The availability of this capability.
	/// If set to `required`, the component is likely to malfunction if this
	/// capability is not provided. If set to `optional`, the component can
	/// handle the capability's absence.
	4: availability Availability;

	/// (Required) The type of this config value. If `target_name` matches a
	/// key in the `config` schema, then this type must match that type.
	5: type ConfigType;

	/// (Optional): If this is set, this is the value that will be provided via routing
	/// if the capability is successfully routed from void.
	6: default ConfigValue;
	};