sdk/fidl/fuchsia.io/node2.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.unknown;
 using zx;

 type MutableNodeAttributes = table {
     /// Time of creation in nanoseconds since the Unix epoch, UTC.
     1: creation_time uint64;

     /// Time of last modification in nanoseconds since the Unix epoch, UTC.
     2: modification_time uint64;
 };

 // TODO(https://fxbug.dev/105840): Inline this into its only reference when fidlgen_go is fixed.
 type ConnectionInfo = resource table {
     /// 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`].
     1: rights Rights;
 };

 // TODO(https://fxbug.dev/105608): Use a generated constant.
 const NODE_PROTOCOL_NAME string = "fuchsia.io/Node";

 /// Node defines the minimal protocol for entities which can be accessed
 /// in a filesystem.
 protocol Node2 {
     @available(added=9)
     compose fuchsia.unknown.Closeable;
     @available(added=9)
     compose fuchsia.unknown.Queryable;

     /// Creates another connection to the same node.
     ///
     /// + `object_request` is the server end of a channel created for the new
     ///   connection. The caller may proceed to send messages on the
     ///   corresponding client end right away.
     @transitional
     @selector("fuchsia.io/Node.Reopen")
     Reopen(resource struct {
         /// Requests rights on the new connection according to the specified rules.
         ///
         /// If absent, inherits the rights from the connection where the call
         /// is made.
         rights_request box<RightsRequest>;
         object_request zx.handle:CHANNEL;
     });

     /// Terminates the connection to the node.
     ///
     /// After calling `Close`, the client must not send any other requests.
     /// Servers, after sending the status response, should close the connection
     /// regardless of status and without sending an epitaph.
     ///
     /// Closing the client end of the channel should be semantically equivalent
     /// to calling `Close` without knowing when the close has completed or its
     /// status.
     ///
     /// This method does not require any rights.
     @available(removed=9)
     @selector("fuchsia.io/Node.Close")
     Close() -> (struct {}) error zx.status;

     /// An event produced eagerly by the server if requested by
     /// [`NodeFlags.GET_REPRESENTATION`]. This event will be the first message
     /// from the server, and is sent exactly once.
     ///
     /// 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.
     ///
     /// If the client specified more than one protocol in `protocols` during
     /// [`Directory.Open`], 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
     /// [`NodeProtocolKinds`].
     ///
     /// This is a special case of [`fuchsia.unknown/Queryable.Query`] +
     /// inherent `Describe` methods on the specific protocols. It exists as
     /// an optimization to avoid an additional round trip.
     @selector("fuchsia.io/Node.OnRepresentation")
     -> OnRepresentation(resource struct {
         // TODO(https://fxbug.dev/105837): Remove the outer struct when fidlgen_go is fixed.
         payload @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 [`NodeProtocolKinds.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 [`NodeProtocolKinds.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 [`NodeProtocolKinds.FILE`].
             3: file FileInfo;
         };
     });

     // TODO(https://fxbug.dev/77623): uncomment and implement.

     // /// Acquires a token which can be used to identify this connection at a later point in
     // /// time. The token will remain valid for as long as the connection requesting the token
     // /// remains open.
     // ///
     // /// This method does not require any rights. Note that the token identifies
     // /// the connection, hence carries the rights information on this connection.
     // @selector("fuchsia.io/Node.GetToken")
     // GetToken2() -> (resource struct {
     //     token Token;
     // }) error zx.status;

     /// Acquires information about the connection.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io/Node.GetConnectionInfo")
     GetConnectionInfo() -> (ConnectionInfo);

     /// Acquires information about the node.
     ///
     /// The attributes of a node should be stable, independent of the
     /// specific protocol used to access it.
     ///
     /// If a particular attribute is not applicable or not supported,
     /// filesystems should leave the corresponding field absent.
     ///
     /// + `query` a bit-mask specifying which attributes to fetch. The server
     ///   should not return more than necessary.
     /// - `attributes` the returned attributes.
     ///
     /// This method requires the [`Rights.GET_ATTRIBUTES`] right.
     @transitional
     @selector("fuchsia.io/Node.GetAttributes")
     GetAttributes(struct {
         /// Set the corresponding bit to one to query that particular attribute.
         ///
         /// The elements here correspond one-to-one with [`NodeAttributes`].
         query @generated_name("NodeAttributesQuery") strict bits : uint64 {
             /// Requests [`NodeAttributes.protocols`].
             PROTOCOLS = 0x1;

             /// Requests [`NodeAttributes.abilities`].
             ABILITIES = 0x2;

             /// Requests [`NodeAttributes.content_size`].
             CONTENT_SIZE = 0x4;

             /// Requests [`NodeAttributes.storage_size`].
             STORAGE_SIZE = 0x8;

             /// Requests [`NodeAttributes.link_count`].
             LINK_COUNT = 0x10;

             /// Requests [`NodeAttributes.id`].
             ID = 0x20;

             /// Requests [`NodeAttributes.creation_time`].
             CREATION_TIME = 0x40;

             /// Requests [`NodeAttributes.modification_time`].
             MODIFICATION_TIME = 0x80;
         };
     }) -> (@generated_name("NodeAttributes2") struct {
         // TODO(https://fxbug.dev/47480): fostr does not escape C++ keywords.
         // Drop the `_attributes` suffixes when fostr is fixed or retired.
         mutable_attributes MutableNodeAttributes;
         immutable_attributes @generated_name("ImmutableNodeAttributes") table {
             /// Describes the kinds of representations supported by the node.
             /// Note: This is not the result of the connection-time negotiation,
             /// which is conveyed via `representation`.
             1: protocols NodeProtocolKinds;

             /// Describes the kinds of operations supported by the node.
             /// Note: This is distinct from the rights used at connection time.
             2: abilities Abilities;

             /// Node size, in bytes.
             3: content_size uint64;

             /// Space needed to store the node (possibly larger than size), in bytes.
             4: storage_size uint64;

             /// Number of hard links to the node. It must be at least one.
             5: link_count uint64;

             /// An ID for the node. See [`Id`].
             /// This `id` should be unique among all entries of a directory.
             6: id Id;
         };
     }) error zx.status;

     /// Updates information about the node.
     ///
     /// + `attributes` the presence of a table field in `attributes` indicates
     /// the intent to update the corresponding attribute.
     ///
     /// This method requires the [`Rights.UPDATE_ATTRIBUTES`] right.
     @transitional
     @selector("fuchsia.io/Node.UpdateAttributes")
     UpdateAttributes(MutableNodeAttributes) -> (struct {}) error zx.status;

     /// Synchronizes updates to the node to the underlying media, if it exists.
     ///
     /// This method will return when the filesystem server has flushed the
     /// relevant updates to the underlying media, but does not guarantee the
     /// underlying media has persisted the information, nor that any information
     /// is committed to hardware. Clients may use `Sync` to ensure ordering
     /// between operations.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io/Node.Sync")
     Sync() -> (struct {}) error zx.status;
 };
	// 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.unknown;
	using zx;

	type MutableNodeAttributes = table {
	/// Time of creation in nanoseconds since the Unix epoch, UTC.
	1: creation_time uint64;

	/// Time of last modification in nanoseconds since the Unix epoch, UTC.
	2: modification_time uint64;
	};

	// TODO(https://fxbug.dev/105840): Inline this into its only reference when fidlgen_go is fixed.
	type ConnectionInfo = resource table {
	/// 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`].
	1: rights Rights;
	};

	// TODO(https://fxbug.dev/105608): Use a generated constant.
	const NODE_PROTOCOL_NAME string = "fuchsia.io/Node";

	/// Node defines the minimal protocol for entities which can be accessed
	/// in a filesystem.
	protocol Node2 {
	@available(added=9)
	compose fuchsia.unknown.Closeable;
	@available(added=9)
	compose fuchsia.unknown.Queryable;

	/// Creates another connection to the same node.
	///
	/// + `object_request` is the server end of a channel created for the new
	/// connection. The caller may proceed to send messages on the
	/// corresponding client end right away.
	@transitional
	@selector("fuchsia.io/Node.Reopen")
	Reopen(resource struct {
	/// Requests rights on the new connection according to the specified rules.
	///
	/// If absent, inherits the rights from the connection where the call
	/// is made.
	rights_request box<RightsRequest>;
	object_request zx.handle:CHANNEL;
	});

	/// Terminates the connection to the node.
	///
	/// After calling `Close`, the client must not send any other requests.
	/// Servers, after sending the status response, should close the connection
	/// regardless of status and without sending an epitaph.
	///
	/// Closing the client end of the channel should be semantically equivalent
	/// to calling `Close` without knowing when the close has completed or its
	/// status.
	///
	/// This method does not require any rights.
	@available(removed=9)
	@selector("fuchsia.io/Node.Close")
	Close() -> (struct {}) error zx.status;

	/// An event produced eagerly by the server if requested by
	/// [`NodeFlags.GET_REPRESENTATION`]. This event will be the first message
	/// from the server, and is sent exactly once.
	///
	/// 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.
	///
	/// If the client specified more than one protocol in `protocols` during
	/// [`Directory.Open`], 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
	/// [`NodeProtocolKinds`].
	///
	/// This is a special case of [`fuchsia.unknown/Queryable.Query`] +
	/// inherent `Describe` methods on the specific protocols. It exists as
	/// an optimization to avoid an additional round trip.
	@selector("fuchsia.io/Node.OnRepresentation")
	-> OnRepresentation(resource struct {
	// TODO(https://fxbug.dev/105837): Remove the outer struct when fidlgen_go is fixed.
	payload @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 [`NodeProtocolKinds.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 [`NodeProtocolKinds.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 [`NodeProtocolKinds.FILE`].
	3: file FileInfo;
	};
	});

	// TODO(https://fxbug.dev/77623): uncomment and implement.

	// /// Acquires a token which can be used to identify this connection at a later point in
	// /// time. The token will remain valid for as long as the connection requesting the token
	// /// remains open.
	// ///
	// /// This method does not require any rights. Note that the token identifies
	// /// the connection, hence carries the rights information on this connection.
	// @selector("fuchsia.io/Node.GetToken")
	// GetToken2() -> (resource struct {
	// token Token;
	// }) error zx.status;

	/// Acquires information about the connection.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io/Node.GetConnectionInfo")
	GetConnectionInfo() -> (ConnectionInfo);

	/// Acquires information about the node.
	///
	/// The attributes of a node should be stable, independent of the
	/// specific protocol used to access it.
	///
	/// If a particular attribute is not applicable or not supported,
	/// filesystems should leave the corresponding field absent.
	///
	/// + `query` a bit-mask specifying which attributes to fetch. The server
	/// should not return more than necessary.
	/// - `attributes` the returned attributes.
	///
	/// This method requires the [`Rights.GET_ATTRIBUTES`] right.
	@transitional
	@selector("fuchsia.io/Node.GetAttributes")
	GetAttributes(struct {
	/// Set the corresponding bit to one to query that particular attribute.
	///
	/// The elements here correspond one-to-one with [`NodeAttributes`].
	query @generated_name("NodeAttributesQuery") strict bits : uint64 {
	/// Requests [`NodeAttributes.protocols`].
	PROTOCOLS = 0x1;

	/// Requests [`NodeAttributes.abilities`].
	ABILITIES = 0x2;

	/// Requests [`NodeAttributes.content_size`].
	CONTENT_SIZE = 0x4;

	/// Requests [`NodeAttributes.storage_size`].
	STORAGE_SIZE = 0x8;

	/// Requests [`NodeAttributes.link_count`].
	LINK_COUNT = 0x10;

	/// Requests [`NodeAttributes.id`].
	ID = 0x20;

	/// Requests [`NodeAttributes.creation_time`].
	CREATION_TIME = 0x40;

	/// Requests [`NodeAttributes.modification_time`].
	MODIFICATION_TIME = 0x80;
	};
	}) -> (@generated_name("NodeAttributes2") struct {
	// TODO(https://fxbug.dev/47480): fostr does not escape C++ keywords.
	// Drop the `_attributes` suffixes when fostr is fixed or retired.
	mutable_attributes MutableNodeAttributes;
	immutable_attributes @generated_name("ImmutableNodeAttributes") table {
	/// Describes the kinds of representations supported by the node.
	/// Note: This is not the result of the connection-time negotiation,
	/// which is conveyed via `representation`.
	1: protocols NodeProtocolKinds;

	/// Describes the kinds of operations supported by the node.
	/// Note: This is distinct from the rights used at connection time.
	2: abilities Abilities;

	/// Node size, in bytes.
	3: content_size uint64;

	/// Space needed to store the node (possibly larger than size), in bytes.
	4: storage_size uint64;

	/// Number of hard links to the node. It must be at least one.
	5: link_count uint64;

	/// An ID for the node. See [`Id`].
	/// This `id` should be unique among all entries of a directory.
	6: id Id;
	};
	}) error zx.status;

	/// Updates information about the node.
	///
	/// + `attributes` the presence of a table field in `attributes` indicates
	/// the intent to update the corresponding attribute.
	///
	/// This method requires the [`Rights.UPDATE_ATTRIBUTES`] right.
	@transitional
	@selector("fuchsia.io/Node.UpdateAttributes")
	UpdateAttributes(MutableNodeAttributes) -> (struct {}) error zx.status;

	/// Synchronizes updates to the node to the underlying media, if it exists.
	///
	/// This method will return when the filesystem server has flushed the
	/// relevant updates to the underlying media, but does not guarantee the
	/// underlying media has persisted the information, nor that any information
	/// is committed to hardware. Clients may use `Sync` to ensure ordering
	/// between operations.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io/Node.Sync")
	Sync() -> (struct {}) error zx.status;
	};