// 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.io;

using fuchsia.mem;
using zx;

/// Returns run-time information about a node that is specific to the
/// current connection.
type ConnectionInfo = resource table {
    /// 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.
    ///
    /// 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`] carries
    /// additionally the result of the connection-time negotiation via its tag.
    ///
    /// The elements have one-to-one correspondence with the members of
    /// [`NodeProtocols`].
    1: representation @generated_name("Representation") flexible resource union {
        /// Auxiliary data for the connector representation of a node, used for
        /// protocol discovery and connection.
        ///
        /// It supports connecting to arbitrary protocols exported by the filesystem
        /// server at a path, including ones that do not compose [`Node2`].
        ///
        /// See [`NodeProtocols.CONNECTOR`].
        1: connector @generated_name("ConnectorInfo") table {};

        /// Auxiliary data for the directory representation of a node.
        /// The selection of this variant in [`Representation`] implies that the
        /// connection speaks the [`Directory`] protocol.
        ///
        /// See [`NodeProtocols.DIRECTORY`].
        2: directory @generated_name("DirectoryInfo") table {};

        /// Auxiliary data for the file representation of a node.
        /// The selection of this variant in [`Representation`] implies that the
        /// connection speaks the [`File`] protocol.
        ///
        /// See [`NodeProtocols.FILE`].
        3: file @generated_name("FileInfo") resource table {
            /// An optional event which transmits information about an object's
            /// readability or writability. This event relays information about the
            /// underlying object, not the capability granted to client: this event
            /// may be signalled "readable" on a connection that does not have
            /// the capability to read.
            ///
            /// This event will be present if the following conditions are met:
            ///
            /// - The `available_operations` on the file connection is not empty.
            /// - The filesystem supports signalling readability/writability events.
            ///
            /// The [`FileSignal`] values may be observed on this event.
            1: observer zx.handle:EVENT;

            /// Returns if the file is opened in append mode.
            /// In append mode, the seek offset is moved to the end before every
            /// write, the two steps performed in an atomic manner.
            2: is_append bool;

            /// An optional stream object, which can be used to read to and write from
            /// the file.
            ///
            /// Reading and writing the file using the stream object can be up to 20x
            /// faster than reading and writing the file using the Read and Write
            /// operations in the [`File`] protocol.
            3: stream zx.handle:STREAM;
        };

        /// Auxiliary data for the memory object representation of a node.
        /// The node is a file which is represented as a VMO.
        /// The selection of this variant in [`Representation`] implies that the
        /// connection speaks the [`Memory`] protocol.
        ///
        /// See [`NodeProtocols.MEMORY`].
        4: memory @generated_name("MemoryInfo") resource table {
            /// Although a VMO is returned as a part of this structure, that VMO may
            /// back multiple files. To identify the logical portion of the VMO that
            /// represents the single file, offset and size are also supplied.
            ///
            /// If the range covers the entire VMO (i.e. the offset is zero and the
            /// length matches the size of the VMO), then all clients must receive a
            /// VMO with the same koid. This can be a duplicate of the same underlying
            /// page-aligned VMO.
            ///
            /// The rights on this VMO should correspond to the rights on the
            /// node connection.
            1: buffer fuchsia.mem.Range;
        };

        /// The connection composes [`fuchsia.hardware.block.BlockAndNode`] OR
        /// [`fuchsia.hardware.block.volume.VolumeAndNode`].
        ///
        /// TODO(https://fxbug.dev/103827): Document why this is needed or
        /// remove it.
        5: device @generated_name("DeviceInfo") resource table {
            /// An optional event which transmits information about a device's state.
            ///
            /// The [`DeviceSignal`] values may be observed on this event.
            1: unused zx.handle:EVENTPAIR;
        };

        /// The object may be cast to a Tty interface.
        @deprecated("tty functionalities may be covered by a tty service")
        6: tty @generated_name("TtyInfo") resource table {
            /// An optional event which transmits information about a device's state.
            ///
            /// The [`DeviceSignal`] values may be observed on this event.
            1: event zx.handle:EVENTPAIR;
        };

        /// The connection composes [`fuchsia.posix.socket/SynchronousDatagramSocket`].
        ///
        /// See [`NodeProtocols.SYNCHRONOUS_DATAGRAM_SOCKET`].
        7: synchronous_datagram_socket
                @generated_name("SynchronousDatagramSocketInfo")
                resource table {
            1: event zx.handle:EVENTPAIR;
        };

        /// The connection composes [`fuchsia.posix.socket/DatagramSocket`].
        ///
        /// See [`NodeProtocols.DATAGRAM_SOCKET`].
        8: datagram_socket @generated_name("DatagramSocketInfo") resource table {
            /// See [`fuchsia.posix.socket.DatagramSocket`] for details.
            1: socket zx.handle:SOCKET;
            /// Size of the buffer used to receive Tx metadata.
            2: tx_meta_buf_size uint64;
            /// Size of the buffer used to receive Rx metadata.
            3: rx_meta_buf_size uint64;
        };

        /// The connection composes [`fuchsia.posix.socket/StreamSocket`].
        ///
        /// See [`NodeProtocols.STREAM_SOCKET`].
        9: stream_socket @generated_name("StreamSocketInfo") resource table {
            1: socket zx.handle:SOCKET;
        };

        /// The connection composes [`fuchsia.posix.socket.raw/Socket`].
        ///
        /// See [`NodeProtocols.RAW_SOCKET`].
       10: raw_socket @generated_name("RawSocketInfo") resource table {
            1: event zx.handle:EVENTPAIR;
        };

        /// The connection composes [`fuchsia.posix.socket.packet/Socket`].
        ///
        /// See [`NodeProtocols.PACKET_SOCKET`].
       11: packet_socket @generated_name("PacketSocketInfo") resource table {
            /// See [`fuchsia.posix.socket.packet.Socket`] for details.
            1: event zx.handle:EVENTPAIR;
        };
    };

    /// 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: available_operations Operations;
};