General: Forums subtopic: App & System Services > Core OS Forums tags: Files and Storage, Foundation, FSKit, File Provider, Finder Sync, Disk Arbitration, APFS Foundation > Files and Data Persistence documentation Low-level file system APIs are documented in UNIX manual pages File System Programming Guide archived documentation About Apple File System documentation Apple File System Guide archived documentation File system changes introduced in iOS 17 forums post On File System Permissions forums post Extended Attributes and Zip Archives forums post Unpacking Apple Archives forums post Creating new file systems: FSKit framework documentation File Provider framework documentation Finder Sync framework documentation App Extension Programming Guide > App Extension Types > Finder Sync archived documentation Managing storage: Disk Arbitration framework documentation Disk Arbitration Programming Guide archived documentation Mass Storage Device Driver Programming Guide archived documentation Device File Access Guide for Storage Devices archived documentation BlockStorageDeviceDriverKit framework documentation Volume format references: Apple File System Reference TN1150 HFS Plus Volume Format Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com"

Currently tested, if the file provider goes offline (referring to calling disconnect) and deletes a file, the system will automatically trigger the deleteItems event after reconnecting (note that only after calling reconnect again will the current deleteItems logic be reached). However, for offline deletion, I would like to pass it directly without operating on the cloud. Can mounting disks determine which operations were performed offline during reboot

I am trying to populate the Finder comment field from extendedAttributes with the code bellow but it doesn't work. Any idea why ? var extendedAttributes: [String : Data] { var attrs = [String: Data]() let comment = self.caption do { let xmlPlistData = try PropertyListSerialization.data(fromPropertyList: comment as Any, format: .xml, options: 0) attrs["com.apple.metadata:kMDItemFinderComment"] = xmlPlistData } catch { NSLog("Error during plist conversion: \(error)") } return attrs }

I'm working on a FileProvider which allows access to encrypted files in Dropbox; I can successfully read and present the decrypted files, so I know it's basically working. But I'm having problems getting FileProvider to re-enumerate a folder when its encryption status changes. When the FileProvider receives an update notification saying a folder is now encrypted, I use signalEnumerator to re-enumerate the folder: FileProviderExtension.manager?.signalEnumerator(for: existingItem.itemIdentifier, completionHandler: { (ourError : Error?) -> Void in       if let ourError = ourError {           log("notifyCallback: mount / unmount failed re-enumeration: \(ourError)")       } else {           log("notifyCallback: mount / unmount signalled re-enumeration; pending")       } }) The log reports that the re-enumeration is pending... but as far as I can tell, neither enumerateItems nor enumerateChanges is called on the folder's item unless a Finder window is actually open for that folder. This means that, when an app other than Finder tries to access the files through the filesystem, it doesn't see the updated set of filenames. (For further reference: I've added code to both enumerateItems and enumerateChanges, so that if the call has been triggered by a recent folder-encryption notification, it retrieves a complete set of items from the Dropbox folder. If a retrieved file has an encrypted filename, it reports it as a modified item and returns its filename in-clear; if the filename isn't encrypted, it doesn't return the item (for enumerateItems) or returns it as a deleted item (for enumerateChanges). This approach seems to work successfully for listing folders with a constant state; it's only if the user encrypts / decrypts a folder without currently having a Finder window open inside that folder that I'm not seeing a refresh.) Any advice on how I can force a re-enumeration without a Finder window currently being displayed?

I am developing a FileProvider extension which will be launched for one or more domains. In the case where I have two domains, say with displayNames "Foo" and "Bar", the finder will then show "MyExtension - Foo" and "MyExtension - Bar" respectively after registering them with addDomain. However, if I only have a single domain, let's say "Foo" – then I just see "MyExtension" rather than "MyExtension - Foo". Now ideally I'd like to be able to control the entire name, but barring that at least be able to show the displayName even with a single domain. How can I achieve that?

Hello Everyone, I'm trying to add badges to files in my File Provider Extension for macOS. I'm not trying to create my own Item decorations here, but use the default Icons provided by apple (such as com.apple.icon-decoration.badge.heart , com.apple.icon-decoration.badge.pinned). I've gone through the Sample code provided by Apple for Fruit Basket. I've tried to replicate the same thing in my Extension as well but It seems I'm unable to display Icons. I'm not even getting any Error when the Icons are not being displayed, So I've been stuck for a month on this. These are the Things that I've done below: Folder Structure : FileExplorer |- FileProviderApp | |- UI.swift | |- ContentView.swift |- Extension |- extension.swift |- item.swift |- enumerator.swift |- info.plist According to the instructions given in the Documentation for Decorations here : https://developer.apple.com/documentation/fileprovider/nsfileprovideritemdecorating. The implementation was done as follows: content inside info.plist of the File provider Extension <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>NSExtension</key> <dict> <key>NSExtensionFileProviderSupportsEnumeration</key> <true/> <key>NSExtensionPointIdentifier</key> <string>com.apple.fileprovider-nonui</string> <key>NSExtensionPrincipalClass</key> <string>$(PRODUCT_MODULE_NAME).FileProviderExtension</string> <key>NSFileProviderDecorations</key> <array> <dict> <key>BadgeImageType</key> <string>com.apple.icon-decoration.badge.heart</string> <key>Category</key> <string>Badge</string> <key>Identifier</key> <string>$(PRODUCT_BUNDLE_IDENTIFIER).heart</string> <key>Label</key> <string>Heart Item</string> </dict> </array> </dict> </dict> </plist> In my extension's NSFileProviderItem I've also Implemented the protocol NSFileProviderItemDecorating. and the decoration's method as static let decorationPrefix = Bundle.main.bundleIdentifier! static let heartDecoration = NSFileProviderItemDecorationIdentifier(rawValue: "\(decorationPrefix).heart") var decorations: [NSFileProviderItemDecorationIdentifier]? { var decos = [NSFileProviderItemDecorationIdentifier]() decos.append(Item.heartDecoration) return decos } I was expecting to see badges on the File items in Finder, but i got nothing. When I modified the FruitBasket Project to do the same i was able to see badges, but not when I try to implement it in my Extension. Was I missing a step or is the issue something else ?

On the macOS platform, I am planning to use the combination of NSFileProviders Custom Action and userInfo to implement custom context menus. However, the NSExtensions FileProviders Action Activation Rule in info does not work as long as it is related to userInfo. Are there any restrictions on the use of this userInfo? keepDownloaded is bool value

I'm trying to put a sub menu inside the context menu using the NSExtensionFileProviderActions in info.plist. Which should look like this image below I have been trying to use FPUIActionExtensionViewController for doing this task but I havent got any context menu like above. But still doing that does seem to complicate the task more. Is there a simpler way to do this task, like doing it within the info.plist so I dont have to complicate the task by creating a view controller. ?

I found that the enumerateItems function is only called when a directory is opened for the first time. If the same directory is opened in the future, enumerateItems will not be called again. Can you set or actively trigger the call to the enumerateItems function

I am currently encountering a problem: during the process of uploading a large file, I have moved the file that was not successfully uploaded to the trash can. These two operations have been tested to be serial (triggering the 'create Item' callback first, followed by the 'modify Item' callback), which means that the file must be uploaded before it can be moved to the recycle bin (which can also result in the file being stored in the cloud recycle bin). I want to implement: directly interrupt this upload process and then do not complete the upload. How can I achieve this? Please help me. Thank you

I want to use FileProvder to implement the function of recovering from the recycle bin (the cloud recycle bin does not move, and after the local recycle bin is restored, the upload event is triggered again), but testing shows that the current recovery from the recycle bin is through the modifyItem event, and the CreateItem event is not triggered again to upload locally restored files Implement the deletion of undelivered files (dateless) without moving them to the recycle bin, which currently appears to be achieved by granting file. dash permission. But it is possible for the content of a file to be manually verified by the user. How can this be solved? How can we dynamically monitor whether a file is dataless Thank you for your reply. Could you please help answer my question

I face this issue only on macOS 26 and only on the Intel architecture. I'm unable to download files from a file provider's folder when I make them read-only. STEPS TO REPRODUCE Download the sample from https://developer.apple.com/documentation/fileprovider/synchronizing-files-using-file-provider-extensions?language=objc Follow the steps on the page to configure the project. Build the project. Run it. Add a domain. Open the domain's folder in the Finder. Move a file to the domain's folder. Right-click on the file in the domain's folder and select "Remove Download". Close the Finder's window with the domain's folder and kill all the "Provider" processes to get rid of running instances of the extension. Change Item's capabilities in Item.swift to make the items read-only: var result: NSFileProviderItemCapabilities = [ .allowsContentEnumerating, .allowsReading ] Rebuild the project and run it. Open the domain's folder and try to drag and drop the file from the extension's folder to, let's say, the Desktop folder. EXPECTED RESULT The file is copied ACTUAL RESULT A dialog pops up with text "The file “filename” cannot be downloaded. Do you want to skip it?" Stop/Skip

We use File Provider Extension in our main app, and it is working fine. We always call "NSFileProviderManager.add(_:completionHandler:)" function to start the extension, and "NSFileProviderManager.disconnect(reason:options:completionHandler:)" to temporarily quit the extension with the reason which will be shown in the Finder at the top of the FP domain folder. But sometimes, when the main app calls the above functions, the following issue cases occur, and the extension does not start/stop: The completionHandler function doesn't get called (As we noticed, we waited for 2 minutes. Then, we restarted the main app.) One of the following errors returned: i) "The application cannot be used right now", ii) "Couldn't communicate with the helper application", iii) "No valid file provider found with identifier" Here, the important thing is that restarting the main app once or twice clears the issue, and the extension starts. But it is frustrating to restart the app each time we get this issue. We want to know the following things: Why and when do the above issues occur? Why do they occur only sometimes, and how does the app restart clear the issue? How do we resolve them without restarting the main app? This has become a critical issue, so a detailed explanation would be greatly appreciated. TIA.

We are creating a Replicated FileProvider based application, where we need to change folder icons for root level folders. I tried below two approaches. This using NSFileProviderDecorations + Custom UTType, this changed the UI as shown: This using Custom UTType, this had no UI change: How can we change the default folder icon, to our custom icon?

I want to implement a feature on macOS using FileProvider: only grant the allowsTrashing permission to files that have already been downloaded, while not granting it to dataless files. However, the system will automatically drain and clear the content. How can this be detected (and how to determine whether a file is dataless)

I want to traverse my local Google Drive folder to calculate the size of all the files on my drive. I'm not interested in files or directories that are not present locally. I use getattrlistbulk for traversing and it takes way too much time. I think it is because FileProvider tries to download metadata for the directories that are not yet materialised. Is there a way to skip non-materialised directories?

https://developer.apple.com/documentation/fileprovider/nsfileproviderpartialcontentfetching/3923718-fetchpartialcontents fetchPartialContents(for:version:request:minimalRange:aligningTo:options:completionHandler:) I need to use this function to fetch contents of the files partially. But it seems I'm just unable to receive any callback when i try to open the file via double click on finder. I've tried to open files of different types and sizes but still i'm defaulting back to fetchContents(for:version:request:completionHandler:) . I've been thinking if there are any specific configurations or requirements that i have to meet , so i could trigger this callback function for all the fetch Operations for files ? If No, then where am i going wrong ?

In the context of a NSFileProviderReplicatedExtension I would like to only see the "Move to Bin" Finder action when files have been materlialised ( isDownloaded fileprovider attribute ) I thought it might be possible to get the isDownloaded attribute in my NSFileProviderItemProtocol class capabilities method but that doesn't seem to be the case. Possible ?

Hello, we have a file provider based macOS app. Around June we started receiving reports that our users have problems when opening files. Sometimes they get "Invalid argument" alerts after double-clicking on a dataless file. We receive similar errors when trying to materialize the files programmatically from our app (not FP extension)(*): "The operation could not be completed. Invalid argument" code: 22 domain: "NSPOSIXErrorDomain" underlyingError: "cannotMaterialize" code: 33 domain: "libfssync.VFSFileError" We also see those errors with matching timestamps in the output from fileproviderctl dump: > (...) update-item: 🔶 last:(...) (-1min27s) (...) error:'NSError: POSIX 22 "The operation couldn’t be completed. Invalid argument" Underlying={NSError: libfssync.VFSFileError 33 "cannotMaterialize" }}' domain:none category:<nil> (...) At the same time our file provider extension receives fetchPartialContents call or no call at all. If it receives the call it finishes with success and returns correct range: requestedRange: "{0, 15295}" returnedRange: "{0, 524288}" alignment: "16384" Sadly we don't know how to reproduce those issues. We will be grateful for any hints that could be useful in debugging. Some more context: if materializing a file fails with this error, subsequent materialization attempts fail similarly in local testing when downloading a file with the code below, or double-click, we only get regular fetchContents call file returned by fetchPartialContents should have correct size the app is built with XCode 16.1, customers reporting this issue have OS/FP versions: 24F74/2882.120.74 and 24G90/2882.140.30 (*) More or less the code that we use to materialize files func materializeURL(_ url: URL) throws { if try url.isDataless() { var error: NSError? = nil let coordinator = NSFileCoordinator(filePresenter: nil) coordinator.coordinate(readingItemAt: url, error: &error) { _ in } if let error { throw error } } } private extension URL { func isDataless() throws -> Bool { let downloadStatus = try self .resourceValues(forKeys: [.ubiquitousItemDownloadingStatusKey]) .ubiquitousItemDownloadingStatus return downloadStatus == .notDownloaded || downloadStatus == .none } }

I’ve filed this as FB20943098 (macOS 26.1 – FileProvider v3 synchronous enumeration bug), but posting here in case others can reproduce and add duplicates. Systems: macOS 26.1 (26B82) M4 Mac mini Pro and M4 MacBook Air Symptoms: In any app (TextEdit, Pages, Browsers, etc.), the Open/Save dialog lags for ~1s per folder navigation click. CPU spikes from fileproviderd, cloudd, bird, and siriactionsd. Key discovery: If my iCloud Drive root is empty (only “Documents” and “Downloads”), performance is perfect. As soon as any folder or file exists at the root of iCloud Drive, the lag returns immediately. Moving those items into “Documents” or “Downloads” makes everything smooth again. Analysis: Based on process traces and container paths, this appears to originate in the FileProvider.framework subsystem (via fileproviderd), which mediates iCloud Drive. Early evidence suggests that folder enumeration of the iCloud Drive container root may be blocking UI threads in macOS 26.1. I believe this may be related to the recent internal migration of the file-provider backend (often referred to as “v3”), but I do not have direct confirmation from Apple of that exact change. MacOS 26.1’s new FileProvider v3 backend seems to be blocking the Open/Save panel while enumerating the iCloud Drive root container (~/Library/Application Support/FileProvider/723EBBFF-…). Folder enumeration seems to wait synchronously for metadata from fileproviderd, and if the local SQLite DB is busy (WAL writes or sync state checks), UI freezes briefly. Workarounds: Disabling iCloud Drive entirely fixes the issue. Simply disabling Desktop/Documents sync does not help. Keeping the iCloud Drive root empty avoids the lag without turning iCloud off. I am able to store whatever I please in the Desktop or Documents folder which is currently syncing. Would appreciate if others on 26.1 could confirm. Engineers: I’ve attached fs_usage, log stream, and process samples to my Feedback ticket via the FB20943098. Expected behavior: Folder enumeration in NSOpenPanel should remain asynchronous regardless of FileProvider background activity. Open/save modal should be responsive and smooth.

I'm working on an iOS document-based app. It uses ReferenceFileDocument and custom creation of documents via DocumentGroupLaunchScene + NewDocumentButton. It works fine when I use the plain NewDocumentButton("Whatever") (without any more arguments), but when I want to perform additional setup via preapreDocumentURL or even just add a contentType it gives such output in the console when I hit it: Content serialization failed, document won't be saved. UTType.replayable is correctly wired up in the plist. It looks like a bug in the SDK, but maybe there is a chance that I'm doing something wrong? Here's a code: import SwiftUI import UniformTypeIdentifiers import Combine @main struct MyApp: App { var body: some Scene { DocumentGroup { Document() } editor: { documentConfiguration in EmptyView() } DocumentGroupLaunchScene("Yoyo") { NewDocumentButton(contentType: .replayable) { return URL(string: "whatever, it doesnt even go there...")! } } } } final class Document: ReferenceFileDocument { static var readableContentTypes: [UTType] { [.replayable] } @Published var x = 0 init() {} init(configuration: ReadConfiguration) throws {} func snapshot(contentType: UTType) throws -> Data { Data() } func fileWrapper(snapshot: Data, configuration: WriteConfiguration) throws -> FileWrapper { .init(regularFileWithContents: snapshot) } } extension UTType { static var replayable: UTType { UTType(exportedAs: "com.whatever.yo") } }