sdk/fidl/fuchsia.io/node.fidl - fuchsia - Git at Google

 // Copyright 2018 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;

 /// The fields of 'attributes' which are used to update the Node are indicated
 /// by the 'flags' argument.
 type NodeAttributeFlags = strict bits : uint32 {
     CREATION_TIME = 0x00000001;
     MODIFICATION_TIME = 0x00000002;
 };

 /// Bits reserved for posix protections. Native fuchsia filesystems
 /// are not required to set bits contained within `MODE_PROTECTION_MASK`,
 /// but filesystems that wish to do so may refer to sys/stat.h for their
 /// definitions.
 const MODE_PROTECTION_MASK uint32 = 0x00FFF;

 // Chosen to match S_IFDIR.
 const MODE_TYPE_DIRECTORY uint32 = 0x04000;
 // Chosen to match S_IFBLK.
 const MODE_TYPE_BLOCK_DEVICE uint32 = 0x06000;
 // Chosen to match S_IFREG.
 const MODE_TYPE_FILE uint32 = 0x08000;
 // Chosen to match S_IFLNK.
 @available(added=HEAD)
 const MODE_TYPE_SYMLINK uint32 = 0x0A000;
 // Chosen arbitrarily.
 const MODE_TYPE_SERVICE uint32 = 0x10000;

 /// Bits indicating node type. The canonical mechanism to check
 /// for a node type is to take 'mode', bitwise AND it with the
 /// `MODE_TYPE_MASK`, and check exact equality against a mode type.
 const MODE_TYPE_MASK uint32 = 0xFF000;

 /// NodeAttributes defines generic information about a filesystem node.
 type NodeAttributes = struct {
     /// Protection bits and node type information describe in 'mode'.
     mode uint32;
     /// A filesystem-unique ID.
     id uint64;
     /// Node size, in bytes.
     content_size uint64;
     /// Space needed to store node (possibly larger than size), in bytes.
     storage_size uint64;
     /// Hard link count.
     link_count uint64;
     /// Time of creation (may be updated manually after creation) in ns since Unix epoch, UTC.
     creation_time uint64;
     /// Time of last modification in ns since Unix epoch, UTC.
     modification_time uint64;
 };

 const MAX_FS_NAME_BUFFER uint64 = 32;

 closed protocol Node {
     compose Node1;
     compose Node2;
 };

 /// Node defines the minimal interface for entities which can be accessed in a filesystem.
 closed protocol Node1 {
     /// Create another connection to the same remote object.
     ///
     /// `flags` may be any of:
     ///
     /// - `OpenFlags.RIGHT_*`
     /// - `OpenFlags.APPEND`
     /// - `OpenFlags.DESCRIBE`
     /// - `OpenFlags.CLONE_SAME_RIGHTS`
     ///
     /// All other flags are ignored.
     ///
     /// The `OpenFlags.RIGHT_*` bits in `flags` request corresponding rights over the resulting
     /// cloned object.
     /// The cloned object must have rights less than or equal to the original object, otherwise
     /// returns `ZX_ERR_ACCESS_DENIED`.
     /// Alternatively, pass `OpenFlags.CLONE_SAME_RIGHTS` to inherit the rights on the source connection.
     /// It is invalid to pass any of the `OpenFlags.RIGHT_*` flags together with
     /// `OpenFlags.CLONE_SAME_RIGHTS`.
     @selector("fuchsia.io1/Node.Clone")
     strict Clone(resource struct {
         flags OpenFlags;
         object server_end:Node;
     });

     /// An event produced eagerly by a FIDL server if requested by `OpenFlags.DESCRIBE`.
     ///
     /// Indicates the success or failure of the open operation, and optionally describes the
     /// object. If the status is `ZX_OK`, `info` contains descriptive information about the object
     /// (the same as would be returned by `Describe`).
     @selector("fuchsia.io1/Node.OnOpen")
     strict -> OnOpen(resource struct {
         s zx.Status;
         info @generated_name("NodeInfoDeprecated") strict resource union {
             /// No protocol information was supplied by the connection.
             1: service struct {};

             /// The connection composes [`File`].
             2: file @generated_name("FileObject") resource struct {
                 /// 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.
                 ///
                 /// The "`FILE_SIGNAL_`" values may be observed on this event.
                 event zx.Handle:<EVENT, optional>;

                 /// A placeholder for future stream support.
                 ///
                 /// Currently, servers are required not to send a handle in this field.
                 stream zx.Handle:<STREAM, optional>;
             };

             /// The connection composes [`Directory`].
             3: directory @generated_name("DirectoryObject") struct {};

             /// The connection composes ['Symlink'].
             @available(added=18)
             4: symlink @generated_name("SymlinkObject") struct {
                 target SymlinkTarget;
             };
         }:optional;
     });

     /// Acquires information about the node.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io1/Node.GetAttr")
     strict GetAttr() -> (struct {
         s zx.Status;
         attributes NodeAttributes;
     });

     /// Updates information about the node.
     ///
     /// This method requires following rights: `OpenFlags.RIGHT_WRITABLE`, otherwise returns
     /// `ZX_ERR_BAD_HANDLE`.
     @selector("fuchsia.io1/Node.SetAttr")
     strict SetAttr(struct {
         flags NodeAttributeFlags;
         attributes NodeAttributes;
     }) -> (struct {
         s zx.Status;
     });

     /// Acquires the `Directory.Open` rights and flags used to access this file.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io1/Node.NodeGetFlags")
     strict GetFlags() -> (struct {
         s zx.Status;
         flags OpenFlags;
     });

     /// Changes the `Directory.Open` flags used to access the file.
     /// Supported flags which can be turned on / off:
     /// - `OpenFlags.APPEND`
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io1/Node.NodeSetFlags")
     strict SetFlags(struct {
         flags OpenFlags;
     }) -> (struct {
         s zx.Status;
     });

     /// Query the filesystem for filesystem-specific information.
     @selector("fuchsia.io.admin/DirectoryAdmin.QueryFilesystem")
     strict QueryFilesystem() -> (struct {
         s zx.Status;
         info box<@generated_name("FilesystemInfo") struct {
             /// The number of data bytes which may be stored in a filesystem. This does not count
             /// metadata or other filesystem overhead like block rounding.
             total_bytes uint64;

             /// The number of data bytes which are in use by the filesystem. This does not count
             /// metadata or other filesystem overhead like block rounding.
             used_bytes uint64;

             /// The number of nodes which may be stored in the filesystem.
             total_nodes uint64;

             /// The number of nodes used by the filesystem.
             used_nodes uint64;

             /// The amount of additional space which may be allocated from the underlying volume
             /// manager. If unsupported or there is no space for the filesystem to grow, this will
             /// be zero.
             free_shared_pool_bytes uint64;

             /// A unique identifier for this filesystem instance. Will not be preserved across
             /// reboots.
             ///
             /// Implementors should create a kernel object (normally an event) and use its koid for
             /// the filesystem ID. This koid guarantees uniqueness in the system.
             fs_id uint64;

             /// The size in bytes of a single filesystem block.
             block_size uint32;

             /// The maximum length of a filesystem name.
             max_filename_size uint32;

             /// A unique identifier for the type of the underlying filesystem.
             fs_type uint32;

             padding uint32;

             // TODO: Replace this field with a string when supported by the "Simple" interface. At
             // the moment, name is a fixed-size, null-terminated buffer.
             name array<int8, MAX_FS_NAME_BUFFER>;
         }>;
     });
 };
	// Copyright 2018 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;

	/// The fields of 'attributes' which are used to update the Node are indicated
	/// by the 'flags' argument.
	type NodeAttributeFlags = strict bits : uint32 {
	CREATION_TIME = 0x00000001;
	MODIFICATION_TIME = 0x00000002;
	};

	/// Bits reserved for posix protections. Native fuchsia filesystems
	/// are not required to set bits contained within `MODE_PROTECTION_MASK`,
	/// but filesystems that wish to do so may refer to sys/stat.h for their
	/// definitions.
	const MODE_PROTECTION_MASK uint32 = 0x00FFF;

	// Chosen to match S_IFDIR.
	const MODE_TYPE_DIRECTORY uint32 = 0x04000;
	// Chosen to match S_IFBLK.
	const MODE_TYPE_BLOCK_DEVICE uint32 = 0x06000;
	// Chosen to match S_IFREG.
	const MODE_TYPE_FILE uint32 = 0x08000;
	// Chosen to match S_IFLNK.
	@available(added=HEAD)
	const MODE_TYPE_SYMLINK uint32 = 0x0A000;
	// Chosen arbitrarily.
	const MODE_TYPE_SERVICE uint32 = 0x10000;

	/// Bits indicating node type. The canonical mechanism to check
	/// for a node type is to take 'mode', bitwise AND it with the
	/// `MODE_TYPE_MASK`, and check exact equality against a mode type.
	const MODE_TYPE_MASK uint32 = 0xFF000;

	/// NodeAttributes defines generic information about a filesystem node.
	type NodeAttributes = struct {
	/// Protection bits and node type information describe in 'mode'.
	mode uint32;
	/// A filesystem-unique ID.
	id uint64;
	/// Node size, in bytes.
	content_size uint64;
	/// Space needed to store node (possibly larger than size), in bytes.
	storage_size uint64;
	/// Hard link count.
	link_count uint64;
	/// Time of creation (may be updated manually after creation) in ns since Unix epoch, UTC.
	creation_time uint64;
	/// Time of last modification in ns since Unix epoch, UTC.
	modification_time uint64;
	};

	const MAX_FS_NAME_BUFFER uint64 = 32;

	closed protocol Node {
	compose Node1;
	compose Node2;
	};

	/// Node defines the minimal interface for entities which can be accessed in a filesystem.
	closed protocol Node1 {
	/// Create another connection to the same remote object.
	///
	/// `flags` may be any of:
	///
	/// - `OpenFlags.RIGHT_*`
	/// - `OpenFlags.APPEND`
	/// - `OpenFlags.DESCRIBE`
	/// - `OpenFlags.CLONE_SAME_RIGHTS`
	///
	/// All other flags are ignored.
	///
	/// The `OpenFlags.RIGHT_*` bits in `flags` request corresponding rights over the resulting
	/// cloned object.
	/// The cloned object must have rights less than or equal to the original object, otherwise
	/// returns `ZX_ERR_ACCESS_DENIED`.
	/// Alternatively, pass `OpenFlags.CLONE_SAME_RIGHTS` to inherit the rights on the source connection.
	/// It is invalid to pass any of the `OpenFlags.RIGHT_*` flags together with
	/// `OpenFlags.CLONE_SAME_RIGHTS`.
	@selector("fuchsia.io1/Node.Clone")
	strict Clone(resource struct {
	flags OpenFlags;
	object server_end:Node;
	});

	/// An event produced eagerly by a FIDL server if requested by `OpenFlags.DESCRIBE`.
	///
	/// Indicates the success or failure of the open operation, and optionally describes the
	/// object. If the status is `ZX_OK`, `info` contains descriptive information about the object
	/// (the same as would be returned by `Describe`).
	@selector("fuchsia.io1/Node.OnOpen")
	strict -> OnOpen(resource struct {
	s zx.Status;
	info @generated_name("NodeInfoDeprecated") strict resource union {
	/// No protocol information was supplied by the connection.
	1: service struct {};

	/// The connection composes [`File`].
	2: file @generated_name("FileObject") resource struct {
	/// 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.
	///
	/// The "`FILE_SIGNAL_`" values may be observed on this event.
	event zx.Handle:<EVENT, optional>;

	/// A placeholder for future stream support.
	///
	/// Currently, servers are required not to send a handle in this field.
	stream zx.Handle:<STREAM, optional>;
	};

	/// The connection composes [`Directory`].
	3: directory @generated_name("DirectoryObject") struct {};

	/// The connection composes ['Symlink'].
	@available(added=18)
	4: symlink @generated_name("SymlinkObject") struct {
	target SymlinkTarget;
	};
	}:optional;
	});

	/// Acquires information about the node.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io1/Node.GetAttr")
	strict GetAttr() -> (struct {
	s zx.Status;
	attributes NodeAttributes;
	});

	/// Updates information about the node.
	///
	/// This method requires following rights: `OpenFlags.RIGHT_WRITABLE`, otherwise returns
	/// `ZX_ERR_BAD_HANDLE`.
	@selector("fuchsia.io1/Node.SetAttr")
	strict SetAttr(struct {
	flags NodeAttributeFlags;
	attributes NodeAttributes;
	}) -> (struct {
	s zx.Status;
	});

	/// Acquires the `Directory.Open` rights and flags used to access this file.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io1/Node.NodeGetFlags")
	strict GetFlags() -> (struct {
	s zx.Status;
	flags OpenFlags;
	});

	/// Changes the `Directory.Open` flags used to access the file.
	/// Supported flags which can be turned on / off:
	/// - `OpenFlags.APPEND`
	///
	/// This method does not require any rights.
	@selector("fuchsia.io1/Node.NodeSetFlags")
	strict SetFlags(struct {
	flags OpenFlags;
	}) -> (struct {
	s zx.Status;
	});

	/// Query the filesystem for filesystem-specific information.
	@selector("fuchsia.io.admin/DirectoryAdmin.QueryFilesystem")
	strict QueryFilesystem() -> (struct {
	s zx.Status;
	info box<@generated_name("FilesystemInfo") struct {
	/// The number of data bytes which may be stored in a filesystem. This does not count
	/// metadata or other filesystem overhead like block rounding.
	total_bytes uint64;

	/// The number of data bytes which are in use by the filesystem. This does not count
	/// metadata or other filesystem overhead like block rounding.
	used_bytes uint64;

	/// The number of nodes which may be stored in the filesystem.
	total_nodes uint64;

	/// The number of nodes used by the filesystem.
	used_nodes uint64;

	/// The amount of additional space which may be allocated from the underlying volume
	/// manager. If unsupported or there is no space for the filesystem to grow, this will
	/// be zero.
	free_shared_pool_bytes uint64;

	/// A unique identifier for this filesystem instance. Will not be preserved across
	/// reboots.
	///
	/// Implementors should create a kernel object (normally an event) and use its koid for
	/// the filesystem ID. This koid guarantees uniqueness in the system.
	fs_id uint64;

	/// The size in bytes of a single filesystem block.
	block_size uint32;

	/// The maximum length of a filesystem name.
	max_filename_size uint32;

	/// A unique identifier for the type of the underlying filesystem.
	fs_type uint32;

	padding uint32;

	// TODO: Replace this field with a string when supported by the "Simple" interface. At
	// the moment, name is a fixed-size, null-terminated buffer.
	name array<int8, MAX_FS_NAME_BUFFER>;
	}>;
	});
	};