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