| // 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.io2; |
| |
| using zx; |
| |
| /// A [`fuchsia.io2/Node`] that is capable of containing other nodes. |
| protocol Directory { |
| compose Node; |
| |
| /// Opens or creates a new node relative to this directory node. |
| /// |
| /// + `path` identifies the node to open. |
| /// If `path` contains multiple segments, then the directory is traversed, |
| /// one segment at a time, relative to the directory represented by this |
| /// connection. |
| /// See [`fuchsia.io2/Path`] for what constitutes a valid path. |
| /// To open another connection to the current directory, use |
| /// [`fuchsia.io2/Node.Reopen`] instead. |
| /// + `mode` controls whether to open existing/create new etc. |
| /// + `options` additional options applicable to both `Open` and `Reopen`, |
| /// including negotiating protocol and restricting rights. |
| /// See [`fuchsia.io2/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. |
| /// |
| /// This method requires the following rights on the current connection: |
| /// |
| /// * [`Rights.ENUMERATE`] |
| /// * [`Rights.TRAVERSE`] |
| /// |
| /// Errors are presented as an epitaph on the `object_request` channel. |
| /// |
| /// * error `ZX_ERR_ACCESS_DENIED` if the requested rights exceeds |
| /// what is allowed. |
| /// * error `ZX_ERR_BAD_PATH` if `path` is invalid. |
| Open(Path path, |
| OpenMode mode, |
| ConnectionOptions options, |
| zx.handle:CHANNEL object_request); |
| |
| /// Adds a new inotify filter for an object relative to this directory object. |
| /// |
| /// + 'filters` is a mask of different inotify events that need to be watched by the server |
| /// for a specific file/directory. |
| /// |
| /// + `path` may contain multiple segments, separated by "/" characters, |
| /// and should never be empty; i.e., "" is an invalid path. Paths should not contain |
| /// a leading "/". |
| /// |
| /// +`watch_descriptor` is client assigned value to identify a filter. |
| /// Server shouldn't trust the client-assigned watch_descriptor. They should just send it |
| /// back to the client in the socket. |
| /// This value is not used by server, but it is returned back as part of InotifyEvent, |
| /// to help the client correlate filters with events on these filters. |
| /// |
| /// + `socket` is shared between different filter objects i.e every new filter will |
| /// have a different server end of the socket and there will be a single client end per |
| /// inotify instance on inotify init. |
| /// |
| /// + `controller` is the server end of a channel and is per filter in the vnode so that |
| /// we can remove the specific inotify filter when the controller is closed by the server |
| /// or the client. |
| /// |
| /// Errors are presented as an epitaph on the `controller` channel. |
| /// * error `ZX_ERR_ACCESS_DENIED` if the requested rights exceeds |
| /// what is allowed. |
| /// * error `ZX_ERR_BAD_PATH` if `path` is invalid. |
| AddInotifyFilter(Path path, InotifyWatchMask filters, uint32 watch_descriptor, |
| zx.handle:SOCKET socket) -> (); |
| |
| /// Removes a child node from the this directory's list of entries. |
| /// |
| /// Note: this does not guarantee that the underlying object is destroyed. |
| /// Although the link will be removed from the containing directory, |
| /// objects with multiple references (such as files which are still open) |
| /// will not actually be destroyed until all references are closed. |
| /// |
| /// * error `ZX_ERR_ACCESS_DENIED` if the connection does not have |
| /// [`Rights.WRITE_BYTES`]. |
| /// * error `ZX_ERR_NOT_SUPPORTED` if the underlying filesystem does not |
| /// support writing. |
| /// * error `ZX_ERR_BAD_PATH` if `name` is invalid. |
| /// * error `ZX_ERR_NOT_EMPTY` if `name` refers to a non-empty directory. |
| /// * error `ZX_ERR_UNAVAILABLE` if `name` refers to a mount point, |
| /// containing a remote channel. |
| /// * error `ZX_ERR_NOT_DIR` if the options requested a directory but something other than a |
| /// directory was found. |
| /// |
| /// Other errors may be returned for filesystem-specific reasons. |
| /// |
| /// This method requires the following rights: |
| /// |
| /// * [`Rights.ENUMERATE`] |
| /// * [`Rights.MODIFY_DIRECTORY`] |
| Unlink(Path path) -> () error zx.status; |
| [Transitional] |
| Unlink2(Name name, UnlinkOptions options) -> () error zx.status; |
| |
| /// Initiates a directory listing operation over the input channel, |
| /// starting at seek offset 0. |
| /// |
| /// This method requires the [`Rights.ENUMERATE`] right. If this right is |
| /// absent, `iterator` will be closed with a `ZX_ERR_ACCESS_DENIED` epitaph. |
| Enumerate(DirectoryEnumerateOptions options, |
| request<DirectoryIterator> iterator); |
| |
| /// Renames a node named `src` to the name `dst`, in a directory represented |
| /// by `dst_parent_token`. |
| /// |
| /// `src` and `dst` must be valid node names. |
| /// See [`fuchsia.io2/Name`] for what constitutes a valid name. |
| /// |
| /// This method requires the following rights on both the current |
| /// connection, and the connection identified by `dst_parent_token`: |
| /// |
| /// * [`Rights.ENUMERATE`] |
| /// * [`Rights.MODIFY_DIRECTORY`] |
| /// |
| /// * error `ZX_ERR_INVALID_ARGS` if `src` or `dst` is invalid. |
| Rename(Name src, |
| Token dst_parent_token, |
| Name dst) -> () error zx.status; |
| |
| /// Creates a link to a node named `src` by the name `dst`, |
| /// in a directory represented by `dst_parent_token`. |
| /// |
| /// Directories cannot be linked, to prevent reference cycles. |
| /// |
| /// `src` and `dst` must be valid node names. |
| /// See [`fuchsia.io2/Name`] for what constitutes a valid name. |
| /// |
| /// This method requires the following rights on both the current |
| /// connection, and the connection identified by `dst_parent_token`: |
| /// |
| /// * [`Rights.ENUMERATE`] |
| /// * [`Rights.MODIFY_DIRECTORY`] |
| /// |
| /// * error `ZX_ERR_INVALID_ARGS` if `src` or `dst` is invalid. |
| /// * error `ZX_ERR_INVALID_ARGS` if `src` is a directory. |
| Link(Name src, |
| Token dst_parent_token, |
| Name dst) -> () error zx.status; |
| |
| /// Watches a directory, monitoring events for children being added or |
| /// removed on the server end of the `watcher` channel. |
| /// |
| /// Mask specifies a bit mask of events to observe. |
| /// |
| /// This method requires the [`Rights.ENUMERATE`] right. If this right is |
| /// absent, `watcher` will be closed with a `ZX_ERR_ACCESS_DENIED` epitaph. |
| Watch(DirectoryWatchMask mask, |
| DirectoryWatchOptions options, |
| request<DirectoryWatcher> watcher); |
| }; |
| |
| /// Options related to node creation during [`Directory.Open`]. |
| enum OpenMode : uint32 { |
| /// Only succeed if the object exists. |
| OPEN_EXISTING = 1; |
| |
| /// Create the object if it does not exist, otherwise open existing. |
| /// The check and the creation are performed in one atomic step. |
| MAYBE_CREATE = 2; |
| |
| /// Assert that the object does not exist, then create it. |
| /// The assertion and creation are performed in one atomic step. |
| ALWAYS_CREATE = 3; |
| |
| /// If the object is a mount point, open the local directory |
| /// instead of forwarding the request. The object must be a directory. |
| /// |
| /// This option implies the behavior of `OPEN_EXISTING`. |
| [Deprecated = "Mount points will be replaced by components."] |
| OPEN_MOUNT_POINT = 0x10000000; |
| }; |
| |
| /// Auxiliary data for the directory representation of a node. |
| /// The selection of this variant in [`Representation`] implies that the |
| /// connection speaks the [`fuchsia.io2/Directory`] protocol. |
| table DirectoryInfo { |
| }; |
| |
| /// Options for [`Directory.Unlink`]. |
| table UnlinkOptions { |
| 1: UnlinkFlags flags; |
| }; |
| |
| /// Flags for [`Directory.Unlink`]. |
| bits UnlinkFlags : uint64 { |
| /// If set, the unlink will fail (with ZX_ERR_NOT_DIR) if the object is not a directory. |
| MUST_BE_DIRECTORY = 0x01; |
| }; |