zircon/system/fidl/fuchsia-io2/connection-info.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.io2;

/// Returns run-time information about a node that is specific to the
/// current connection.
table ConnectionInfo {
    /// The active variant corresponds to one of the supported protocols
    /// of the node, and represents the result of the connection-time
    /// negotiation. Provides auxiliary handles if applicable.
    1: Representation representation;

    /// Information about the rights possessed by the current connection.
    /// Note: `rights` limits the set of operations allowed on the connection,
    /// but does not guarantee their availability. For example, one may have
    /// the [`Rights.EXECUTE`] right on a file connection, but the file itself
    /// does not have the `EXECUTE` ability, and hence cannot be executed.
    /// See [`ConnectionOptions.rights`].
    2: Rights rights;

    /// The set of available operations on this channel. It is always the
    /// intersection between the rights possessed by this connection, and the
    /// abilities of the node. The value may be zero in the case of an empty
    /// intersection.
    /// See [`ConnectionOptions.rights`].
    3: Operations available_operations;
};

/// Set the relevant bit to one to fetch the corresponding field
/// during [`fuchsia.io2/Node.Describe`].
bits ConnectionInfoQuery : uint64 {
    /// Requests [`ConnectionInfo.representation`].
    REPRESENTATION = 0x1;

    /// Requests [`ConnectionInfo.rights`].
    RIGHTS = 0x2;

    /// Requests [`ConnectionInfo.available_operations`].
    AVAILABLE_OPERATIONS = 0x4;
};

/// Describes how the connection should be handled, and provides auxiliary
/// handles and information for the connection where applicable.
/// Refer to [`Node.Describe`] and [`Node.OnConnectionInfo`].
///
/// If handles are returned which offer alternative ways of access to the node,
/// the rights on the handles should correspond to the rights on the connection.
///
/// If the client specified more than one protocol in `protocols` during
/// [`Directory.Open`] or [`Node.Reopen`], the [`Representation`] xunion carries
/// additionally the result of the connection-time negotiation via its tag.
///
/// The elements have one-to-one correspondence with the members of
/// [`NodeProtocolSet`].
xunion Representation {
    /// See [`NodeProtocolSet.CONNECTOR`].
    ConnectorInfo connector;

    /// See [`NodeProtocolSet.DIRECTORY`].
    DirectoryInfo directory;

    /// See [`NodeProtocolSet.FILE`].
    FileInfo file;

    /// See [`NodeProtocolSet.MEMORY`].
    MemoryInfo memory;

    /// See [`NodeProtocolSet.POSIX_SOCKET`].
    PosixSocketInfo posix_socket;

    /// See [`NodeProtocolSet.PIPE`].
    PipeInfo pipe;

    /// See [`NodeProtocolSet.DEBUGLOG`].
    DebuglogInfo debuglog;

    [Deprecated = "devices will be services in the future"]
    DeviceInfo device;

    [Deprecated = "tty may not be useful"]
    TtyInfo tty;
};

/// A node may have multiple supported representations when opening, even though
/// it may have a fixed underlying identity.
///
/// Today, a file is accessed via the [`fuchsia.io2/File`] protocol, and sends a
/// [`Representation.FileInfo`] when opened with `GET_CONNECTION_INFO`. However,
/// in the future we might introduce a more sophisticated `FileV2` protocol, or
/// a more efficient `SuperFastFile` backed by a specialized kernel object.
/// New clients can request the more advanced representations by specifying
/// the corresponding bits in [`NodeProtocolSet`], whereas existing clients
/// would continue to talk to the node via the old representation.
///
/// [`NodeProtocolSet`] enables forward-compatibility through a form of protocol
/// negotiation.
///
/// The elements have one-to-one correspondence with the members of
/// [`Representation`].
bits NodeProtocolSet : uint64 {
    /// The connector representation of a node.
    /// The connection will speak either [`fuchsia.io2/Node`], or some custom
    /// protocol, depending on the flags used during opening and reopening.
    CONNECTOR = 0x1;

    /// The directory representation of a node.
    /// The connection will speak the [`fuchsia.io2/Directory`] protocol.
    DIRECTORY = 0x2;

    /// The file representation of a node.
    /// The connection will speak the [`fuchsia.io2/File`] protocol.
    FILE = 0x4;

    /// The memory representation of a node. A memory object is a file whose
    /// contents are explicitly backed by some VMO.
    /// The connection will speak the [`fuchsia.io2/Memory`] protocol, and
    /// [`Representation`] would contain a [`fuchsia.mem/Range`] object
    /// representing the contents of the file.
    MEMORY = 0x8;

    /// The POSIX socket representation of a node.
    /// The connection will speak the [`fuchsia.posix.socket/Control`] protocol.
    POSIX_SOCKET = 0x10;

    /// The pipe representation of a node.
    /// The connection will speak the [`fuchsia.io2/Pipe`] protocol.
    PIPE = 0x20;

    /// The debuglog representation of a node.
    /// The connection will speak the [`fuchsia.io2/Debuglog`] protocol.
    DEBUGLOG = 0x40;

    [Deprecated = "devices will be services in the future"]
    DEVICE = 0x10000000;

    [Deprecated = "tty functionalities may be covered by a tty service"]
    TTY = 0x20000000;
};