blob: bc9e135f97eb006733cc1fd767e47fff089dd273 [file] [log] [blame]
// 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;
};