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