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 zx;

 /// Objective information about a filesystem node.
 /// See [`Node.GetAttributes`] and [`Node.UpdateAttributes`].
 ///
 /// 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.
 type NodeAttributes2 = 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`.
     ///
     /// This attribute is read-only.
     1: protocols NodeProtocols;

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

     /// Node size, in bytes.
     ///
     /// This attribute is read-only.
     3: content_size uint64;

     /// Space needed to store the node (possibly larger than size), in bytes.
     ///
     /// This attribute is read-only.
     4: storage_size uint64;

     /// Number of hard links to the node. It must be at least one.
     ///
     /// This attribute is read-only.
     5: link_count uint64;

     /// Time of creation in nanoseconds since the Unix epoch, UTC.
     /// It may be updated manually after creation.
     6: creation_time uint64;

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

     /// An ID for the node. See [`Id`].
     /// This `id` should be unique among all entries of a directory.
     ///
     /// This attribute is read-only.
     8: id Id;
 };

 /// Node defines the minimal protocol for entities which can be accessed
 /// in a filesystem.
 protocol Node2 {
     /// Creates another connection to the same node.
     ///
     /// + `options` options applicable to both `Open` and `Reopen`,
     ///   including negotiating protocol and restricting rights.
     ///   See [`ConnectionOptions`].
     /// + `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.
     ///
     /// For files, the cloned connection and the original connection have
     /// independent seek offsets.
     @transitional
     @selector("fuchsia.io/Node.Reopen")
     Reopen(resource struct {
         options ConnectionOptions;
         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.
     @selector("fuchsia.io/Node.Close")
     Close() -> (struct {}) error zx.status;

     /// Returns extra connection information and auxiliary handles.
     ///
     /// + `query` specifies the fields in `ConnectionInfo` that the caller is
     ///   interested in.
     /// - `info` see [`ConnectionInfo`] for details on the fields.
     ///
     /// When all known bits in `query` are set, the return value matches
     /// the one from [`OnConnectionInfo`], as if the caller requested that event
     /// using [`ConnectionFlags.GET_CONNECTION_INFO`].
     ///
     /// If the `Describe` operation fails, the connection is closed with the
     /// associated error.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io/Node.Describe")
     Describe2(struct {
         query @generated_name("ConnectionInfoQuery") strict bits : uint64 {
             /// Requests [`ConnectionInfo.representation`].
             REPRESENTATION = 0x1;

             /// Requests [`ConnectionInfo.rights`].
             RIGHTS = 0x2;

             /// Requests [`ConnectionInfo.available_operations`].
             AVAILABLE_OPERATIONS = 0x4;
         };
     }) -> (resource struct {
         info ConnectionInfo;
     });

     /// An event produced eagerly by the server if requested by
     /// [`ConnectionFlags.GET_CONNECTION_INFO`]. This event will be the
     /// first message from the server, and is sent exactly once.
     ///
     /// - `info` See [`ConnectionInfo`] for details on the fields.
     ///   All members should be present.
     ///
     /// Different from [`fuchsia.io/OnOpen`], an error during open/reopen is
     /// always manifested as an epitaph.
     @selector("fuchsia.io/Node.OnConnectionInfo")
     -> OnConnectionInfo(resource struct {
         info ConnectionInfo;
     });

     // 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.
     // ///
     // /// 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 node.
     ///
     /// The attributes of a node should be stable, independent of the
     /// specific protocol used to access it.
     ///
     /// + `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.creation_time`].
             CREATION_TIME = 0x20;

             /// Requests [`NodeAttributes.modification_time`].
             MODIFICATION_TIME = 0x40;

             /// Requests [`NodeAttributes.id`].
             ID = 0x80;
         };
     }) -> (struct {
         attributes NodeAttributes2;
     }) 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(struct {
         attributes NodeAttributes2;
     }) -> (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 zx;

	/// Objective information about a filesystem node.
	/// See [`Node.GetAttributes`] and [`Node.UpdateAttributes`].
	///
	/// 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.
	type NodeAttributes2 = 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`.
	///
	/// This attribute is read-only.
	1: protocols NodeProtocols;

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

	/// Node size, in bytes.
	///
	/// This attribute is read-only.
	3: content_size uint64;

	/// Space needed to store the node (possibly larger than size), in bytes.
	///
	/// This attribute is read-only.
	4: storage_size uint64;

	/// Number of hard links to the node. It must be at least one.
	///
	/// This attribute is read-only.
	5: link_count uint64;

	/// Time of creation in nanoseconds since the Unix epoch, UTC.
	/// It may be updated manually after creation.
	6: creation_time uint64;

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

	/// An ID for the node. See [`Id`].
	/// This `id` should be unique among all entries of a directory.
	///
	/// This attribute is read-only.
	8: id Id;
	};

	/// Node defines the minimal protocol for entities which can be accessed
	/// in a filesystem.
	protocol Node2 {
	/// Creates another connection to the same node.
	///
	/// + `options` options applicable to both `Open` and `Reopen`,
	/// including negotiating protocol and restricting rights.
	/// See [`ConnectionOptions`].
	/// + `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.
	///
	/// For files, the cloned connection and the original connection have
	/// independent seek offsets.
	@transitional
	@selector("fuchsia.io/Node.Reopen")
	Reopen(resource struct {
	options ConnectionOptions;
	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.
	@selector("fuchsia.io/Node.Close")
	Close() -> (struct {}) error zx.status;

	/// Returns extra connection information and auxiliary handles.
	///
	/// + `query` specifies the fields in `ConnectionInfo` that the caller is
	/// interested in.
	/// - `info` see [`ConnectionInfo`] for details on the fields.
	///
	/// When all known bits in `query` are set, the return value matches
	/// the one from [`OnConnectionInfo`], as if the caller requested that event
	/// using [`ConnectionFlags.GET_CONNECTION_INFO`].
	///
	/// If the `Describe` operation fails, the connection is closed with the
	/// associated error.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io/Node.Describe")
	Describe2(struct {
	query @generated_name("ConnectionInfoQuery") strict bits : uint64 {
	/// Requests [`ConnectionInfo.representation`].
	REPRESENTATION = 0x1;

	/// Requests [`ConnectionInfo.rights`].
	RIGHTS = 0x2;

	/// Requests [`ConnectionInfo.available_operations`].
	AVAILABLE_OPERATIONS = 0x4;
	};
	}) -> (resource struct {
	info ConnectionInfo;
	});

	/// An event produced eagerly by the server if requested by
	/// [`ConnectionFlags.GET_CONNECTION_INFO`]. This event will be the
	/// first message from the server, and is sent exactly once.
	///
	/// - `info` See [`ConnectionInfo`] for details on the fields.
	/// All members should be present.
	///
	/// Different from [`fuchsia.io/OnOpen`], an error during open/reopen is
	/// always manifested as an epitaph.
	@selector("fuchsia.io/Node.OnConnectionInfo")
	-> OnConnectionInfo(resource struct {
	info ConnectionInfo;
	});

	// 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.
	// ///
	// /// 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 node.
	///
	/// The attributes of a node should be stable, independent of the
	/// specific protocol used to access it.
	///
	/// + `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.creation_time`].
	CREATION_TIME = 0x20;

	/// Requests [`NodeAttributes.modification_time`].
	MODIFICATION_TIME = 0x40;

	/// Requests [`NodeAttributes.id`].
	ID = 0x80;
	};
	}) -> (struct {
	attributes NodeAttributes2;
	}) 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(struct {
	attributes NodeAttributes2;
	}) -> (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;
	};