Struct NSFileProviderManager 

#[repr(C)]
pub struct NSFileProviderManager { /* private fields */ }

Available on crate feature Extension only.

The file provider manager allows you to communicate with the file provider framework from both the extension and related processes.

NSFileProviderManager can be used from the following processes:

• the extension
• the main app containing the extension
• sibling extensions to the extension
• executables contained in the main app bundle (on macOS only)

Executables contained in the main app bundle need to have a bundle identifier that is prefixed by the bundle identifier of the main app (note that this is generally required for extensions). They must also have access to the document group defined for the provider (via its NSExtensionFileProviderDocumentGroup key).

The file provider framework will invoke your file provider extension in response to those calls if appropriate.

The class also provides methods to manage provider domains. Each domain has a corresponding manager.

See also Apple’s documentation

Implementations

impl NSFileProviderManager

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn defaultManager() -> Retained<NSFileProviderManager>

Return the manager responsible for the default domain.

pub unsafe fn managerForDomain( domain: &NSFileProviderDomain, ) -> Option<Retained<Self>>

Available on crate feature NSFileProviderDomain only.

Return the manager for the specified domain.

pub unsafe fn signalEnumeratorForContainerItemIdentifier_completionHandler( &self, container_item_identifier: &NSFileProviderItemIdentifier, completion: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Call this method either in the app or in the extension to trigger an enumeration, typically in response to a push.

When using NSFileProviderExtension, the system will enumerate containers while the user is viewing them in the UI. If there are changes to the container while an enumerator is open, call this method with the identifier of that container. This will trigger another call to -[NSFileProviderEnumerator enumerateChangesForObserver:fromSyncAnchor:] on that enumerator, and the UI will be refreshed, giving the user live updates on the presented enumeration.

If there are changes in the working set, call this method with containerItemIdentifier set to NSFileProviderWorkingSetContainerItemIdentifier, even if there is no live enumeration for the working set container.

When using NSFileProviderReplicatedExtension, only call this method with NSFileProviderWorkingSetContainerItemIdentifier. Other container identifiers are ignored. The system will automatically propagate working set changes to the UI, without explicitly signaling the containers currently being viewed in the UI.

In addition to using this method, your application/extension can register for pushes using the PKPushTypeFileProvider push type. Pushes of the form { “container-identifier”: “”, “domain”: “” } with a topic of “.pushkit.fileprovider” will be translated into a call to signalEnumeratorForContainerItemIdentifier:completionHandler:.

pub unsafe fn getUserVisibleURLForItemIdentifier_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSURL, *mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Return the security scoped URL to the user visible location for an item identifier.

The caller must use file coordination (see NSFileCoordinator) if it wishes to read the content or list the children of the URL. The caller should not try to manipulate files in the user visible location. All changes coming from the provider should go through updates in the working set that will be applied to the user visible items by the system.

The location may differ from the logical parentURL/filename. If an item on disk cannot be assigned the requested name (e.g. because the local file system has different case collision rules from the provider), one of the items can be assigned a different local name. In that case, the “com.apple.fileprovider.before-bounce#P” extended attribute will contain the filename before collision resolution. This attribute is only set if the item has been assigned a different local name following a collision. Such local names are not synced up to the provider; the purpose of the attribute is to enable consistency checkers to detect this case.

Before accessing the content of the returned URL, the caller must call -[NSURL startAccessingSecurityScopedResource] on the returned URL and call -[NSURL stopAccessingSecurityScopedResource]` when done accessing the content.

The returned URL grants read-write access to the user visible location for the corresponding item.

On iOS, for replicated domains, the extension process will never be granted access to the user visible location, this function will always fail with NSFileReadNoPermissionError.

pub unsafe fn getIdentifierForUserVisibleFileAtURL_completionHandler( url: &NSURL, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItemIdentifier, *mut NSFileProviderDomainIdentifier, *mut NSError)>, )

Available on crate features NSFileProviderDomain and NSFileProviderItem and block2 only.

Return the identifier and domain for a user visible URL.

This method returns the identifier and domain of a user visible URL if applicable. Calling this method on a file which doesn’t reside in your provider/domain, or which hasn’t yet been assigned an identifier by the provider will return the Cocoa error NSFileNoSuchFileError.

pub unsafe fn registerURLSessionTask_forItemWithIdentifier_completionHandler( &self, task: &NSURLSessionTask, identifier: &NSFileProviderItemIdentifier, completion: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Registers the given NSURLSessionTask to be responsible for the specified item. A given item can only have one task registered at a time. The task must be suspended at the time of calling. The task’s progress is displayed on the item when the task is executed.

pub unsafe fn providerIdentifier(&self) -> Retained<NSString>

The purpose identifier of your file provider extension. A coordination using a file coordinator with this purpose identifier set will not trigger your file provider extension. You can use this to e.g. perform speculative work on behalf of the file provider from the main app.

pub unsafe fn documentStorageURL(&self) -> Retained<NSURL>

The root URL for provided documents. This URL is derived by consulting the NSExtensionFileProviderDocumentGroup property on your extension. The document storage URL is the folder “File Provider Storage” in the corresponding container.

If the NSExtensionFileProviderDocumentGroup property is not set, calling this method will result in an error.

pub unsafe fn temporaryDirectoryURLWithError( &self, ) -> Result<Retained<NSURL>, Retained<NSError>>

A temporary directory suitable to store files that will be exchanged with the system.

The returned URL is guaranteed to be on the same volume as the user visible URL, making sure the system can atomatically clone/move files from that location to the user visible URL. The provider can also use that directory as a target for moves and clones of content URL passed to createItemBasedOnTemplate or modifyItem.

If the system cannot find a suitable directory, this calls will fail. This could happen e.g. if the domain does not exist or is in instance of initialization.

This call succeeds when called from the extension process with an instance of the extension for the domain unless domain was disconnected by -[NSFileProviderExternalVolumeHandling shouldConnectExternalDomainWithCompletionHandler:]. It can also fail in the extension process if the domain (external) is being setup for the very first time (meaning it never existed).

pub unsafe fn writePlaceholderAtURL_withMetadata_error( placeholder_url: &NSURL, metadata: &NSFileProviderItem, ) -> Result<(), Retained<NSError>>

Available on crate feature NSFileProviderItem only.

Writes out a placeholder at the specified URL. The placeholder is used in place of the actual file for operations that do not require the file’s actual data to be on disk:

• if attributes are requested by an application via the getPromisedItemResourceValue: method on NSURL
• or via a coordination with the NSFileCoordinatorReadingImmediatelyAvailableMetadataOnly flag set
• to verify whether an application has access to a file

Your extension should provide placeholders by implementing the providePlaceholderAtURL: method, but your application may choose to proactively write out placeholders to facilitate access to files. This is especially useful if your application wants to actively hand out a file URL, e.g. using UIActivityViewController, in which case it should ensure that either the file or a placeholder is present on disk first.

The path of the placeholder is fixed and must be determined in advance by calling the placeholderURLForURL: method.

pub unsafe fn placeholderURLForURL(url: &NSURL) -> Retained<NSURL>

Returns the designated placeholder URL for a given file URL. Used in conjunction with writePlaceholderAtURL.

pub unsafe fn addDomain_completionHandler( domain: &NSFileProviderDomain, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderDomain and block2 only.

Register a domain in which items can be stored.

If a domain with the same identifier already exists, addDomain will update the display name and hidden state of the domain and succeed.

When the domain is backed by a NSFileProviderReplicatedExtension, the system will create a disk location where the domain will be replicated. If that location already exists on disk this call will fail with the code NSFileWriteFileExistsError.

pub unsafe fn removeDomain_completionHandler( domain: &NSFileProviderDomain, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderDomain and block2 only.

Remove a domain.

pub unsafe fn removeDomain_mode_completionHandler( domain: &NSFileProviderDomain, mode: NSFileProviderDomainRemovalMode, completion_handler: &DynBlock<dyn Fn(*mut NSURL, *mut NSError)>, )

Available on crate features NSFileProviderDomain and block2 only.

Remove a domain with options

pub unsafe fn getDomainsWithCompletionHandler( completion_handler: &DynBlock<dyn Fn(NonNull<NSArray<NSFileProviderDomain>>, *mut NSError)>, )

Available on crate features NSFileProviderDomain and block2 only.

Get all registered domains.

pub unsafe fn removeAllDomainsWithCompletionHandler( completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Remove all registered domains.

pub unsafe fn signalErrorResolved_completionHandler( &self, error: &NSError, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Calling this method will cause the system to cancel throttling on every item which has been throttled due to the given error.

This call supports the following errors:

• NSFileProviderErrorNotAuthenticated
• NSFileProviderErrorInsufficientQuota
• NSFileProviderErrorServerUnreachable
• NSFileProviderErrorCannotSynchronize
• NSFileProviderErrorExcludedFromSync

pub unsafe fn globalProgressForKind( &self, kind: &NSProgressFileOperationKind, ) -> Retained<NSProgress>

Returns the global progress for the specified kind of operations

This progress tracks all the ongoing kind of operations (from disk to the provider). Uploading operations are the operations from disk to the provider. Downloading operations are the operations from the provider to the disk.

The global progress exposes the two following data:

• Number of items with an ongoing matching kind operation along with the grand total;
• Number of bytes already transferred along with the total amount of bytes to transfer.

totalUnitCount will only be reset when there are no operations left. If new operations of the matching kind arrive while the global progress is already ongoing, they will just be summed to the existing global progress.

By default, when no matching kind operations are active, the progress has its values set to 1 and its state set to finished.

The progress will be updated on the main queue. It is to be retained by the caller and to be observed through KVO.

The two only supported values for kind are:

• NSProgressFileOperationKindUploading
• NSProgressFileOperationKindDownloading

The returned progress will have its fileOperationKind property set.

impl NSFileProviderManager

Methods declared on superclass NSObject.

pub unsafe fn new() -> Retained<Self>

impl NSFileProviderManager

MaterializedSet.

pub unsafe fn enumeratorForMaterializedItems( &self, ) -> Retained<ProtocolObject<dyn NSFileProviderEnumerator>>

Available on crate feature NSFileProviderEnumerating only.

Returns an enumerator for the set of materialized items.

When calling -[NSFileProviderEnumerator enumerateItemsForObserver:startingAtPage:] on the returned enumerator, pass the result of [NSData new] as the starting page. The sorting page constants (NSFileProviderInitialPageSortedByName and NSFileProviderInitialPageSortedByDate) will not influence the order of the items enumerated from the materialized set.

This enumerator is unlike other enumerators because the roles of the system and the app/extension are reversed:

• The system enumerates the working set after the extension calls ‘signalEnumeratorForContainerItemIdentifier’;
• The app/extension enumerates the materialized set after the system calls ‘materializedItemsDidChangeWithCompletionHandler’.

impl NSFileProviderManager

PendingSet.

pub unsafe fn enumeratorForPendingItems( &self, ) -> Retained<ProtocolObject<dyn NSFileProviderPendingSetEnumerator>>

Available on crate feature NSFileProviderEnumerating only.

Returns an enumerator for the set of pending items.

This enumerator behaves like the materialized set enumerator. On later modifications in the set, the system will call ‘pendingItemsDidChangeWithCompletionHandler’.

impl NSFileProviderManager

Import.

pub unsafe fn importDomain_fromDirectoryAtURL_completionHandler( domain: &NSFileProviderDomain, url: &NSURL, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderDomain and block2 only.

Request the creation of a new domain that will take ownership of on-disk data that were previously managed without a file provider.

You can use this method in order to migrate from a software that managed a file hierarchy on disk to a NSFileProviderExtension without having to redownload the data that was already on disk.

The URL is expected to point to a directory. That directory will be moved away, its ownership being taken by the system. From this point, your extension’s createItemFromTemplate method will be called for every item found in the directory with the special NSFileProviderCreateItemMayAlreadyExist option.

In case a domain with the same name already exists in the file provider manager, the call will fail with the code NSFileWriteFileExistsError. The URL will remain untouched. In case the system does not allow the extension to request a migration, the call will fail with NSFeatureUnsupportedError.

In case of success, the URL will become invalid and the domain will be created. The completion handler is called as soon as the domain is created. Your provider will receive calls to createItemBasedOnTemplate afterward.

When the import of the file hierarchy is finished, the system calls -[NSFileProviderExtension signalDidFinishImportingItemsFromDiskWithCompletionHandler:]. In case -[NSFileProviderManager reimportItemsBelowItemWithIdentifier:completionHandler:] is called before the end of the import, a single call to importDidFinishWithCompletionHandler will be received for both the import and the scan.

pub unsafe fn reimportItemsBelowItemWithIdentifier_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Notify the system that the itemIdentifiers known by the system are not valid anymore.

This can be called by an extension in case it has lost track of its synchronisation state and as a consequence is not able to guarantee the stability of the itemIdentifiers anymore. In that case, the system will trigger a scan of any data that is cached on disk and call createItemBasedOnTemplate with the special NSFileProviderCreateItemMayAlreadyExist option so that the extension can specify the new itemIdentifier for those items. The provided item identifier is inclusive, meaning the specified item will be re-import as well as any children in case it is a container.

In case the extension has lost its synchronisation state but is still able to guarantee the stability of the itemIdentifiers, it should make sure that querying the working set enumerator with an anchor that predates the synchronisation loss will cause a NSFileProviderErrorSyncAnchorExpired error.

In case the extension has lost its synchronisation state and is not interested in preserving the data cached on disk, it can remove and re-add the affected domain.

The completion handler is called as soon as the reimport is initiated and does not not reflect the end of the import. When the import of the file hierarchy is finished, the system calls -[NSFileProviderExtension importDidFinishWithCompletionHandler:].

In some circumstances, in particular in case the requested item is the root item, calling reimport will cause the system to stop the extension process. If the call is initiated from the extension, the system does not guarantee that the completion handler will be called before the extension is stopped. When called on the root item, reimport will cause the system to rebuild its backing store for the domain. See -[NSFileProviderDomain backingStoreIdentity].

If this method succeeds, the system will reimport at least the requested sub-tree, but may import more.

If the requested item has no on-disk representation, the completion handler will be called with a NSFileProviderErrorNoSuchItem error. The same error will be reported if the reimport request happens quickly after a previous import / reimport and the corresponding item hasn’t been reimported yet.

pub unsafe fn requestModificationOfFields_forItemWithIdentifier_options_completionHandler( &self, fields: NSFileProviderItemFields, item_identifier: &NSFileProviderItemIdentifier, options: NSFileProviderModifyItemOptions, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and NSFileProviderModifyItemOptions and block2 only.

Request that the system schedules a call to -[NSFileProviderReplicatedExtension modifyItem:] for the given item identifier. The fields passed to modifyItem will contain at least the set requested via the fields parameter. The completion handler is called when the system has persisted the request. There is no guarantee as to when the modifyItem call will be scheduled. The completion handler may be called with an error. If the provider passes the .content field when the item is not downloaded, or when the item is a folder, then the system will return CocoaError(.ubiquitousFileUnavailable).

impl NSFileProviderManager

Eviction.

pub unsafe fn evictItemWithIdentifier_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Request that the system remove an item from its cache.

When called on a file, the file will be made dataless.

When called on a directory, first each of the directory’s children will be evicted (child files are made dataless, child directories are recursively evicted). Then the directory itself will be made dataless. If a non-evictable child is encountered, eviction will stop immediately and the completionHandler will be called with the NSFileProviderErrorNonEvictableChildren error. The error will include information on why and which children could not be evicted in -[NSError underlyingErrors].

The materialization state of the remaining items may be either materialized or evicted, depending on the traversal order.

The completion handler is called after the items have been evicted from disk or immediately when an error occurs.

Eviction might fail with the following errors :

• NSFileProviderErrorDomain.NSFileProviderErrorUnsyncedEdits if the item had non-uploaded changes.
• NSFileProviderErrorDomain.NSFileProviderErrorNonEvictable if the item has been marked as non-purgeable by the provider.
• NSPOSIXErrorDomain.EBUSY : if the item has open file descriptors on it.
• NSPOSIXErrorDomain.EMLINK : if the item has several hardlinks.
• other NSPOSIXErrorDomain error codes if the system was unable to access or manipulate the corresponding file.

impl NSFileProviderManager

Barrier.

pub unsafe fn waitForChangesOnItemsBelowItemWithIdentifier_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Wait for all changes on disk in the sub-hierarchy of the item to be acknowledged by the extension.

This call can be used to guarantee operation ordering in a sub-hierarchy of the provider. The completion handler is called when all the changes for descendents of the item have been acknowledged by the extension. If any error is met during that process, an error will be raised, in which case the caller should not assume all the changes have been received.

This call will only wait for changes affecting items that were already descendents of the requested item in the provider, or items that have been newly created on disk. It will not wait for items that are already known from the provider and are being moved in the directory. As a consequence, that call can be used from within a call to -[NSFileProviderReplicatedExtension modifyItem:baseVersion:changedFields:contents:options:completionHandler:]. Also note that the call will return immediately on items that are not directories.

In case a change cannot be applied to the provider, the call will fail with NSFileProviderErrorCannotSynchronize including the NSFileProviderErrorItemKey with the identifier of the item that could not be synced if that item is known by the provider.

impl NSFileProviderManager

Stabilization.

pub unsafe fn waitForStabilizationWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Wait for stabilization of the domain.

The system will wait until it is caught up with the file system’s changes up to the time of the call, then wait until it is caught up with the provider’s changes up to the time of the call.

The completion handler is called when both sets of changes are caught up to at least the time of the call. This is useful to enforce a consistent state for testing.

impl NSFileProviderManager

Disconnection.

pub unsafe fn disconnectWithReason_options_completionHandler( &self, localized_reason: &NSString, options: NSFileProviderManagerDisconnectionOptions, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

pub unsafe fn reconnectWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

impl NSFileProviderManager

Materialize.

pub unsafe fn requestDownloadForItemWithIdentifier_requestedRange_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, range_to_materialize: NSRange, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Request that the system schedule a download for an item.

The completion handler is called when the system acknowledges the download request, or with an error indicating why it didn’t (e.g NSFileProviderErrorNoSuchItem.) The system will then call -fetchContentsForItemWithIdentifier at the earliest convenient time.

Set rangeToMaterialize to NSMakeRange(offset, nbytes) to request a partial download. The system will then invoke -fetchPartialContentsForItemWithIdentifier instead of fetchContentsForItemWithIdentifier. For a full download, set rangeToMaterialize to NSMakeRange(NSNotFound, 0). -[NSFileProviderManager evictItemWithIdentifier:completionHandler:] must be called on a partially materialized file before requesting an extent to be downloaded from a later version of the file.

This method cannot be used to download directories recursively. When invoked on a dataless directory, it will trigger an enumeration of the directory, causing a materialization of the directory one level down only. All the children of the directory will remain dataless after the enumeration.

impl NSFileProviderManager

StateDirectory.

pub unsafe fn stateDirectoryURLWithError( &self, ) -> Result<Retained<NSURL>, Retained<NSError>>

A directory suitable for storing state information for the domain.

The returned URL is guaranteed to be on the same volume as the user visible URL and the temporary URL, making sure the system can atomatically clone/move files from that location to the user visible URL. The caller is responsible for managing the security scope of the returned URL.

When syncing a domain on an external volume, all information about the sync state must be kept in this directory if the volume is to be shared between multiple machines.

If the system cannot find a suitable directory, this call will fail. This could happen e.g. if the domain does not exist or is in instance of initialization.

This call will not fail when called from the extension process with an active instance of the extension for that domain unless the domain is being setup for the very first time (meaning it never existed).

Removing the domain will remove the corresponding directory along with it.

impl NSFileProviderManager

ExternalDomain.

pub unsafe fn checkDomainsCanBeStored_onVolumeAtURL_unsupportedReason_error( eligible: NonNull<Bool>, url: &NSURL, unsupported_reason: *mut NSFileProviderVolumeUnsupportedReason, ) -> Result<(), Retained<NSError>>

Check if a URL is eligible for storing a domain.

This returns whether the check has been performed succesfully - NOT whether the drive is eligible.

If an error was encountered while checking, this method returns FALSE and an error describing the problem will be set.

The eligible parameter will contain the result of the check and indicate whether the volume can be used to store FP domains. Its value is only defined if the call returns YES.

The url can be any existing and accessible URL on the volume for which you want to assess eligibility. The checks are volume-wide and the exact location on the volume doesn’t impact them.

If a drive is eligible, unsupportedReason will be empty (0). Otherwise it will contain the list of identified conditions that currently prevent this drive from being used to store FP domains.

impl NSFileProviderManager

Diagnostics.

pub unsafe fn requestDiagnosticCollectionForItemWithIdentifier_errorReason_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, error_reason: &NSError, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderItem and block2 only.

Request diagnostics collection for the item.

This will prompt the user about an issue with the sync in the provider and ask their permission to collection diagnostic information and to send them to Apple for further analysis.

This call is to be used wisely with care given there’s global throttling on it preventing spamming the users. Furthermore it should be used in collaboration with Apple when you detect a misbehavior in the sync in your provider likely caused by a system bug and you need to work with Apple in order to resolve it.

This will return whether the call was allowed or not - not if it suceed This method will only return an error if the user was not on a Seed build

It is mandatory to provide an error for the item why the collection is requested. The error won’t be shown to the user (a generic message will be shown instead) It will surface in the generated report though

It is important to note that even if the call is allowed, it might not trigger diagnostic collection nor prompt to the user depending on the system state and other throttling parameters

impl NSFileProviderManager

KnownFolders.

pub unsafe fn claimKnownFolders_localizedReason_completionHandler( &self, known_folders: &NSFileProviderKnownFolderLocations, localized_reason: &NSString, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderKnownFolders and block2 only.

Request the specified known folders to be synced by this domain.

This method allows the provider to claim a set of known folders described by the non-null properties of the knownFolders parameter. The system will only enable sync for those folders in that domain if the set of locations is valid and if the user agrees.

This API should only be called as a result of the user requesting, via UI in the provider’s application, that they wish to start syncing the Desktop and Document folders. If the provider chooses to implement a UI which invokes this API, the provider should also implement a UI for the user to request to stop syncing the Desktop and Document folders, using the -[NSFileProviderManager releaseKnownFolders:localizedReason:completionHandler:] method.

The reason specified in this call is a custom string that the provider can pass and will be presented to the user as a way to explain why it is claiming those known folders. One suggested phrasing would be:

Keep your Desktop & Documents in sync with and access them from other devices and from .

If the user denies the transition of the known folders, the call will fail with NSUserCancelledError.

The call will fail if:

• one or more locations are not folders
• multiple locations are backed by the same folder
• a known folder doesn’t live on the same volume as the root of the domain
• the known folders don’t have the same parent folder
• …

Currently, only claiming both ~/Desktop and ~/Documents together is allowed.

pub unsafe fn releaseKnownFolders_localizedReason_completionHandler( &self, known_folders: NSFileProviderKnownFolders, localized_reason: &NSString, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features NSFileProviderKnownFolders and NSFileProviderDomain and block2 only.

Request that the system stops replicating the specified known folders in the domain.

This call can be used by the provider to immediately disable replication of the specified known folders.

impl NSFileProviderManager

NSFileProviderService.

pub unsafe fn getServiceWithName_itemIdentifier_completionHandler( &self, service_name: &NSFileProviderServiceName, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderService, *mut NSError)>, )

Available on crate features NSFileProviderService and NSFileProviderItem and block2 only.

Retrieve the service with the specified named for the specified item.

impl NSFileProviderManager

TestingModeInteractive. Control the scheduling of operation.

These methods are available on domain with the NSFileProviderDomainTestingModeInteractive enabled.

In order to manually schedule the operation, the testing harness will first call -listAvailableTestingOperationWithError and get a list of operations that can be scheduled. It can pick one or more operations from that list and call -runTestingOperations:error: to schedule those operations.

From that point, it should get the new list of available operations and iterate between listing, picking operation, running those operation and so on.

A process must have the com.apple.developer.fileprovider.testing-mode entitlement in order to call the methods from this category.

pub unsafe fn listAvailableTestingOperationsWithError( &self, ) -> Result<Retained<NSArray<ProtocolObject<dyn NSFileProviderTestingOperation>>>, Retained<NSError>>

Available on crate feature NSFileProviderTesting only.

List the available operations.

This lists all of the operations that are ready to be scheduled by the system. The system waits for all the pending disk and working set updates to be known before returning.

The operations that are returned may become invalid if the system receives new disk or working set events, or if some operation are scheduled using -runTestingOperations:error:.

pub unsafe fn runTestingOperations_error( &self, operations: &NSArray<ProtocolObject<dyn NSFileProviderTestingOperation>>, ) -> Result<Retained<NSDictionary<ProtocolObject<dyn NSFileProviderTestingOperation>, NSError>>, Retained<NSError>>

Available on crate feature NSFileProviderTesting only.

Run a set of operations.

Ask the system to schedule the execution of the listed operations. The system will wait until all those operations have completed and report a per-operation error in case an operation fails.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for NSFileProviderManager

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSFileProviderManager> for NSFileProviderManager

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for NSFileProviderManager

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for NSFileProviderManager

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSFileProviderManager

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSFileProviderManager

const NAME: &'static str = "NSFileProviderManager"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<NSFileProviderManager as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for NSFileProviderManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for NSFileProviderManager

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for NSFileProviderManager

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for NSFileProviderManager

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSFileProviderManager

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for NSFileProviderManager

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for NSFileProviderManager

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for NSFileProviderManager

impl Eq for NSFileProviderManager