Trait NSFileProviderPartialContentFetching

Source

pub unsafe trait NSFileProviderPartialContentFetching: NSObjectProtocol {
    // Provided method
    unsafe fn fetchPartialContentsForItemWithIdentifier_version_request_minimalRange_aligningTo_options_completionHandler(
        &self,
        item_identifier: &NSFileProviderItemIdentifier,
        requested_version: &NSFileProviderItemVersion,
        request: &NSFileProviderRequest,
        requested_range: NSRange,
        alignment: NSUInteger,
        options: NSFileProviderFetchContentsOptions,
        completion_handler: &DynBlock<dyn Fn(*mut NSURL, *mut NSFileProviderItem, NSRange, NSFileProviderMaterializationFlags, *mut NSError)>,
    ) -> Retained<NSProgress>
       where Self: Sized + Message { ... }
}

Available on crate feature NSFileProviderReplicatedExtension only.

Expand description

Apple’s documentation

Provided Methods§

Source

unsafe fn fetchPartialContentsForItemWithIdentifier_version_request_minimalRange_aligningTo_options_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, requested_version: &NSFileProviderItemVersion, request: &NSFileProviderRequest, requested_range: NSRange, alignment: NSUInteger, options: NSFileProviderFetchContentsOptions, completion_handler: &DynBlock<dyn Fn(mut NSURL, mut NSFileProviderItem, NSRange, NSFileProviderMaterializationFlags, *mut NSError)>, ) -> Retained<NSProgress>
where Self: Sized + Message,

Available on crate features NSFileProviderItem and NSFileProviderRequest and block2 only.

Download the requested extent of an item for the given identifier and return it via the completion handler. If this protocol is not implemented the system defaults to fetchContentsForItemWithIdentifier.

The requestedVersion parameter specifies which version should be returned. This version will always be specified by the system so as to prevent extents from different versions from being written into the same file. The system tolerates a version mismatch for the first materialization of a fully dataless file (strictVersion=NO).

The requested range is <location , length>. The implementation can provide any properly aligned range that covers the requested range (including the entire item). The system provides the minimal alignment value. The location (or start offset) of the fetched range should be a multiple of this value for it to be considered properly aligned. The length of the fetched range should be a multiple of this value, with an exception for the end of the file, checked against the documentSize attribute the implementation supplied for this item. The alignment value should not be expected to be stable across reboots. It is guaranteed by the system to be a power of two. In addition to the content the extension needs to fill in fetchedRange with either the requestest range, <location , length>, or indicate full materialization with, < 0, file size>.

§On-disk layout:

The retrieved content at fileContents URL must be a regular file on the same volume as the user-visible URL. A suitable location can be retrieved using -[NSFileProviderManager temporaryDirectoryURLWithError:]. The file contents outside of the fetched range are ignored by the system. The system only requires the file to be at least as large as the end of the fetched range. For instance, if the fetchedRange is {offset:0x100000, length:0x1000}, the file size must be at least 0x101000 bytes. Any data (or lack thereof) beyond the fetched range is ignored.

The fetched range must be stored in this file at the same offset as the range indicates. For instance if the retrievedRange is {offset:0x100000, length:0x1000} then it should actually be at offset 0x100000 in the fileContents file. The ranges {0, 0x100000}, and {0x101000, EOF} can be anything including sparse ranges.

§Concurrent Downloads:

The system will call fetchContents concurrently if there are multiple outstanding file download requests. The provider can control the concurrency by setting the key NSExtensionFileProviderDownloadPipelineDepth in the Info.plist of the extension to the number of concurrent downloads that the system should create per domain. This number must be between 1 and 128, inclusive.

§File ownership:

The system clones and unlinks the received fileContents. The extension should not mutate the corresponding file after calling the completion handler. If the extension wishes to keep a copy of the content, it must provide a clone of the that content as the URL passed to the completion handler.

In case the extension or the system crashes between the moment the completion handler is called and the moment the system unlinks the file, the file may unexpectedly still be on disk the next time an instance of the extension is created. The extension is then responsible for deleting that file.

§Disallowing processes from fetching items:

The system automatically downloads files on POSIX accesses. The extension may wish to disallow this class of downloads for specific applications.

The extension can set an array of strings into the UserDefault key “NSFileProviderExtensionNonMaterializingProcessNames”. A process whose executable’s filename on disk is an exact match for an entry in this array will not be allowed to fetch items in the extension’s domains. The comparison is case sensitive.

In macOS 11.0 and later, this list will be checked when a download is initiated through a POSIX filesystem call. In macOS 11.4 and later, this list will also be checked for downloads initiated through file coordination.

§Error cases:

If the download fails because the item is unknown, the call should fail with the NSFileProviderErrorNoSuchItem error. In that case, the system will consider the item has been removed from the domain and will attempt to delete it from disk. In case that deletion fails because there are local changes on this item, the system will re-create the item using createItemBasedOnTemplate.

If the user does not have access to the content of the file, the provider can fail the call with NSCocoaErrorDomain and code NSFileReadNoPermissionError. That error will then be presented to the user. The extension can also report the NSFileProviderErrorNotAuthenticated, NSFileProviderErrorServerUnreachable in case the item cannot be fetched because of the current state of the system / domain. In those cases, the system will present an appropriate error message and back off until the next time it is signalled.

If the requested version cannot be retrieved, the provider can choose to provide a different version of the file, unless NSFileProviderFetchContentsOptionsStrictVersioning is set. In this case, the provider should fail with NSFileProviderErrorVersionNoLongerAvailable. If some content is returned, the item must have the corresponding version. The system will detect any mismatch and handle it as a remote update. For the reading application, the materialization will fail with the same error as reading from a dataless file that got remotely updated (-1/errno=ESTALE). Upon retry the new version will be requested by the system.

Any other error will be considered to be transient and will cause the download to be retried.

§Cancellations:

If the NSProgress returned by this method is cancelled, the extension should call the completion handler with (nil, nil, someRange, 0, NSUserCancelledError) in the NSProgress cancellation handler.

The returned NSProgress is used to show progress to the user. If the user cancels the fetch, the extension should stop fetching the item, as it is no longer required.

§Execution time:

The system will grant enough time to the extension to download the file. The system will interrupt the call if it stops making progress or if download takes an unexpectedly long time. In that case, the system will call cancel on the progress. The extension is then expected to quickly call the completion handler.