// 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.
resource 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
/// [`NodeProtocols`].
flexible resource union Representation {
    /// See [`NodeProtocols.CONNECTOR`].
    1: ConnectorInfo connector;

    /// See [`NodeProtocols.DIRECTORY`].
    2: DirectoryInfo directory;

    /// See [`NodeProtocols.FILE`].
    3: FileInfo file;

    /// See [`NodeProtocols.MEMORY`].
    4: MemoryInfo memory;

    /// See [`NodeProtocols.POSIX_SOCKET`].
    5: PosixSocketInfo posix_socket;

    /// See [`NodeProtocols.PIPE`].
    6: PipeInfo pipe;

    /// See [`NodeProtocols.DEBUGLOG`].
    7: DebuglogInfo debuglog;

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

    [Deprecated = "tty may not be useful"]
    9: 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 [`NodeProtocols`], whereas existing clients
/// would continue to talk to the node via the old representation.
///
/// [`NodeProtocols`] enables forward-compatibility through a form of protocol
/// negotiation.
///
/// The elements have one-to-one correspondence with the members of
/// [`Representation`].
bits NodeProtocols : 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;
};