| // 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 offered by a component to one of its children, which |
| /// may have been offered by the component's containing realm, the component |
| /// itself, or one of its other children. |
| type Offer = flexible union { |
| 1: service OfferService; |
| 2: protocol OfferProtocol; |
| 3: directory OfferDirectory; |
| 4: storage OfferStorage; |
| 5: runner OfferRunner; |
| 6: resolver OfferResolver; |
| 7: event OfferEvent; |
| 8: event_stream OfferEventStream; |
| }; |
| |
| /// Describes the type of dependency implied by the capability. |
| type DependencyType = strict enum { |
| /// A strong dependency which may be required by components that use it. |
| STRONG = 1; |
| /// A weak dependency which is allowed to form a cycle. Components that use |
| /// a weak dependency must support the dependency being unavailable at |
| /// arbitrary times. |
| WEAK = 2; |
| /// A weak dependency specifically used to mark cyclic dependencies from |
| /// migrated v1 components. |
| WEAK_FOR_MIGRATION = 3; |
| }; |
| |
| |
| /// Type used to create a mapping between 2 names. Used to rename service or component instances |
| /// in FIDL declarations. |
| type NameMapping = struct { |
| /// Name used in the source instance. |
| source_name name; |
| |
| /// Name used in the target instance. |
| target_name name; |
| }; |
| |
| /// Describes the expected availability of the capability. |
| type Availability = strict enum { |
| REQUIRED = 1; |
| OPTIONAL = 2; |
| SAME_AS_TARGET = 3; |
| }; |
| |
| /// Declares a service offered by a component to one of its children, which may |
| /// have been offered by the component's containing realm, the component itself, |
| /// or one of its other children. |
| /// |
| /// To learn more about services, see: |
| /// https://fuchsia.dev/fuchsia-src/glossary#service |
| type OfferService = table { |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent`, `self`, `child`, or `void`. If set to `void`, then the target |
| /// must offer or use the capability with `optional` availability. |
| 1: source Ref; |
| |
| /// Name identifying the service being offered. |
| 2: source_name name; |
| |
| /// Reference to the target. Must be `child` or `collection`. |
| 3: target Ref; |
| |
| /// The name under which the capability is being offered. |
| 4: target_name name; |
| |
| /// The list of allow listed instances to be offered. Instances of the service |
| /// not in this list will not be accessible by the target component. |
| /// If this is not set that means all instances from the source service are |
| /// offered. |
| 5: source_instance_filter vector<string:MAX_NAME_LENGTH>:MAX; |
| |
| /// List of renamed service instances. |
| 6: renamed_instances vector<NameMapping>:MAX; |
| |
| /// The availability of this capability. If set to `required`, the target |
| /// may use or offer the capability with either `required` or `optional` |
| /// availability. If set to `optional`, the target must use or offer the |
| /// capability with `optional` availability. The `same_as_target` value |
| /// causes this offer's availability to match the availability set in the |
| /// target. |
| 7: availability Availability; |
| }; |
| |
| /// Declares a protocol offered by a component to one of its children, |
| /// which may have been offered by the component's containing realm, the |
| /// component itself, or one of its other children. |
| /// |
| /// To learn more about protocols, see: |
| /// https://fuchsia.dev/fuchsia-src/glossary#protocol |
| type OfferProtocol = table { |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent`, `self`, `child`, `framework`, or `void`. If set to `void`, |
| /// then the target must offer or use the capability with `optional` |
| /// availability. |
| 1: source Ref; |
| |
| /// Name identifying the protocol being offered. |
| 2: source_name name; |
| |
| /// Reference to the target. Must be `child` or `collection`. |
| 3: target Ref; |
| |
| /// The name by which the capability is being offered. |
| 4: target_name name; |
| |
| /// The dependency type this offer represents. A component which receives a |
| /// weak offer must support the offered capability being unavailable at any |
| /// point. |
| 5: dependency_type DependencyType; |
| |
| /// The availability of this capability. If set to `required`, the target |
| /// may use or offer the capability with either `required` or `optional` |
| /// availability. If set to `optional`, the target must use or offer the |
| /// capability with `optional` availability. The `same_as_target` value |
| /// causes this offer's availability to match the availability set in the |
| /// target. |
| 6: availability Availability; |
| }; |
| |
| /// Declares a directory offered by a component to one of its children, which |
| /// may have been offered by the component's containing realm, the component |
| /// itself, or one of its other children. |
| type OfferDirectory = table { |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent`, `self`, `child`, `framework`, or `void`. If set to `void`, |
| /// then the target must offer or use the capability with `optional` |
| /// availability. |
| 1: source Ref; |
| |
| /// Name identifying the directory being offered. |
| 2: source_name name; |
| |
| /// Reference to the target of the capability. Must be `child` or |
| /// `collection`. |
| 3: target Ref; |
| |
| /// The name by which the capability is being offered. |
| 4: target_name name; |
| |
| /// The maximum rights that can be set by a component using this directory, |
| /// required iff `source == self`. |
| 5: rights fuchsia.io.Rights; |
| |
| /// The subdirectory of this directory to offer instead of the root. Optional. |
| 6: subdir string:MAX_PATH_LENGTH; |
| |
| /// The dependency type this offer represents. A component which receives a |
| /// weak offer must support the offered capability being unavailable at any |
| /// point. |
| 7: dependency_type DependencyType; |
| |
| /// The availability of this capability. If set to `required`, the target |
| /// may use or offer the capability with either `required` or `optional` |
| /// availability. If set to `optional`, the target must use or offer the |
| /// capability with `optional` availability. The `same_as_target` value |
| /// causes this offer's availability to match the availability set in the |
| /// target. |
| 8: availability Availability; |
| }; |
| |
| /// Declares a storage capability offered by a component to one of its children, |
| /// such as meta storage offered by the component's containing realm or cache |
| /// storage offered by the component itself. |
| type OfferStorage = table { |
| /// The name of the storage capability being offered |
| 1: source_name name; |
| |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent`, `storage`, or `void`. If set to `void`, then the target must |
| /// offer or use the capability with `optional` availability. |
| 2: source Ref; |
| |
| /// Reference to the target of the capability. Must be `child` or |
| /// `collection`. |
| 3: target Ref; |
| |
| /// The name the storage capability is being offered as |
| 4: target_name name; |
| |
| /// The availability of this capability. If set to `required`, the target |
| /// may use or offer the capability with either `required` or `optional` |
| /// availability. If set to `optional`, the target must use or offer the |
| /// capability with `optional` availability. The `same_as_target` value |
| /// causes this offer's availability to match the availability set in the |
| /// target. |
| 5: availability Availability; |
| }; |
| |
| /// Declares a runner offered by a component to one of its children, which may |
| /// have been offered by the component's containing realm, the component itself, |
| /// or one of its other children. |
| type OfferRunner = table { |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent`, `self`, or `child`. |
| 1: source Ref; |
| |
| /// Name of the runner being offered. |
| 2: source_name name; |
| |
| /// Reference to the target of the capability. Must be `child` or |
| /// `collection`. |
| 3: target Ref; |
| |
| /// Name under which the capability is being offered. |
| 4: target_name name; |
| }; |
| |
| /// Declares a resolver capability offered by a component to one of its children, which |
| /// may have been offered by the component's containing realm, the component itself, |
| /// or one of its other children. |
| type OfferResolver = table { |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent`, `self`, or `child`. |
| 1: source Ref; |
| |
| /// Name of the resolver being offered. |
| 2: source_name name; |
| |
| /// Reference to the target of the capability. Must be `child` or |
| /// `collection`. |
| 3: target Ref; |
| |
| /// Name under which the capability is being offered. |
| 4: target_name name; |
| }; |
| |
| /// Declares an event offered by a component. |
| type OfferEvent = table { |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent` or `void`. If set to `void`, then the target must offer or use |
| /// the capability with `optional` availability. |
| 1: source Ref; |
| |
| /// Name of the event being offered. |
| 2: source_name name; |
| |
| /// Reference to the target of the event. Must be `child` or `collection`. |
| 3: target Ref; |
| |
| /// Name under which the event is being offered. |
| 4: target_name name; |
| |
| /// Filter for the event. The structure of the filter depends on the event type. May be absent |
| /// for some events. |
| 5: filter fuchsia.data.Dictionary; |
| |
| /// The availability of this capability. If set to `required`, the target |
| /// may use or offer the capability with either `required` or `optional` |
| /// availability. If set to `optional`, the target must use or offer the |
| /// capability with `optional` availability. The `same_as_target` value |
| /// causes this offer's availability to match the availability set in the |
| /// target. |
| 6: availability Availability; |
| }; |
| |
| /// Declares an event stream offered by a component. |
| type OfferEventStream = table { |
| /// The provider of the capability relative to the component itself. Must be |
| /// `parent`, `framework`, `child`, or `void`. If set to `void`, then the |
| /// target must offer or use the capability with `optional` availability. |
| 1: source Ref; |
| |
| /// Name of the event being offered. |
| 2: source_name name; |
| |
| /// When an event is offered from framework, the scope is required and allows |
| /// one to define the child (or array of children) which the event is about. |
| /// When the event is offered 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; |
| |
| /// The destination to which the event stream is offered. |
| 4: target Ref; |
| |
| /// Name under which the event stream is being offered. |
| 5: target_name name; |
| |
| /// Filter for the event stream. Only present for DirectoryReady events |
| /// and CapabilityRequested events |
| 6: filter fuchsia.data.Dictionary; |
| |
| /// The availability of this capability. If set to `required`, the target |
| /// may use or offer the capability with either `required` or `optional` |
| /// availability. If set to `optional`, the target must use or offer the |
| /// capability with `optional` availability. The `same_as_target` value |
| /// causes this offer's availability to match the availability set in the |
| /// target. |
| 7: availability Availability; |
| }; |