cloud_filter/filter/
sync_filter.rs

1use std::path::PathBuf;
2
3use crate::{
4    error::{CResult, CloudErrorKind},
5    filter::{info, ticket, Request},
6};
7
8/// Core functions for implementing a Sync Engine.
9///
10/// [Send] and [Sync] are required as the callback could be invoked from an arbitrary thread, [read
11/// here](https://docs.microsoft.com/en-us/windows/win32/api/cfapi/ne-cfapi-cf_callback_type#remarks).
12pub trait SyncFilter: Send + Sync {
13    /// A placeholder hydration has been requested. This means that the placeholder should be
14    /// populated with its corresponding data on the remote.
15    fn fetch_data(
16        &self,
17        _request: Request,
18        _ticket: ticket::FetchData,
19        _info: info::FetchData,
20    ) -> CResult<()>;
21
22    /// A placeholder hydration request has been cancelled.
23    fn cancel_fetch_data(&self, _request: Request, _info: info::CancelFetchData) {}
24
25    /// Followed by a successful call to [SyncFilter::fetch_data][super::SyncFilter::fetch_data], this callback should verify the integrity of
26    /// the data persisted in the placeholder.
27    ///
28    /// **You** are responsible for validating the data in the placeholder. To approve
29    /// the request, use the ticket provided.
30    ///
31    /// Note that this callback is only called if [HydrationPolicy::ValidationRequired][crate::root::HydrationPolicy::ValidationRequired]
32    /// is specified.
33    fn validate_data(
34        &self,
35        _request: Request,
36        _ticket: ticket::ValidateData,
37        _info: info::ValidateData,
38    ) -> CResult<()> {
39        Err(CloudErrorKind::NotSupported)
40    }
41
42    /// A directory population has been requested. The behavior of this callback is dependent on
43    /// the [PopulationType][crate::root::PopulationType] variant specified during registration.
44    fn fetch_placeholders(
45        &self,
46        _request: Request,
47        _ticket: ticket::FetchPlaceholders,
48        _info: info::FetchPlaceholders,
49    ) -> CResult<()> {
50        Err(CloudErrorKind::NotSupported)
51    }
52
53    /// A directory population request has been cancelled.
54    fn cancel_fetch_placeholders(&self, _request: Request, _info: info::CancelFetchPlaceholders) {}
55
56    /// A placeholder file handle has been opened for read, write, and/or delete
57    /// access.
58    fn opened(&self, _request: Request, _info: info::Opened) {}
59
60    /// A placeholder file handle that has been previously opened with read, write,
61    /// and/or delete access has been closed.
62    fn closed(&self, _request: Request, _info: info::Closed) {}
63
64    /// A placeholder dehydration has been requested. This means that all of the data persisted in
65    /// the file will be __completely__ discarded.
66    ///
67    /// The operating system will handle dehydrating placeholder files automatically. However, it
68    /// is up to **you** to approve this. Use the ticket to approve the request.
69    fn dehydrate(
70        &self,
71        _request: Request,
72        _ticket: ticket::Dehydrate,
73        _info: info::Dehydrate,
74    ) -> CResult<()> {
75        Err(CloudErrorKind::NotSupported)
76    }
77
78    /// A placeholder dehydration request has been cancelled.
79    fn dehydrated(&self, _request: Request, _info: info::Dehydrated) {}
80
81    /// A placeholder file is about to be deleted.
82    ///
83    /// The operating system will handle deleting placeholder files automatically. However, it is
84    /// up to **you** to approve this. Use the ticket to approve the request.
85    fn delete(
86        &self,
87        _request: Request,
88        _ticket: ticket::Delete,
89        _info: info::Delete,
90    ) -> CResult<()> {
91        Err(CloudErrorKind::NotSupported)
92    }
93
94    /// A placeholder file has been deleted.
95    fn deleted(&self, _request: Request, _info: info::Deleted) {}
96
97    /// A placeholder file is about to be renamed or moved.
98    ///
99    /// The operating system will handle moving and renaming placeholder files automatically.
100    /// However, it is up to **you** to approve this. Use the ticket to approve the
101    /// request.
102    ///
103    /// When the operation is completed, the [SyncFilter::renamed] callback will be called.
104    fn rename(
105        &self,
106        _request: Request,
107        _ticket: ticket::Rename,
108        _info: info::Rename,
109    ) -> CResult<()> {
110        Err(CloudErrorKind::NotSupported)
111    }
112
113    /// A placeholder file has been renamed or moved.
114    fn renamed(&self, _request: Request, _info: info::Renamed) {}
115
116    /// Placeholder for changed attributes under the sync root.
117    ///
118    /// This callback is implemented using [ReadDirectoryChangesW](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-readdirectorychangesw)
119    /// so it is not provided by the `Cloud Filter APIs`.
120    ///
121    /// This callback is used to detect when a user pins or unpins a placeholder file, etc.
122    ///
123    /// See also [Cloud Files API Frequently Asked Questions](https://www.userfilesystem.com/programming/faq/).
124    fn state_changed(&self, _changes: Vec<PathBuf>) {}
125}
cloud_filter/filter/sync_filter.rs

cloud_filter/filter/
sync_filter.rs
