Class

NSItemProvider

An item provider for conveying data or a file between processes during drag and drop or copy/paste activities, or from a host app to an app extension.

Declaration

@interface NSItemProvider : NSObject

Overview

Starting in iOS 11, item providers play a central role in drag and drop, and in copy/paste. They continue to play a role with app extensions.

All completion blocks used in the NSItemProvider class are called by the system on an internal queue. When using an item provider with drag and drop, ensure that user-interface updates take place on the main queue as follows:

DispatchQueue.main.async {
    // work that impacts the user interface
}

App Extension Support

An app extension typically encounters item providers when examining the attachments property of an NSExtensionItem object. During that examination, the extension can use the hasItemConformingToTypeIdentifier: method to look for data that it recognizes. Item providers use Uniform Type Identifier (UTI) values to identify the data they contain. After finding a type of data that your extension can use, it calls the loadItemForTypeIdentifier:options:completionHandler: method to load the actual data, which is delivered to the provided completion handler.

You can create item providers to vend data to another process. An extension that modifies an original data item can create a new NSItemProvider object to send back to the host app. When creating data items, you specify your data object and the type of that object. You can optionally use the previewImageHandler property to generate a preview image for your data.

A single item provider may use custom blocks to provide its data in many different formats. When configuring an item provider, use the registerItemForTypeIdentifier:loadHandler: method to register your blocks and the formats each one supports. When a client requests data in a particular format, the item provider executes the corresponding block, which is then responsible for coercing the data to the appropriate type and returning it to the client.

Topics

Initializing an Item Provider

- initWithContentsOfURL:

Provides data backed by the contents of an existing file. The system uses the URL’s filename extension to select an appropriate UTI.

- initWithItem:typeIdentifier:

Initializes an item provider with an object, according to the NSItemProvider type coercion policy.

- init

Instantiates an empty item provider to which you can later register a data or file representation.

- initWithObject:

Initializes a new item provider, employing a specified object’s type identifiers to specify the data representations eligible to be loaded by the provider.

Getting the Item’s Data

- canLoadObjectOfClass:

Returns a Boolean value indicating whether an item provider can load objects of a given class.

- hasItemConformingToTypeIdentifier:

A convenience method equivalent to the hasRepresentationConformingToTypeIdentifier:fileOptions: method, but with the fileOptions parameter set to a value of 0.

- loadItemForTypeIdentifier:options:completionHandler:

Loads the item’s data and coerces it (as needed) to the specified type.

- loadDataRepresentationForTypeIdentifier:completionHandler:

Asynchronously copies the provided, typed data into an NSData object, returning an NSProgress object.

- loadFileRepresentationForTypeIdentifier:completionHandler:

Asynchronously writes a copy of the provided, typed data to a temporary file, returning an NSProgress object.

- loadInPlaceFileRepresentationForTypeIdentifier:completionHandler:

Asynchronously opens a file in place, if doing so is possible, returning an NSProgress object.

- loadObjectOfClass:completionHandler:

Asynchronously loads an object of a specified class to an item provider, returning an NSProgress object.

- hasRepresentationConformingToTypeIdentifier:fileOptions:

Returns a Boolean value indicating whether an item provider contains a data representation conforming to a specified uniform type identifier (UTI) and to specified open-in-place behavior.

- registeredTypeIdentifiersWithFileOptions:

Returns an array with a subset of type identifiers for the item provider, according to the specified file options, listed in the same order in which they were registered.

Providing the Item’s Data

- registerDataRepresentationForTypeIdentifier:visibility:loadHandler:

Registers a data-backed representation for an item, specifiying item visibility and a load handler.

- registerFileRepresentationForTypeIdentifier:fileOptions:visibility:loadHandler:

Registers a file-backed representation for an item, specifying file options, item visibility, and a load handler.

- registerObject:visibility:

Adds representations of a specified object to an item provider, based on the object’s implementation of the NSItemProviderWriting protocol and adhering to a visibility specification.

- registerObjectOfClass:visibility:loadHandler:

Lazily adds representations of a specified object to an item provider, based on the object’s implementation of the NSItemProviderWriting protocol and adhering to a visibility specification.

suggestedName

The filename to use when writing the provided data to a file on disk.

Registering Custom Coercion Handlers

- registerItemForTypeIdentifier:loadHandler:

Lazily registers an item, according to the NSItemProvider type coercion policy.

registeredTypeIdentifiers

Returns the array of type identifiers for the item provider, listed in the same order in which they were registered.

Generating a Preview Image

- loadPreviewImageWithOptions:completionHandler:

Loads the preview image for the item that is represented by the item provider.

previewImageHandler

The custom preview image handler block for the item provider.

Getting the Visual Attributes

sourceFrame

The rectangle (in screen coordinates) occupied by the item in the host app’s source window.

containerFrame

The rectangle (in screen coordinates) of the item’s visible content.

preferredPresentationSize

The ideal presentation size of the item.

preferredPresentationStyle

The preferred style for presenting the item provider's data.

UIPreferredPresentationStyle

The presentation styles that determine how a view should show an item provider's data.

Constants

NSItemProviderCompletionHandler

A block that receives the item provider’s data.

NSItemProviderLoadHandler

A block that loads the item provider’s data and coerces it to the specified type.

Options Dictionary Key

Keys indicating options to use when generating the item provider’s data.

Keys for Items Accessed in JavaScript Code

Keys used in property list items received from or sent to JavaScript code.

NSItemProviderErrorDomain

The error domain associated with the NSItemProvider class.

NSItemProviderFileOptions

Data-access specifications that declare how items should be handled.

NSItemProviderReading

The protocol you implement on a class to allow an item provider to create an instance of the class.

NSItemProviderWriting

The protocol you implement on a class to allow an item provider to retrieve data from an instance of the class.

NSItemProviderRepresentationVisibility

Specifications that control which categories of processes can see an item.

NSItemProviderErrorCode

The error codes that describe problems with consuming data from an item provider.

Instance Properties

Relationships

Inherits From

Conforms To

See Also

Attachments

NSExtensionItem

An immutable collection of values representing different aspects of an item for an extension to act upon.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software