vfs/directory/
entry_container.rs

1// Copyright 2019 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! `EntryContainer` is a trait implemented by directories that allow manipulation of their
6//! content.
7
8use crate::directory::dirents_sink;
9use crate::directory::traversal_position::TraversalPosition;
10use crate::execution_scope::ExecutionScope;
11use crate::node::Node;
12use crate::object_request::ObjectRequestRef;
13#[cfg(any(fuchsia_api_level_at_least = "PLATFORM", not(fuchsia_api_level_at_least = "NEXT")))]
14use crate::object_request::ToObjectRequest as _;
15use crate::path::Path;
16use fidl::endpoints::ServerEnd;
17use fidl_fuchsia_io as fio;
18use futures::future::BoxFuture;
19use std::any::Any;
20use std::future::{Future, ready};
21use std::sync::Arc;
22use zx_status::Status;
23
24mod private {
25    use fidl_fuchsia_io as fio;
26
27    /// A type-preserving wrapper around [`fuchsia_async::Channel`].
28    #[derive(Debug)]
29    pub struct DirectoryWatcher {
30        channel: fuchsia_async::Channel,
31    }
32
33    impl DirectoryWatcher {
34        /// Provides access to the underlying channel.
35        pub fn channel(&self) -> &fuchsia_async::Channel {
36            let Self { channel } = self;
37            channel
38        }
39    }
40
41    impl From<fidl::endpoints::ServerEnd<fio::DirectoryWatcherMarker>> for DirectoryWatcher {
42        fn from(server_end: fidl::endpoints::ServerEnd<fio::DirectoryWatcherMarker>) -> Self {
43            let channel = fuchsia_async::Channel::from_channel(server_end.into_channel());
44            Self { channel }
45        }
46    }
47}
48
49pub use private::DirectoryWatcher;
50
51/// All directories implement this trait.  If a directory can be modified it should
52/// also implement the `MutableDirectory` trait.
53pub trait Directory: Node {
54    /// Opens a connection to this item if the `path` is "." or a connection to an item inside
55    /// this one otherwise.  `path` will not contain any "." or ".." components.
56    ///
57    /// `flags` corresponds to the fuchsia.io [`fio::Flags`] type. See fuchsia.io's Open method for
58    /// more information regarding how flags are handled and what flag combinations are valid.
59    ///
60    /// If this method was initiated by a FIDL Open call, hierarchical rights are enforced at the
61    /// connection layer.
62    ///
63    /// If the implementation takes `object_request`, it is then responsible for sending an
64    /// `OnRepresentation` event when `flags` includes [`fio::Flags::FLAG_SEND_REPRESENTATION`].
65    ///
66    /// This method is called via either `Open` or `Reopen` fuchsia.io methods. Any errors returned
67    /// during this process will be sent via an epitaph on the `object_request` channel before
68    /// closing the channel.
69    fn open(
70        self: Arc<Self>,
71        scope: ExecutionScope,
72        path: Path,
73        flags: fio::Flags,
74        object_request: ObjectRequestRef<'_>,
75    ) -> Result<(), Status>;
76
77    /// Same as [`Self::open`] but the implementation is async. This may be more efficient if the
78    /// directory needs to do async work to open the connection.
79    fn open_async(
80        self: Arc<Self>,
81        scope: ExecutionScope,
82        path: Path,
83        flags: fio::Flags,
84        object_request: ObjectRequestRef<'_>,
85    ) -> impl Future<Output = Result<(), Status>> + Send
86    where
87        Self: Sized,
88    {
89        ready(self.open(scope, path, flags, object_request))
90    }
91
92    /// Reads directory entries starting from `pos` by adding them to `sink`.
93    /// Once finished, should return a sealed sink.
94    fn read_dirents(
95        &self,
96        pos: &TraversalPosition,
97        sink: Box<dyn dirents_sink::Sink>,
98    ) -> impl Future<Output = Result<(TraversalPosition, Box<dyn dirents_sink::Sealed>), Status>> + Send
99    where
100        Self: Sized;
101
102    /// Register a watcher for this directory.
103    /// Implementations will probably want to use a `Watcher` to manage watchers.
104    fn register_watcher(
105        self: Arc<Self>,
106        scope: ExecutionScope,
107        mask: fio::WatchMask,
108        watcher: DirectoryWatcher,
109    ) -> Result<(), Status>;
110
111    /// Unregister a watcher from this directory. The watcher should no longer
112    /// receive events.
113    fn unregister_watcher(self: Arc<Self>, key: usize);
114
115    #[cfg(any(fuchsia_api_level_at_least = "PLATFORM", not(fuchsia_api_level_at_least = "NEXT")))]
116    /// DEPRECATED - Do not implement unless required for backwards compatibility. Called when
117    /// handling a fuchsia.io/Directory.DeprecatedOpen request.
118    fn deprecated_open(
119        self: Arc<Self>,
120        _scope: ExecutionScope,
121        flags: fio::OpenFlags,
122        _path: Path,
123        server_end: ServerEnd<fio::NodeMarker>,
124    ) {
125        flags.to_object_request(server_end.into_channel()).shutdown(Status::NOT_SUPPORTED);
126    }
127}
128
129/// This trait indicates a directory that can be mutated by adding and removing entries.
130/// This trait must be implemented to use a `MutableConnection`, however, a directory could also
131/// implement the `DirectlyMutable` type, which provides a blanket implementation of this trait.
132pub trait MutableDirectory: Directory + Send + Sync {
133    /// Adds a child entry to this directory.  If the target exists, it should fail with
134    /// ZX_ERR_ALREADY_EXISTS.
135    fn link<'a>(
136        self: Arc<Self>,
137        _name: String,
138        _source_dir: Arc<dyn Any + Send + Sync>,
139        _source_name: &'a str,
140    ) -> BoxFuture<'a, Result<(), Status>> {
141        Box::pin(ready(Err(Status::NOT_SUPPORTED)))
142    }
143
144    /// Set the mutable attributes of this directory based on the values in `attributes`. If the
145    /// directory does not support updating *all* of the specified attributes, implementations
146    /// should fail with `ZX_ERR_NOT_SUPPORTED`.
147    fn update_attributes(
148        &self,
149        attributes: fio::MutableNodeAttributes,
150    ) -> impl Future<Output = Result<(), Status>> + Send
151    where
152        Self: Sized;
153
154    /// Removes an entry from this directory.
155    fn unlink(
156        self: Arc<Self>,
157        name: &str,
158        must_be_directory: bool,
159    ) -> impl Future<Output = Result<(), Status>> + Send
160    where
161        Self: Sized;
162
163    /// Syncs the directory.
164    fn sync(&self) -> impl Future<Output = Result<(), Status>> + Send
165    where
166        Self: Sized;
167
168    /// Renames into this directory.
169    fn rename(
170        self: Arc<Self>,
171        _src_dir: Arc<dyn MutableDirectory>,
172        _src_name: Path,
173        _dst_name: Path,
174    ) -> BoxFuture<'static, Result<(), Status>> {
175        Box::pin(ready(Err(Status::NOT_SUPPORTED)))
176    }
177
178    /// Creates a symbolic link.
179    fn create_symlink(
180        &self,
181        _name: String,
182        _target: Vec<u8>,
183        _connection: Option<ServerEnd<fio::SymlinkMarker>>,
184    ) -> impl Future<Output = Result<(), Status>> + Send
185    where
186        Self: Sized,
187    {
188        ready(Err(Status::NOT_SUPPORTED))
189    }
190}
vfs/directory/entry_container.rs

vfs/directory/
entry_container.rs
