-
Notifications
You must be signed in to change notification settings - Fork 549
Foundation iOS xcode26.0 b5
Alex Soto edited this page Aug 5, 2025
·
2 revisions
#Foundation.framework
diff -ruN /Applications/Xcode_26.0.0-beta4.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSFileManager.h /Applications/Xcode_26.0.0-beta5.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSFileManager.h
--- /Applications/Xcode_26.0.0-beta4.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSFileManager.h 2025-07-11 23:11:45
+++ /Applications/Xcode_26.0.0-beta5.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSFileManager.h 2025-07-24 01:43:30
@@ -324,71 +324,125 @@
*/
@property (nullable, readonly, copy) id<NSObject,NSCopying,NSCoding> ubiquityIdentityToken API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
-/* Sync controls available on an item
- */
+/// An option set of the sync controls available for an item.
+///
+/// Get an instance of this type by calling ``URL/resourceValues(forKeys:)`` on a ``URL`` instance (Swift) or ``NSURL/getResourceValue:forKey:error:`` on an ``NSURL`` (Swift or Objective-C) and passing in the key ``NSURLUbiquitousItemSupportedSyncControlsKey``.
typedef NS_OPTIONS(NSUInteger, NSFileManagerSupportedSyncControls) {
- /* Sync with the server can be paused on the item.
- */
+ /// The file provider supports pausing the sync on the item.
NSFileManagerSupportedSyncControlsPauseSync = 1 << 0,
- /* File Provider supports failing an upload if the local version conflicts with the server version.
- */
+ /// The file provider supports failing an upload if the local and server versions conflict.
NSFileManagerSupportedSyncControlsFailUploadOnConflict = 1 << 1,
} API_AVAILABLE(ios(26.0), macos(26.0), watchos(26.0), tvos(26.0), visionos(26.0));
-/* Asynchronously pauses the sync of an item at given URL. If the item is already paused, the pause will be considered successful. If the item is undergoing changes (sync up or sync down pending), the pause will fail with EBUSY and the app will have to wait for the state to have stabilized before retrying the pause.
-
- The pause of the sync is independent from the calling app's lifecycle. The sync of a file will not be resumed if the app closes or crashes. It has to be explicitely resumed using: [NSFileManager resumeSyncForUbiquitousItemAtURL:withBehavior:completionHandler:].
-
- Warning: To preserve the paused sync state of a file, the app should use document-level writing APIs such as NSFileWrapper or [NSFileManager replaceItemAtURL:withItemAtURL:backupItemName:options:resultingItemURL:error:]. Using data-level writing APIs such as [NSString writeToFile:atomically:encoding:error:] or [NSData writeToFile:atomically:] will result in the file resuming its sync to the server.
- */
+/// Asynchronously pauses sync of an item at the given URL.
+///
+/// Call this when opening an item to prevent sync from altering the contents of the URL.
+/// Once paused, the file provider will not upload local changes nor download remote changes.
+///
+/// While paused, call ``uploadLocalVersionOfUbiquitousItem(at:withConflictResolutionPolicy:completionHandler:)`` when the document is in a stable state.
+/// This action keeps the server version as up-to-date as possible.
+///
+/// If the item is already paused, a second call to this method reports success.
+/// If the file provider is already applying changes to the item, the pause fails with an ``NSFileWriteUnknownError-enum.case``, with an underlying error that has domain ``NSPOSIXErrorDomain`` and code ``POSIXError/EBUSY``.
+/// If the pause fails, wait for the state to stabilize before retrying.
+/// Pausing also fails with ``CocoaError/featureUnsupported`` if `url` refers to a regular (non-package) directory.
+///
+/// Pausing sync is independent of the calling app's lifecycle; sync doesn't automatically resume if the app closes or crashes and relaunches later.
+/// To resume syncing, explicitly call ``resumeSyncForUbiquitousItem(at:with:completionHandler:)``.
+/// Always be sure to resume syncing before you close the item.
+///
+/// - Parameters:
+/// - url: The URL of the item for which to pause sync.
+/// - completionHandler: A closure or block that the framework calls when the pause action completes. It receives a single ``NSError`` parameter to indicate an error that prevented pausing; this value is `nil` if the pause succeeded. In Swift, you can omit the completion handler and catch the thrown error instead.
- (void)pauseSyncForUbiquitousItemAtURL:(NSURL *)url completionHandler:(void (NS_SWIFT_SENDABLE ^)(NSError * _Nullable error))completionHandler API_AVAILABLE(ios(26.0), macos(26.0), visionos(26.0)) API_UNAVAILABLE(watchos, tvos);
-/* Behaviors available to resume the sync on an item.
-
- Always using preserveLocalChanges or afterUploadWithFailOnConflict is strongly recommended to avoid any risk of dataloss. In order to avoid conflicted file states, use afterUploadWithFailOnConflict to apply the local version cleanly on the server before resuming.
- The dropLocalChanges behavior should only be used when the app uses a side-channel to handle and merge conflicting changes on a file.
- */
+/// The behaviors the file manager can apply to resolve conflicts when resuming a sync.
+///
+/// You use this type when calling ``FileManager/resumeSyncForUbiquitousItem(at:with:completionHandler:)`` to resume synchronizing.
+/// In most situations, the ``NSFileManagerResumeSyncBehavior/preserveLocalChanges`` behavior is the best choice to avoid risk of data loss.
typedef NS_ENUM(NSInteger, NSFileManagerResumeSyncBehavior) {
- /* Resume the sync by trying to upload the local version of the file. If a newer version of the file is available on the server, the resume operation might create a conflict. To get out of a conflicted state, the app should use the NSFileVersion API to solve the conflicts
- */
+ /// Resumes synchronizing by uploading the local version of the file.
+ ///
+ /// If the server has a newer version, the server may create a conflict copy of the file, or may automatically pick the winner of the conflict.
+ /// Apps can choose to implement conflict handling themselves by passing `NSFileManagerResumeSyncBehaviorAfterUploadWithFailOnConflict`.
NSFileManagerResumeSyncBehaviorPreserveLocalChanges = 0,
- /* First upload the local version of the file with a failOnConflict policy. If it succeeds, resume the sync with the preserveLocalChanges behavior.
- */
+ /// Resumes sync by first uploading the local version of the file, failing if the provider detects a conflict.
+ ///
+ /// If the upload succeeds, the sync resumes with the ``preserveLocalChanges`` behavior.
+ ///
+ /// If the provider detects a conflict, the upload fails with an ``NSFileWriteUnknownError-enum.case``, with the underlying error of <doc://com.apple.documentation/documentation/FileProvider/NSFileProviderError/localVersionConflictingWithServer>.
+ /// In this case, the app needs to call ``FileManager/fetchLatestRemoteVersionOfItem(at:completionHandler:)``, rebase local changes on top of the newly fetched version to resolve the conflict, and try again to resume sync.
+ /// This scenario is only available on paused items for which the file provider supports the fail-on-conflict behavior.
+ /// To check that the file provider supports the behavior, get the ``NSURLUbiquitousItemSupportedSyncControlsKey`` URL resource and verify that ``NSFileManagerSupportedSyncControls/failUploadOnConflict`` is `true`.
NSFileManagerResumeSyncBehaviorAfterUploadWithFailOnConflict = 1,
- /* Resume the sync by overwriting any local changes with the remote version of the file. The local changes will be stored as an alternate version. This option shouldn't be used unless a side channel is used to merge conflicts.
- */
+ /// Resumes synchronizing by overwriting any local changes with the remote version of the file.
+ ///
+ /// If a conflict occurs, the file manager stores the local changes as an alternate version.
+ /// Only use this behavior if you provide a separate means of resolving and merging conflicts.
NSFileManagerResumeSyncBehaviorDropLocalChanges = 2,
} API_AVAILABLE(ios(26.0), macos(26.0), visionos(26.0)) API_UNAVAILABLE(watchos, tvos);
-/* Asynchronously resumes the sync on a paused file using the given resume behavior.
- */
+/// Asynchronously resumes the sync on a paused item using the given resume behavior.
+///
+/// Always call this method when your app closes an item to allow the file provider to sync local changes back to the server.
+///
+/// In most situations, the ``NSFileManagerResumeSyncBehavior/preserveLocalChanges`` behavior is the best choice to avoid any risk of data loss.
+///
+/// The resume call fails with ``CocoaError/featureUnsupported`` if `url` isn't currently paused.
+/// If the device isn't connected to the network, the call may fail with ``NSFileWriteUnknownError-enum.case``, with the underlying error of <doc://com.apple.documentation/documentation/FileProvider/NSFileProviderError/serverUnreachable>.
+///
+/// - Parameters:
+/// - url: The URL of the item for which to resume sync.
+/// - behavior: A ``NSFileManagerResumeSyncBehavior`` value that tells the file manager how to handle conflicts between local and remote versions of files.
+/// - completionHandler: A closure or block that the framework calls when the resume action completes. It receives a single ``NSError`` parameter to indicate an error that prevented the resume action; the value is `nil` if the resume succeeded. In Swift, you can omit the completion handler and catch the thrown error instead.
- (void)resumeSyncForUbiquitousItemAtURL:(NSURL *)url withBehavior:(NSFileManagerResumeSyncBehavior)behavior completionHandler:(void (NS_SWIFT_SENDABLE ^)(NSError * _Nullable error))completionHandler API_AVAILABLE(ios(26.0), macos(26.0), visionos(26.0)) API_UNAVAILABLE(watchos, tvos);
-/* Asynchronously fetches the latest remote version of a given item on the server and returns it in the completionHandler as a NSFileVersion.
-
- If the sync of an item is not paused, the live file will be updated with the latest remote version and the NSFileVersion will be +[NSFileVersion currentVersionOfItemAtURL:].
- If the sync of an item is paused and there are no changes on the server, the NSFileVersion will point at the live URL.
- If the sync of an item is paused and there are newer changes on the server, the NSFileVersion will point to a side location. In that case, the app can use the NSFileVersion and -[NSFileVersion replaceItemAtURL:options:error:] to replace the live version.
- */
+/// Asynchronously fetches the latest remote version of a given item from the server.
+///
+/// Use this method if uploading fails due to a version conflict and sync is paused.
+/// In this case, fetching the latest remote version allows you to inspect the newer item from the server, resolve the conflict, and resume uploading.
+///
+/// The version provided by this call depends on several factors:
+/// * If there is no newer version of the file on the server, the caller receives the current version of the file.
+/// * If the server has a newer version and sync isn't paused, this call replaces the local item and provides the version of the new item.
+/// * If the server has a newer version but sync is paused, the returned version points to a side location. In this case, call ``NSFileVersion/replaceItem(at:options:)`` on the provided version object to replace the local item with the newer item from the server.
+///
+/// If the device isn't connected to the network, the call may fail with ``NSFileReadUnknownError-enum.case``, with the underlying error of <doc://com.apple.documentation/documentation/FileProvider/NSFileProviderError/serverUnreachable>.
+///
+/// - Parameters:
+/// - url: The URL of the item for which to check the version.
+/// - completionHandler: A closure or block that the framework calls when the fetch action completes. It receives parameters of types ``NSFileVersion`` and ``NSError``. The error is `nil` if fetching the remote version succeeded; otherwise it indicates the error that caused the call to fail. In Swift, you can omit the completion handler, catching any error in a `do`-`catch` block and receiving the version as the return value.
- (void)fetchLatestRemoteVersionOfItemAtURL:(NSURL *)url completionHandler:(void (NS_SWIFT_SENDABLE ^)(NSFileVersion * _Nullable latestRemoteVersion, NSError * _Nullable error))completionHandler API_AVAILABLE(ios(26.0), macos(26.0), visionos(26.0)) API_UNAVAILABLE(watchos, tvos);
-/* Conflict resolution policies when uploading a local version of an item.
- */
+/// The policies the file manager can apply to resolve conflicts when uploading a local version of a file.
typedef NS_ENUM(NSInteger, NSFileManagerUploadLocalVersionConflictPolicy) {
- /* Solves a conflict using the provider-defined policy.
- */
+ /// Resolves the conflict using the policy defined by the file provider.
NSFileManagerUploadConflictPolicyDefault = 0,
- /* Fails the upload with a NSFileProviderErrorLocalVersionConflictingWithServer underlying error if the version on top of which the local changes have been applied doesn't match the server version of the file.
- If the server version of the file differs from the one on which the changes are based, the app will have to call [NSFileManager fetchLatestRemoteVersionOfItemAtURL:completionHandler:], rebase the local changes on top of the server version and try again.
-
- Only available on paused items that have NSSupportsFailUploadOnConflict set to 1.
- */
+ /// Resolves the conflict by causing the upload to fail.
+ ///
+ /// This policy causes an upload to fail if the local version of a file, with any local changes applied, doesn't match the server version.
+ /// In this scenario, call ``FileManager/fetchLatestRemoteVersionOfItem(at:completionHandler:)``, rebase local changes on top of the newly fetched version, and retry the upload.
+ ///
+ /// This policy is only available on paused items for which the file provider supports the fail-on-conflict behavior.
+ /// To check that the file provider supports the behavior, get the ``NSURLUbiquitousItemSupportedSyncControlsKey`` URL resource and verify that ``NSFileManagerSupportedSyncControls/failUploadOnConflict`` is `true`.
NSFileManagerUploadConflictPolicyFailOnConflict = 1,
} API_AVAILABLE(ios(26.0), macos(26.0), visionos(26.0)) API_UNAVAILABLE(watchos, tvos);
-/* Asynchronously uploads the local version of the paused item using the provided conflict resolution policy. If the upload succeeds, the uploaded NSFileVersion is sent back in the completionHandler. If the item is not paused, the call will fail with NSFeatureUnsupportedError.
-*/
+/// Asynchronously uploads the local version of the item using the provided conflict resolution policy.
+///
+/// Once your app pauses a sync for an item, call this method every time your document is in a stable state.
+/// This action keeps the server version as up-to-date as possible.
+///
+/// If the server has a newer version than the one to which the app made changes, uploading fails with ``NSFileWriteUnknownError-enum.case``, with an underlying error of <doc://com.apple.documentation/documentation/FileProvider/NSFileProviderError/localVersionConflictingWithServer>.
+/// In this case, call ``FileManager/fetchLatestRemoteVersionOfItem(at:completionHandler:)``, rebase local changes on top of that version, and retry the upload.
+///
+/// If the device isn't connected to the network, the call may fail with ``NSFileWriteUnknownError-enum.case``, with the underlying error of <doc://com.apple.documentation/documentation/FileProvider/NSFileProviderError/serverUnreachable>.
+///
+/// - Parameters:
+/// - url: The URL of the item for which to check the version.
+/// - conflictResolutionPolicy: The policy the file manager applies if the local and server versions conflict.
+/// - completionHandler: A closure or block that the framework calls when the upload completes. It receives parameters of types ``NSFileVersion`` and ``NSError``. The error is `nil` if fetching the remote version succeeded; otherwise it indicates the error that caused the call to fail. In Swift, you can omit the completion handler, catching any error in a `do`-`catch` block and receiving the version as the return value.
- (void)uploadLocalVersionOfUbiquitousItemAtURL:(NSURL *)url withConflictResolutionPolicy:(NSFileManagerUploadLocalVersionConflictPolicy)conflictResolutionPolicy completionHandler:(void (NS_SWIFT_SENDABLE ^)(NSFileVersion * _Nullable uploadedVersion, NSError * _Nullable error))completionHandler API_AVAILABLE(ios(26.0), macos(26.0), visionos(26.0)) API_UNAVAILABLE(watchos, tvos);
/* Asynchronously returns a dictionary of zero or more NSFileProviderService instances, which enable your application to instruct the file's provider to take various actions on or with regards to the given URL. To do this, first identify an NSFileProviderService object whose name matches the service you wish to use. Then get an NSXPCConnection from it and set up its NSXPCInterface with the protocol that matches the service's name. You'll need to refer to external documentation or an SDK supplied by the provider to get this information. Once an NSXPCConnection is obtained, you must finish configuring it and send it -resume. Failure to do so will result in leaking system resources.