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;

 /// Connection information.
 ///
 /// Refer to [`Node.Describe`] and [`Node.OnOpen`] for usage.
 type NodeInfo = 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 [`Pipe`].
     4: pipe @generated_name("PipeObject") resource struct {
         socket zx.handle:SOCKET;
     };

     /// The connection composes [`File`]. Its implementation is backed by a VMO.
     5: vmofile resource struct {
         /// The VMO which backs this file.
         vmo zx.handle:VMO;
         /// The index into `vmo` which represents the first byte of the file.
         offset uint64;
         /// The number of bytes, starting at `offset`, which may be used to represent this file.
         length uint64;
     };
     6: device resource struct {
         /// An optional event which transmits information about a device's state.
         ///
         /// The "`DEVICE_SIGNAL_`" values may be observed on this event.
         unused zx.handle:<EVENTPAIR, optional>;
     };
     7: tty resource struct {
         event zx.handle:<EVENTPAIR, optional>;
     };

     8: reserved;

     /// The connection composes [`fuchsia.posix.socket/SynchronousDatagramSocket`].
     9: synchronous_datagram_socket resource struct {
         /// See [`fuchsia.posix.socket.SynchronousDatagramSocket`] for details.
         event zx.handle:<EVENTPAIR, zx.rights.TRANSFER | zx.rights.WAIT>;
     };

     /// The connection composes [`fuchsia.posix.socket/StreamSocket`].
    10: stream_socket resource struct {
         socket zx.handle:<SOCKET, zx.rights.TRANSFER | zx.RIGHTS_IO | zx.rights.WAIT | zx.rights.INSPECT>;
     };

     /// The connection composes [`fuchsia.posix.socket.raw/Socket`].
    11: raw_socket resource struct {
         /// See [`fuchsia.posix.socket.raw.Socket`] for details.
         event zx.handle:<EVENTPAIR, zx.rights.TRANSFER | zx.rights.WAIT>;
     };

     /// The connection composes [`fuchsia.posix.socket.packet/Socket`].
    12: packet_socket resource struct {
         /// See [`fuchsia.posix.socket.packet.Socket`] for details.
         event zx.handle:<EVENTPAIR, zx.rights.TRANSFER | zx.rights.WAIT>;
     };

     /// The connection composes  [`fuchsia.posix.socket/DatagramSocket`].
    13: datagram_socket resource struct {
         /// See [`fuchsia.posix.socket.DatagramSocket`] for details.
         socket zx.handle:<SOCKET, zx.rights.TRANSFER | zx.RIGHTS_IO | zx.rights.WAIT | zx.rights.INSPECT>;
         /// Size of the buffer used to receive Tx metadata.
         tx_meta_buf_size uint64;
         /// Size of the buffer used to receive Rx metadata.
         rx_meta_buf_size uint64;
     };
 };

 /// 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;
 };

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

 protocol Node {
     compose Node1;
     compose Node2;
 };

 /// Node defines the minimal interface for entities which can be accessed in a filesystem.
 protocol Node1 {
     compose Node2;

     /// 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")
     Clone(resource struct {
         flags OpenFlags;
         object server_end:Node;
     });

     /// Returns extra information about the type of the object.
     /// If the `Describe` operation fails, the connection is closed.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io1/Node.Describe")
     Describe() -> (resource struct {
         info NodeInfo;
     });

     /// 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")
     -> OnOpen(resource struct {
         s zx.status;
         info NodeInfo:optional;
     });

     /// Acquires information about the node.
     ///
     /// This method does not require any rights.
     @selector("fuchsia.io1/Node.GetAttr")
     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")
     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")
     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")
     SetFlags(struct {
         flags OpenFlags;
     }) -> (struct {
         s zx.status;
     });

     /// Query the filesystem for filesystem-specific information.
     @selector("fuchsia.io.admin/DirectoryAdmin.QueryFilesystem")
     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;

	/// Connection information.
	///
	/// Refer to [`Node.Describe`] and [`Node.OnOpen`] for usage.
	type NodeInfo = 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 [`Pipe`].
	4: pipe @generated_name("PipeObject") resource struct {
	socket zx.handle:SOCKET;
	};

	/// The connection composes [`File`]. Its implementation is backed by a VMO.
	5: vmofile resource struct {
	/// The VMO which backs this file.
	vmo zx.handle:VMO;
	/// The index into `vmo` which represents the first byte of the file.
	offset uint64;
	/// The number of bytes, starting at `offset`, which may be used to represent this file.
	length uint64;
	};
	6: device resource struct {
	/// An optional event which transmits information about a device's state.
	///
	/// The "`DEVICE_SIGNAL_`" values may be observed on this event.
	unused zx.handle:<EVENTPAIR, optional>;
	};
	7: tty resource struct {
	event zx.handle:<EVENTPAIR, optional>;
	};

	8: reserved;

	/// The connection composes [`fuchsia.posix.socket/SynchronousDatagramSocket`].
	9: synchronous_datagram_socket resource struct {
	/// See [`fuchsia.posix.socket.SynchronousDatagramSocket`] for details.
	event zx.handle:<EVENTPAIR, zx.rights.TRANSFER \| zx.rights.WAIT>;
	};

	/// The connection composes [`fuchsia.posix.socket/StreamSocket`].
	10: stream_socket resource struct {
	socket zx.handle:<SOCKET, zx.rights.TRANSFER \| zx.RIGHTS_IO \| zx.rights.WAIT \| zx.rights.INSPECT>;
	};

	/// The connection composes [`fuchsia.posix.socket.raw/Socket`].
	11: raw_socket resource struct {
	/// See [`fuchsia.posix.socket.raw.Socket`] for details.
	event zx.handle:<EVENTPAIR, zx.rights.TRANSFER \| zx.rights.WAIT>;
	};

	/// The connection composes [`fuchsia.posix.socket.packet/Socket`].
	12: packet_socket resource struct {
	/// See [`fuchsia.posix.socket.packet.Socket`] for details.
	event zx.handle:<EVENTPAIR, zx.rights.TRANSFER \| zx.rights.WAIT>;
	};

	/// The connection composes [`fuchsia.posix.socket/DatagramSocket`].
	13: datagram_socket resource struct {
	/// See [`fuchsia.posix.socket.DatagramSocket`] for details.
	socket zx.handle:<SOCKET, zx.rights.TRANSFER \| zx.RIGHTS_IO \| zx.rights.WAIT \| zx.rights.INSPECT>;
	/// Size of the buffer used to receive Tx metadata.
	tx_meta_buf_size uint64;
	/// Size of the buffer used to receive Rx metadata.
	rx_meta_buf_size uint64;
	};
	};

	/// 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;
	};

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

	protocol Node {
	compose Node1;
	compose Node2;
	};

	/// Node defines the minimal interface for entities which can be accessed in a filesystem.
	protocol Node1 {
	compose Node2;

	/// 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")
	Clone(resource struct {
	flags OpenFlags;
	object server_end:Node;
	});

	/// Returns extra information about the type of the object.
	/// If the `Describe` operation fails, the connection is closed.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io1/Node.Describe")
	Describe() -> (resource struct {
	info NodeInfo;
	});

	/// 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")
	-> OnOpen(resource struct {
	s zx.status;
	info NodeInfo:optional;
	});

	/// Acquires information about the node.
	///
	/// This method does not require any rights.
	@selector("fuchsia.io1/Node.GetAttr")
	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")
	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")
	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")
	SetFlags(struct {
	flags OpenFlags;
	}) -> (struct {
	s zx.status;
	});

	/// Query the filesystem for filesystem-specific information.
	@selector("fuchsia.io.admin/DirectoryAdmin.QueryFilesystem")
	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>;
	}>;
	});
	};