sdk/fidl/fuchsia.component.decl/use.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.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;
    5: event UseEvent;
    6: event_stream_deprecated UseEventStreamDeprecated;
    7: event_stream UseEventStream;
};

/// 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 service relative to the component itself.
    /// Must be `parent` or `framework`. If the availability is set to
    /// `optional`, then this must be set to `parent`.
    1: source Ref;

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

    /// (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`. If the
    /// availability is set to `optional`, then this must be set to `parent`.
    1: source Ref;

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

    /// (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`. If the availability
    /// is set to `optional`, then this must be set to `parent`.
    1: source Ref;

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

    /// (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. If the availability is set to `optional`, then this must
    /// be set to `parent`.
    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.
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.
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`. If
    /// the availability is set to `optional`, then this must be set to
    /// `parent`.
    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
    /// `DirectoryReady` and `CapabilityRequested` event types.
    @available(added=9)
    6: filter fuchsia.data.Dictionary;
};