Contents

importDocument(at:toParentItemIdentifier:completionHandler:)

Imports a file or package into the given parent directory.

Declaration

func importDocument(at fileURL: URL, toParentItemIdentifier parentItemIdentifier: NSFileProviderItemIdentifier, completionHandler: @escaping  @Sendable (NSFileProviderItem?, (any Error)?) -> Void)
func importDocument(at fileURL: URL, toParentItemIdentifier parentItemIdentifier: NSFileProviderItemIdentifier) async throws -> NSFileProviderItem

Parameters

  • fileURL:

    A security-scoped URL for the file to import. Call Startaccessingsecurityscopedresource() on the URL before accessing it and Stopaccessingsecurityscopedresource() when finished.

  • parentItemIdentifier:

    The persistent identifier for the directory where the item will be imported.

  • completionHandler:

    A block that takes the following parameters:

    importedDocumentItem

    A provider item that describes the newly imported item, or nil if an error occurred.

    error

    An error object. If an error occurs, pass in an object that describes the error; otherwise, set it to nil.

Discussion

This method is called when the user imports a document or directory. Override this method to move the file at the provided security-scoped URL to the file provider’s storage. Your implementation should return immediately. Call the completion handler before performing any network activity or other long-running tasks. Defer these tasks to the background.

The importedDocumentItem instance that you pass to the completion handler must define the following properties:

itemIdentifier

This identifier may be temporary. If you later receive a permanent identifier from your server, delete the temporary item and add the permanent one.

parentItemIdentifier

Set to the value passed to the parentItemIdentifier parameter.

filename

Set to the fileURL parameter’s nameKey resource value.

creationDate

Set to the fileURL parameter’s creationDateKey resource value.

contentModificationDate

Set to the fileURL parameter’s contentModificationDateKey resource value.

typeIdentifier

Set to the fileURL parameter’s typeIdentifierKey resource value.

documentSize

For a flat file, set to the fileURL parameter’s totalFileSizeKey resource value. For a package, set to the sum of the contents’ file sizes.

capabilities

Set to define the actions that the user can perform on the directory (for example, allowsReading and allowsWriting).

The user’s ability to import an item into a directory is controlled by the parent directory’s allowsAddingSubItems capability.

See Also

Handling actions