sdk/fidl/fuchsia.sys2/decls/use_decl.fidl

// Copyright 2019 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.sys2;

using fuchsia.component;
using fuchsia.data;
using fuchsia.io2;

/// Declares a capability used by a component, which was offered to the
/// component's environment.
flexible union UseDecl {
    1: UseServiceDecl service;
    2: UseProtocolDecl protocol;
    3: UseDirectoryDecl directory;
    4: UseStorageDecl storage;
    5: UseRunnerDecl runner;
    6: UseEventDecl event;
    7: UseEventStreamDecl event_stream;
};

/// Declares a service used by a component, which was offered to the component's
/// environment.
///
/// To learn more about services, see:
/// https://fuchsia.dev/fuchsia-src/glossary#service
table UseServiceDecl {
    /// The provider of the service relative to the component itself. Must
    /// be `parent` or `framework`.
    1: Ref source;

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

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

/// Declares a protocol used by a component, which was offered to the
/// component's environment.
///
/// A protocol is a service with a single instance, provided by a single FIDL
/// protocol.
table UseProtocolDecl {
    /// The provider of the protocol relative to the component itself.
    /// Must be `parent`, `framework`, `debug` or `capability`.
    1: Ref source;

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

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

/// Declares a directory used by a component, which was offered to the
/// component's environment.
table UseDirectoryDecl {
    /// The provider of the directory relative to the component itself. Must
    /// be `parent` or `framework`.
    1: Ref source;

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

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

    /// The rights required by the component to use this directory.
    4: fuchsia.io2.Rights rights;

    /// The subdirectory of this directory to use instead of the root. Optional.
    5: string:fuchsia.component.MAX_PATH_LENGTH subdir;
};

/// Declares storage used by a component, which was offered to the component's
/// environment.
table UseStorageDecl {
    /// Name identifying the storage, by which it was presented to this
    /// component.
    1: fuchsia.component.name source_name;

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

/// Declares a runner used by a component, which was offered to the component's
/// environment.
table UseRunnerDecl {
    /// The name of the runner, as it was presented to this component by the
    /// realm.
    1: fuchsia.component.name source_name;
};

/// Declares an event used by a component.
table UseEventDecl {
    /// The provider of the event. Must be |realm| or |framework|.
    1: Ref source;

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

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

    /// Filter for the event. The structure of the filter depends on the event type. May be absent
    /// for some events.
    4: fuchsia.data.Dictionary filter;

    /// The mode that the event can use.
    5: EventMode mode;
};

/// Declares a static EventStream used by a component.
table UseEventStreamDecl {
    /// The path where the EventStream protocol will be served.
    ///
    /// Must be an absolute path starting with /.
    1: string:fuchsia.component.MAX_PATH_LENGTH target_path;

    /// The set of events to which this EventStream is subscribed.
    /// Note: This vector must be non-empty.
    2: vector<EventSubscription>:fuchsia.component.MAX_NUM_EVENTS_RECEIVED events;
};