iOS Developer Library — Prerelease

Developer

Foundation Framework Reference NSExtensionContext Class Reference

Options
Deployment Target:

On This Page
Language:

NSExtensionContext

An NSExtensionContext object represents the host app context from which an app extension is invoked.

When a host app sends a request to an app extension, it provides an extension context. For many app extensions, the most important part of the context is the data the user wants to work with, which is contained in the inputItems property.

  • Tells the host app to cancel the app extension request, with a supplied error.

    Declaration

    Swift

    func cancelRequestWithError(_ error: NSError)

    Objective-C

    - (void)cancelRequestWithError:(NSError * nonnull)error

    Parameters

    error

    The error object to return. It must be non-nil.

    Discussion

    On return, the userInfo dictionary of the NSError object contains a key named NSExtensionItemsAndErrorsKey which has as its value a dictionary of NSExtensionItem objects and associated NSError instances.

    Availability

    Available in iOS 8.0 and later.

  • Tells the host app to complete the app extension request with an array of result items.

    Declaration

    Swift

    func completeRequestReturningItems(_ items: [AnyObject]?, completionHandler completionHandler: ((Bool) -> Void)?)

    Objective-C

    - (void)completeRequestReturningItems:(NSArray * nullable)items completionHandler:(void (^ nullable)(BOOL expired))completionHandler

    Parameters

    items

    An array of result items, each an NSExtensionItem object, to return to the host app.

    completionHandler

    An optional block to be called when the request completes, performed as a background priority task.

    The block takes the following parameter:

    expired

    A Boolean value that indicates whether the system is terminating a previous invocation of the completionHandler block.

    This parameter is YEStrue when the system prematurely terminates a completionHandler block that was previously invoked and had not otherwise expired.

    Discussion

    Calling this method eventually dismisses the app extension’s view controller.

    Availability

    Available in iOS 8.0 and later.

  • Asks the system open a URL on behalf of the currently running app extension.

    Declaration

    Swift

    func openURL(_ URL: NSURL, completionHandler completionHandler: ((Bool) -> Void)?)

    Objective-C

    - (void)openURL:(NSURL * nonnull)URL completionHandler:(void (^ nullable)(BOOL success))completionHandler

    Parameters

    URL

    The URL to open.

    completionHandler

    A block to be called when the URL has opened.

    The block takes the following parameter:

    success

    A Boolean value that indicates whether the open operation was successful.

    Discussion

    Each extension point determines whether to support this method, or under which conditions to support this method. In iOS 8, only the Today extension point (used for creating Today widgets) supports this method.

    Availability

    Available in iOS 8.0 and later.

  • The list of input NSExtensionItem objects associated with the context. (read-only)

    Declaration

    Swift

    var inputItems: [AnyObject] { get }

    Objective-C

    @property(readonly, copy, nonatomic) NSArray *inputItems

    Discussion

    If the context has no input items, this array is empty.

    Availability

    Available in iOS 8.0 and later.

  • This key is used in the userInfo dictionary of the NSError object returned by cancelRequestWithError:.

    Declaration

    Swift

    let NSExtensionItemsAndErrorsKey: String

    Objective-C

    NSString *const NSExtensionItemsAndErrorsKey;

    Constants

    • NSExtensionItemsAndErrorsKey

      NSExtensionItemsAndErrorsKey

      A key whose value is a dictionary of NSExtensionItem objects and associated NSError instances.

      Available in iOS 8.0 and later.

  • Posted when the extension’s host app moves from the inactive to the active state.

    Extensions can use this notification to adjust their activity when they become active. The object parameter contains the NSExtensionContext object. This notification does not contain a userInfo dictionary.

    Declaration

    Swift

    let NSExtensionHostDidBecomeActiveNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.2 and later.

  • Posted when the extension’s host app moves from the active to the inactive state.

    Extensions can use this notification to adjust their activity when they become inactive. For example, you might use this notification to save any unsaved data to prevent it from being lost. The object parameter contains the NSExtensionContext object. This notification does not contain a userInfo dictionary.

    Declaration

    Swift

    let NSExtensionHostWillResignActiveNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.2 and later.

  • Posted when the extension’s host app begins running in the background.

    Extensions can use this notification to stop tasks and prepare the extension to be suspended. The object parameter contains the NSExtensionContext object. This notification does not contain a userInfo dictionary.

    Extensions receive only a short amount of time to perform any background work. If you need more time to complete critical tasks, use the methods of the NSProcessInfo class to request that time.

    Declaration

    Swift

    let NSExtensionHostDidEnterBackgroundNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.2 and later.

  • Posted when the extension’s host app begins running in the foreground.

    Extensions can use this notification to restart tasks that it stopped when they moved to the background. The object parameter contains the NSExtensionContext object. This notification does not contain a userInfo dictionary.

    Declaration

    Swift

    let NSExtensionHostWillEnterForegroundNotification: String

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.2 and later.