sdk/fidl/fuchsia.io/connection-info.fidl - fuchsia - Git at Google

 // 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 pipe representation of a node.
         /// A pipe is a data streaming interface, commonly used for standard in/out.
         /// There is no universal requirement as to if it is uni- or bi-directional.
         /// The selection of this variant in [`Representation`] implies that the
         /// connection speaks the [`Pipe`] protocol.
         ///
         /// See [`NodeProtocols.PIPE`].
         5: pipe @generated_name("PipeInfo") resource table {
             /// The backing socket transport for the pipe.
             /// The rights on this socket should correspond to the rights on the
             /// node connection.
             1: socket zx.handle:SOCKET;
         };

         /// The object may be cast to the shared interface of devices.
         @deprecated("devices will be services in the future")
         6: 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")
         7: 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`].
         8: synchronous_datagram_socket
                 @generated_name("SynchronousDatagramSocketInfo")
                 resource table {
             1: event zx.handle:EVENTPAIR;
         };

         /// The connection composes [`fuchsia.posix.socket/DatagramSocket`].
         ///
         /// See [`NodeProtocols.DATAGRAM_SOCKET`].
         9: 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`].
        10: stream_socket @generated_name("StreamSocketInfo") resource table {
             1: socket zx.handle:SOCKET;
         };

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

         /// The connection composes [`fuchsia.posix.socket.packet/Socket`].
         ///
         /// See [`NodeProtocols.PACKET_SOCKET`].
        12: 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;
 };
	// 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 pipe representation of a node.
	/// A pipe is a data streaming interface, commonly used for standard in/out.
	/// There is no universal requirement as to if it is uni- or bi-directional.
	/// The selection of this variant in [`Representation`] implies that the
	/// connection speaks the [`Pipe`] protocol.
	///
	/// See [`NodeProtocols.PIPE`].
	5: pipe @generated_name("PipeInfo") resource table {
	/// The backing socket transport for the pipe.
	/// The rights on this socket should correspond to the rights on the
	/// node connection.
	1: socket zx.handle:SOCKET;
	};

	/// The object may be cast to the shared interface of devices.
	@deprecated("devices will be services in the future")
	6: 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")
	7: 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`].
	8: synchronous_datagram_socket
	@generated_name("SynchronousDatagramSocketInfo")
	resource table {
	1: event zx.handle:EVENTPAIR;
	};

	/// The connection composes [`fuchsia.posix.socket/DatagramSocket`].
	///
	/// See [`NodeProtocols.DATAGRAM_SOCKET`].
	9: 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`].
	10: stream_socket @generated_name("StreamSocketInfo") resource table {
	1: socket zx.handle:SOCKET;
	};

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

	/// The connection composes [`fuchsia.posix.socket.packet/Socket`].
	///
	/// See [`NodeProtocols.PACKET_SOCKET`].
	12: 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;
	};