objc2_file_provider/generated/NSFileProviderActions.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6use objc2_foundation::*;
7
8use crate::*;
9
10/// [Apple's documentation](https://developer.apple.com/documentation/fileprovider/nsfileproviderextensionactionidentifier?language=objc)
11// NS_TYPED_EXTENSIBLE_ENUM
12pub type NSFileProviderExtensionActionIdentifier = NSString;
13
14/// NSFileProviderActions.
15///
16/// This category encapsulates common user-driven actions on FileProvider's items.
17#[cfg(feature = "Extension")]
18impl NSFileProviderExtension {
19 extern_methods!(
20 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
21 /// Import a document.
22 ///
23 /// The file or package at fileURL should be moved on disk into the file provider's
24 /// own storage, where it will later be uploaded. The completion block should be
25 /// executed after the move on disk, but before the upload. Before doing any
26 /// network, actually.
27 ///
28 /// In the completion block, importedDocumentItem should have these properties set:
29 /// - itemIdentifier
30 /// - parentItemIdentifier (to the value passed in to this method)
31 /// - filename (to fileURL's resource value for key NSURLNameKey)
32 /// - creationDate (to NSURLCreationDateKey)
33 /// - contentModificationDate (to NSURLContentModificationDateKey)
34 /// - contentType (to NSURLContentTypeKey)
35 /// - documentSize (to NSURLTotalFileSizeKey on a flat file, or to the sum of the
36 /// files sizes for a package)
37 /// - capabilities
38 ///
39 /// [fileURL startAccessingSecurityScopedResource] needs to be called prior to
40 /// accessing this security scoped URL, and stopAccessingSecurityScopedResource
41 /// needs to be called when done.
42 ///
43 /// Note that itemIdentifier should be set with no network call. It doesn't have
44 /// to be the final identifier. If the identifier changes after talking to the
45 /// server then the file provider should send a delete for the temporary, local
46 /// identifier immediately followed by an add with the final identifier.
47 ///
48 /// A reasonable way of organizing files in the file provider storage is:
49 /// <file
50 /// provider storage path>/
51 /// <itemIdentifier
52 /// >/
53 /// <filename
54 /// >.
55 /// <extension
56 /// >
57 /// If the item identifier was to change, you should move the file on disk to
58 /// update its path, under coordination with NSFileCoordinatorWritingForMoving.
59 ///
60 /// This is expected to work offline even if there might be a collision (another
61 /// item with the same filename and parentItemIdentifier) only detected when later
62 /// syncing up this change to the server. In that case, it is suggested that a
63 /// follow up update to the item change its filename to something unique. This
64 /// wouldn't be considered an error to import.
65 ///
66 /// If however you can tell right away, with no communication to your server, that
67 /// there is a collision then this call should fail with error code
68 /// NSFileProviderErrorFilenameCollision generated with this method:
69 /// -[NSError (NSFileProviderError) fileProviderErrorForCollisionWithItem:].
70 ///
71 /// The existing item set in this error will be used to handle the collision, and
72 /// ask the user if she or he would like to replace the existing item. This takes
73 /// into account the existing item's capabilities (particularly
74 /// NSFileProviderItemCapabilitiesAllowsTrashing and AllowsDeleting.)
75 ///
76 /// Collision checks should be case insensitive even if the filesystem or file
77 /// provider might allow two coexisting filenames differing only by their case.
78 ///
79 /// Upload errors (such as NSFileProviderErrorInsufficientQuota) should be handled
80 /// with a subsequent update to the item, setting its uploadingError property.
81 /// Upload errors should not prevent creating or importing a document, because they
82 /// can be resolved at a later date (for example, when the user has quota again.)
83 ///
84 /// Other errors will be presented to the user, but are unexpected. If you want to
85 /// prevent imports in a given directory, then the directory item's capacities
86 /// should exclude NSFileProviderItemCapabilitiesAllowsAddingSubItems.
87 #[unsafe(method(importDocumentAtURL:toParentItemIdentifier:completionHandler:))]
88 #[unsafe(method_family = none)]
89 pub unsafe fn importDocumentAtURL_toParentItemIdentifier_completionHandler(
90 &self,
91 file_url: &NSURL,
92 parent_item_identifier: &NSFileProviderItemIdentifier,
93 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
94 );
95
96 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
97 /// Create a directory.
98 ///
99 /// This is expected to complete before doing any network.
100 ///
101 /// In the completion block, createdDirectoryItem should have these properties set:
102 /// - itemIdentifier
103 /// - parentItemIdentifier (to the value passed in to this method)
104 /// - filename (to directoryName)
105 /// - creationDate (to the current date and time)
106 /// - contentType (to "public.folder" - UTTypeFolder)
107 /// - childItemCount (to 0)
108 /// - capabilities
109 ///
110 /// Errors (including collision errors) are handled as documented for the import
111 /// method above. Directory creation is gated by the capabilities of the
112 /// destination directory, with NSFileProviderItemCapabilitiesAllowsAddingSubItems.
113 #[unsafe(method(createDirectoryWithName:inParentItemIdentifier:completionHandler:))]
114 #[unsafe(method_family = none)]
115 pub unsafe fn createDirectoryWithName_inParentItemIdentifier_completionHandler(
116 &self,
117 directory_name: &NSString,
118 parent_item_identifier: &NSFileProviderItemIdentifier,
119 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
120 );
121
122 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
123 /// Rename a document or a directory.
124 ///
125 /// This is expected to complete before doing any network.
126 ///
127 /// itemName is the full file or directory name, complete with its file extension.
128 /// In the completion block, property renamedItem.filename should change to
129 /// itemName. Property renamedItem.displayName should also be updated if you
130 /// chose to overwrite that method.
131 ///
132 /// Errors (including collision errors) are handled as documented for the import
133 /// method above. Renames are gated by the capabilities of the renamed item, with
134 /// NSFileProviderItemCapabilitiesAllowsRenaming.
135 #[unsafe(method(renameItemWithIdentifier:toName:completionHandler:))]
136 #[unsafe(method_family = none)]
137 pub unsafe fn renameItemWithIdentifier_toName_completionHandler(
138 &self,
139 item_identifier: &NSFileProviderItemIdentifier,
140 item_name: &NSString,
141 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
142 );
143
144 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
145 /// Move an item to a new directory.
146 ///
147 /// This is expected to complete before doing any network.
148 ///
149 /// If newName is non null, the moved item should be renamed to newName.
150 ///
151 /// Errors (including collision errors) are handled as documented for the import
152 /// method above. Moves are gated by the capabilities of both the moved item with
153 /// NSFileProviderItemCapabilitiesAllowsReparenting, and the destination directory
154 /// with NSFileProviderItemCapabilitiesAllowsAddingSubItems.
155 #[unsafe(method(reparentItemWithIdentifier:toParentItemWithIdentifier:newName:completionHandler:))]
156 #[unsafe(method_family = none)]
157 pub unsafe fn reparentItemWithIdentifier_toParentItemWithIdentifier_newName_completionHandler(
158 &self,
159 item_identifier: &NSFileProviderItemIdentifier,
160 parent_item_identifier: &NSFileProviderItemIdentifier,
161 new_name: Option<&NSString>,
162 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
163 );
164
165 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
166 /// Move an item to the trash.
167 ///
168 /// In the completion block, property trashedItem.isTrashed should be set to YES.
169 /// You should keep track of the original parentItemIdentifier of the item before
170 /// it was moved to trash, so you can move the item back where it used to be in the
171 /// untrash method. You could use the trashedItem.parentItemIdentifier property
172 /// for that.
173 ///
174 /// The trashed item should continue to belong to the working set of documents
175 /// cached on the device and visible offline to the user. But if it is a
176 /// directory, then all of its children should be removed from the working set and
177 /// the file provider extension should send deletion events to make sure that they
178 /// no longer appear in the recent lists.
179 ///
180 /// It is also suggested that shared documents be unshared when trashed.
181 ///
182 /// Trash is gated by the capabilities of the trashed item with
183 /// NSFileProviderItemCapabilitiesAllowsTrashing.
184 #[unsafe(method(trashItemWithIdentifier:completionHandler:))]
185 #[unsafe(method_family = none)]
186 pub unsafe fn trashItemWithIdentifier_completionHandler(
187 &self,
188 item_identifier: &NSFileProviderItemIdentifier,
189 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
190 );
191
192 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
193 /// Move an item out of the trash.
194 ///
195 /// If parentItemIdentifier is nil, the file provider should attempt to put the
196 /// item back where it was when it was moved to the trash; otherwise it should move
197 /// it to this new parent.
198 ///
199 /// If the item is a directory, then the file provider extension should enumerate
200 /// the children and send addition events in the working set so that the documents
201 /// in the now untrashed directory may be reindexed.
202 ///
203 /// Untrash is gated by the capabilities of the destination directory, with
204 /// NSFileProviderItemCapabilitiesAllowsAddingSubItems.
205 #[unsafe(method(untrashItemWithIdentifier:toParentItemIdentifier:completionHandler:))]
206 #[unsafe(method_family = none)]
207 pub unsafe fn untrashItemWithIdentifier_toParentItemIdentifier_completionHandler(
208 &self,
209 item_identifier: &NSFileProviderItemIdentifier,
210 parent_item_identifier: Option<&NSFileProviderItemIdentifier>,
211 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
212 );
213
214 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
215 /// Delete an item forever.
216 ///
217 /// This is called when the user deletes an item that was already in the Trash and
218 /// the item should no longer appear there after this call. This call should
219 /// remove the item from the working set.
220 ///
221 /// Delete is gated by the capabilities of the removed item with
222 /// NSFileProviderItemCapabilitiesAllowsDeleting.
223 #[unsafe(method(deleteItemWithIdentifier:completionHandler:))]
224 #[unsafe(method_family = none)]
225 pub unsafe fn deleteItemWithIdentifier_completionHandler(
226 &self,
227 item_identifier: &NSFileProviderItemIdentifier,
228 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
229 );
230
231 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
232 /// Mark an item as recently used, or clear its lastUsedDate if nil.
233 ///
234 /// This last used date is the sort key for the recent lists. It is the primary
235 /// hint that an item must belong to the working set cached and indexed on the
236 /// user's device.
237 ///
238 /// The file provider is asked to persist the new last used date on disk, then call
239 /// the completion callback with the updated last used date. At a later point, the
240 /// file provider should sync the new last used date to their server.
241 ///
242 /// The error parameter is here for debugging purposes alone; it won't be presented
243 /// to the user or otherwise handled, but it will be logged.
244 #[unsafe(method(setLastUsedDate:forItemIdentifier:completionHandler:))]
245 #[unsafe(method_family = none)]
246 pub unsafe fn setLastUsedDate_forItemIdentifier_completionHandler(
247 &self,
248 last_used_date: Option<&NSDate>,
249 item_identifier: &NSFileProviderItemIdentifier,
250 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
251 );
252
253 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
254 /// Tag an item, or untag it if tagData is nil.
255 ///
256 /// The file provider is asked to persist the new tag data on disk, then call the
257 /// completion callback with the updated tagged data. At a later point, the file
258 /// provider should sync the new tag data to their server.
259 ///
260 /// Tagged items are relevant to the user and should be in the working set even if
261 /// they haven't been used recently.
262 ///
263 /// If set, the error will be immediately presented to the user and the item just
264 /// won't be tagged.
265 ///
266 /// On shared items, tags should sync across the devices of any one participant but
267 /// shouldn't sync across users.
268 #[unsafe(method(setTagData:forItemIdentifier:completionHandler:))]
269 #[unsafe(method_family = none)]
270 pub unsafe fn setTagData_forItemIdentifier_completionHandler(
271 &self,
272 tag_data: Option<&NSData>,
273 item_identifier: &NSFileProviderItemIdentifier,
274 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
275 );
276
277 #[cfg(all(feature = "NSFileProviderItem", feature = "block2"))]
278 /// Mark a directory as favorite (or no longer favorite if favoriteRank is nil.)
279 ///
280 /// The favorite rank is used to represent the relative order of two favorite
281 /// directories in the UI. It is a 64 bit unsigned integer. It needs to be synced.
282 ///
283 /// Favorite directories are relevant to the user and should be in the working set
284 /// even if they haven't been used recently. The documents and directories in the
285 /// favorite directory however don't all have to be in the working set, and don't
286 /// all have to be made accessible offline.
287 ///
288 /// The file provider is asked to persist the new favorite rank on disk, then call
289 /// the completion callback with the updated favorite rank. At a later point, the
290 /// file provider should sync the new favorite rank to their server.
291 #[unsafe(method(setFavoriteRank:forItemIdentifier:completionHandler:))]
292 #[unsafe(method_family = none)]
293 pub unsafe fn setFavoriteRank_forItemIdentifier_completionHandler(
294 &self,
295 favorite_rank: Option<&NSNumber>,
296 item_identifier: &NSFileProviderItemIdentifier,
297 completion_handler: &block2::DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
298 );
299 );
300}