-
Notifications
You must be signed in to change notification settings - Fork 542
BackgroundTasks iOS xcode26.0 b1
Alex Soto edited this page Jun 9, 2025
·
1 revision
#BackgroundTasks.framework
diff -ruN /Applications/Xcode_16.4.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h /Applications/Xcode_26.0.0-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h
--- /Applications/Xcode_16.4.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h 2025-04-19 02:00:33
+++ /Applications/Xcode_26.0.0-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h 2025-05-29 02:28:43
@@ -11,82 +11,61 @@
NS_ASSUME_NONNULL_BEGIN
-/*!
- @abstract An abstract class that represents the background work for which the app was launched to handle.
- @discussion Subclasses of this type are created by the system and should not be directly instantiated.
- */
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
/// An abstract class representing a task that’s run while the app is in the
/// background.
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
@interface BGTask : NSObject
-/*!
- @abstract The identifier associated with the request used to schedule this background work.
- */
-
/// The string identifier of the task.
///
/// The identifier is the same as the one used to register the launch handler in
/// ``BGTaskScheduler/registerForTaskWithIdentifier:usingQueue:launchHandler:``.
@property (copy, readonly) NSString *identifier;
-/*!
- @abstract Called by the system shortly before your app's background time expires.
- @discussion There is a limit to how long your app has to perform its background work, and your work may need to be interrupted if system conditions change. Assign a handler to this property to cancel any ongoing tasks, perform any needed cleanup, and then call setTaskCompletedWithSuccess: to signal completion to the system and allow your app to be suspended.
- This property is cleared after it is called by the system or when setTaskCompletedWithSuccess: is called. This is to mitigate the impact of a retain cycle created by referencing the BGTask instance inside this block.
- */
-
/// A handler called shortly before the task’s background time expires.
///
-/// The time allocated by the system for expiration handlers doesn’t vary with
-/// the number of background tasks. All expiration handlers must complete before
-/// the allocated time.
+/// There is a limit to how long your app has to perform its background work, and your work may need to be interrupted
+/// if system conditions change. Assign a handler to this property to cancel any ongoing tasks, perform any needed
+/// cleanup, and then call setTaskCompletedWithSuccess: to signal completion to the system and allow your app to be
+/// suspended. This property is cleared after it is called by the system or when ``BGTask/setTaskCompletedWithSuccess:``
+/// is called. This is to mitigate the impact of a retain cycle created by referencing the BGTask instance inside this
+/// block.
///
-/// Not setting an expiration handler results in the system marking your task as
-/// complete and unsuccessful instead of sending a warning.
+/// The handler may be called before the background process uses the full amount of its allocated time.
///
-/// The manager sets the value `expirationHandler` to `nil` after the handler
-/// completes.
-///
/// - Parameters:
-/// - expirationHandler: The expiration handler takes no arguments and has no
-/// return value. Use the handler to cancel any ongoing work and to do any
-/// required cleanup in as short a time as possible.
+/// - expirationHandler: The expiration handler takes no arguments and has no return value. Use the handler to
+/// cancel any ongoing work and to do any required cleanup in as short a time as possible.
///
-/// The handler may be called before the background process uses the full amount of its
-/// allocated time.
+/// - Note: The manager sets the value `expirationHandler` to `nil` after the handler completes.
+/// - Warning: Not setting an expiration handler results in the system marking your task as complete and unsuccessful instead of sending a warning.
@property (nullable, strong) void (^expirationHandler)(void);
- (instancetype)init NS_UNAVAILABLE; // Subclasses of this abstract type are created by the system and cannot be directly instantiated
+ (instancetype)new NS_UNAVAILABLE; // Subclasses of this abstract type are created by the system and cannot be directly instantiated
-/*!
- @abstract Marks this task as complete.
- @discussion Call this method as soon as the background work associated with this task is complete. The system provides your app with a limited amount of time to finish the task. If you do not call setTaskCompletedWithSuccess: on the task, the system continues to run in the background until all the available time is consumed, wasting battery power.
- The system suspends the app as soon as all background tasks are complete.
- @param success Whether the task was completed successfully. If the task was unsuccessful, you may request the system to try again later by submitting a new task request to the scheduler before calling this method.
- */
-
-/// Informs the background task scheduler that the task is complete.
+/// Inform the background task scheduler that the task is complete.
///
-/// Not calling ``BGTask/setTaskCompletedWithSuccess:`` before the time for the
-/// task expires may result in the system killing your app.
+/// Call this method as soon as the background work associated with this task is complete. The system provides your app
+/// with a limited amount of time to finish the task. If you do not call setTaskCompletedWithSuccess: on the task, the
+/// system continues to run in the background until all the available time is consumed, wasting battery power. The
+/// system suspends the app as soon as all background tasks are complete.
///
-/// You can reschedule an unsuccessful required task.
-///
-/// - Important: If you don’t set an expiration handler, the system will mark
-/// your task as complete and unsuccessful instead of sending a warning.
-///
/// - Parameters:
-/// - success: A `Boolean` indicating if the task completed successfully or not.
+/// - success: A `Boolean` indicating if the task completed successfully or not. If the task was unsuccessful, you
+/// may request the system to try again later by submitting a new task request to the scheduler before calling this
+/// method.
+///
+/// - Important: If you don’t set an expiration handler, the system will mark your task as complete and unsuccessful
+/// instead of sending a warning.
+/// - Warning: Not calling ``BGTask/setTaskCompletedWithSuccess:`` before the time for the task expires may result in
+/// the system killing your app.
- (void)setTaskCompletedWithSuccess:(BOOL)success;
@end
-/*!
- @abstract A background task used to perform deferrable processing.
- */
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
+#pragma mark -
+
/// A time-consuming processing task that runs while the app is in the
/// background.
///
@@ -103,27 +82,25 @@
/// Processing tasks run only when the device is idle. The system terminates any
/// background processing tasks running when the user starts using the device.
/// Background refresh tasks are not affected.
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
@interface BGProcessingTask : BGTask
@end
-/*!
- @abstract A potentially time-consuming task that is required to process data essential to a health research study.
- */
-BG_EXTERN API_AVAILABLE(ios(17.0), tvos(25.0)) API_UNAVAILABLE(macos, watchos, tvos)
+#pragma mark -
+
/// A task meant to perform processing on behalf of health research studies.
///
/// Health research tasks may only be used by applications entitled to perform
/// studies and user's have opted in to the relevant study. These apps must have the
/// `com.apple.developer.backgroundtasks.healthresearch` entitlement.
+BG_EXTERN API_AVAILABLE(ios(17.0), tvos(32.0)) API_UNAVAILABLE(macos, tvos)
@interface BGHealthResearchTask : BGProcessingTask
@end
-/*!
- @abstract A background task used to update your app's contents in the background.
- */
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
+#pragma mark -
+
/// An object representing a short task typically used to refresh content that’s
/// run while the app is in the background.
///
@@ -134,7 +111,35 @@
/// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/uibackgroundmodes>
/// capability. For information on setting this capability, see
/// ``BGTaskScheduler``.
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
@interface BGAppRefreshTask : BGTask
+
+@end
+
+#pragma mark -
+
+/// A task meant to perform processing on behalf of a user initiated request.
+///
+/// Continued processing tasks will present UI while in progress to provide awareness to the user.
+/// ``BGContinuedProcessingTask``s _must_ report progress via the ``NSProgressReporting`` protocol conformance during
+/// runtime and are subject to expiration based on changing system conditions and user input. Tasks that appear stalled
+/// may be forcibly expired by the scheduler to preserve system resources.
+BG_EXTERN API_AVAILABLE(ios(26.0)) API_UNAVAILABLE(macos, tvos, visionos, watchos, macCatalyst)
+@interface BGContinuedProcessingTask : BGTask<NSProgressReporting>
+
+/// The localized title displayed to the user.
+@property (copy, readonly) NSString *title;
+
+/// The localized subtitle displayed to the user.
+@property (copy, readonly) NSString *subtitle;
+
+/// Update the title and subtitle displayed in the live activity displayed to the user.
+///
+/// - Parameters:
+/// - title: The localized title displayed to the user.
+/// - subtitle: The localized subtitle displayed to the user.
+- (void)updateTitle:(NSString *)title
+ subtitle:(NSString *)subtitle;
@end
diff -ruN /Applications/Xcode_16.4.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h /Applications/Xcode_26.0.0-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h
--- /Applications/Xcode_16.4.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h 2025-04-19 04:34:02
+++ /Applications/Xcode_26.0.0-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h 2025-05-29 01:12:50
@@ -14,7 +14,7 @@
@abstract An abstract class that represents a request for the app to be launched in the background to perform work.
@discussion Do not instantiate instances of this class directly. Instead, use one of its concrete subclasses.
*/
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
/// An abstract class for representing task requests.
@interface BGTaskRequest : NSObject <NSCopying>
/*!
@@ -42,13 +42,15 @@
+ (instancetype)new NS_UNAVAILABLE; // This is an abstract type and should not be directly instantiated
@end
+#pragma mark -
+
/*!
@abstract A request to briefly launch your app to keep its contents up to date.
@discussion Schedule a refresh task request to ask that the system launch your app briefly so that you can download data and keep your app's contents up-to-date. The system will fulfill this request intelligently based on system conditions and app usage.
*/
/// A request to launch your app in the background to execute a short refresh task.
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
@interface BGAppRefreshTaskRequest : BGTaskRequest
/// Return a new refresh task request for the specified identifier.
@@ -59,6 +61,8 @@
@end
+#pragma mark -
+
/*!
@abstract A request to launch your app to perform deferrable processing tasks.
@discussion Schedule a processing task request to ask that the system launch your app when conditions are favorable for battery life to handle deferrable, longer-running processing, such as syncing, database maintenance, or similar tasks. The system will attempt to fulfill this request to the best of its ability within the next two days as long as the user has used your app within the past week.
@@ -66,7 +70,7 @@
/// A request to launch your app in the background to execute a processing task
/// that can take minutes to complete.
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
@interface BGProcessingTaskRequest : BGTaskRequest
/// Return a new processing task request for the specified identifier.
@@ -96,9 +100,11 @@
@end
+#pragma mark -
+
/// A request to launch your app in the background to execute a health research task for studies a user has opted into and
/// that can take minutes to complete.
-BG_EXTERN API_AVAILABLE(ios(17.0), tvos(17.0)) API_UNAVAILABLE(macos, watchos)
+BG_EXTERN API_AVAILABLE(ios(17.0), tvos(17.0)) API_UNAVAILABLE(macos)
@interface BGHealthResearchTaskRequest : BGProcessingTaskRequest
/*!
@abstract What file protection state is required to access data relevant to this task.
@@ -111,6 +117,81 @@
@end
-NS_ASSUME_NONNULL_END
+#pragma mark -
+typedef NS_ENUM(NSInteger, BGContinuedProcessingTaskRequestSubmissionStrategy) {
+ /// Fail the submission if there is no room for the task request, or if the system is under substantial load and is
+ /// unable immediately run the task.
+ BGContinuedProcessingTaskRequestSubmissionStrategyFail,
+ /// Add the request to the back of a queue if there is no room for the submitted task or if the system is under
+ /// substantial load and is unable to immediately run the task. Queued ``BGContinuedProcessingTaskRequest``s will be
+ /// cancelled when the user removes your app from the app switcher.
+ BGContinuedProcessingTaskRequestSubmissionStrategyQueue
+} NS_SWIFT_NAME(BGContinuedProcessingTaskRequest.SubmissionStrategy) API_AVAILABLE(ios(26.0)) API_UNAVAILABLE(macos, tvos, visionos, watchos, macCatalyst);
+typedef NS_OPTIONS(NSInteger, BGContinuedProcessingTaskRequestResources) {
+ /// No special system resources required.
+ ///
+ /// Unless informed otherwise, the scheduler assumes the default resources, allowing background CPU and network
+ /// access.
+ BGContinuedProcessingTaskRequestResourcesDefault = 0,
+ /// Indicate to the scheduler that the workload will require background GPU utilization.
+ ///
+ /// Task submissions will be rejected if the submitting app does not have the correct entitlement. Background GPU
+ /// execution is not supported on all devices. Additionally, if a device is experiencing heavy GPU contention
+ /// backgrounded workloads are not guaranteed runtime.
+ ///
+ /// - Important: Applications must have the `com.apple.developer.background-tasks.continued-processing.gpu` entitlement to submit a task request with this resource.
+ BGContinuedProcessingTaskRequestResourcesGPU NS_SWIFT_NAME(gpu) = (1 << 0),
+} NS_SWIFT_NAME(BGContinuedProcessingTaskRequest.Resources) API_AVAILABLE(ios(26.0)) API_UNAVAILABLE(macos, tvos, visionos, watchos, macCatalyst);
+
+#pragma mark -
+
+/// A request to begin a workload immediately, or shortly after submission, which is allowed to continue running even if
+/// the app is backgrounded.
+///
+/// Similar to Background App Refresh, users are allowed to disable ``BGContinuedProcessingTask`` objects from running
+/// on their devices.
+BG_EXTERN API_AVAILABLE(ios(26.0)) API_UNAVAILABLE(macos, tvos, visionos, watchos, macCatalyst)
+@interface BGContinuedProcessingTaskRequest : BGTaskRequest
+
+/// The localized title displayed to the user.
+@property (copy, nonnull) NSString *title;
+
+/// The localized subtitle displayed to the user.
+@property (copy, nonnull) NSString *subtitle;
+
+/// The submission strategy for the scheduler to abide by.
+///
+/// Defaults to ``BGContinuedProcessingTaskRequestSubmissionStrategy/BGContinuedProcessingTaskRequestSubmissionStrategyQueue``.
+@property (nonatomic) BGContinuedProcessingTaskRequestSubmissionStrategy strategy;
+
+/// Inform the scheduler that the task will be requesting additional system resources.
+///
+/// Defaults to ``BGContinuedProcessingTaskRequestResources/BGContinuedProcessingTaskRequestResourcesDefault``.
+@property (nonatomic) BGContinuedProcessingTaskRequestResources requiredResources;
+
+/// Creates an instance on behalf of the currently foregrounded app.
+///
+/// Apps and their extensions should use this method to initialize any tasks due to the underlying association to the
+/// currently foregrounded app. Please note that ``BGTaskRequest/earliestBeginDate`` will be outright ignored by the
+/// scheduler in favor of `NSDate.now`.
+///
+/// The identifier must leverage a base wildcard notation, where the prefix of the identifier must at least contain the
+/// bundle ID of the submitting application, followed by optional semantic context, and finally ending with `.*`. An
+/// example: `<MainBundle>.<SemanticContext>.*` which would transform to
+/// `com.foo.MyApplication.continuedProcessingTask.*`. Thus, a submitted identifier would be of the form
+/// `com.foo.MyApplication.continuedProcessingTask.HD830D`.
+///
+/// - Parameters:
+/// - identifier: The task identifier.
+/// - title: The localized title displayed to the user before the task begins running.
+/// - subtitle: The localized subtitle displayed to the user before the task begins running.
+/// - Warning: Successful creation of this object does not guarantee successful submission to the scheduler.
+- (instancetype)initWithIdentifier:(NSString *)identifier
+ title:(NSString *)title
+ subtitle:(NSString *)subtitle;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff -ruN /Applications/Xcode_16.4.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h /Applications/Xcode_26.0.0-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h
--- /Applications/Xcode_16.4.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h 2025-04-19 02:00:33
+++ /Applications/Xcode_26.0.0-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h 2025-05-29 02:28:43
@@ -7,6 +7,7 @@
#import <Foundation/Foundation.h>
+#import <BackgroundTasks/BGTaskRequest.h>
#import <BackgroundTasks/BGDefines.h>
@class BGTaskScheduler;
@@ -16,64 +17,50 @@
NS_ASSUME_NONNULL_BEGIN
/// The background tasks error domain as a string.
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
NSErrorDomain const BGTaskSchedulerErrorDomain;
-/*!
- @enum BGTaskSchedulerErrorCode
- @constant BGTaskSchedulerErrorCodeUnavailable Background task scheduling functionality is not available for this app/extension. Background App Refresh may have been disabled in Settings.
- @constant BGTaskSchedulerErrorCodeTooManyPendingTaskRequests The task request could not be submitted because there are too many pending task requests of this type. Cancel some existing task requests before trying again.
- @constant BGTaskSchedulerErrorCodeNotPermitted The task request could not be submitted because the appropriate background mode is not included in the UIBackgroundModes array, or its identifier was not present in the BGTaskSchedulerPermittedIdentifiers array in the app's Info.plist.
- */
-
/// An enumeration of the task scheduling errors.
typedef NS_ERROR_ENUM(BGTaskSchedulerErrorDomain, BGTaskSchedulerErrorCode) {
- /// A task scheduling error indicating that the app or extension can’t
- /// schedule background work.
+ /// A task scheduling error indicating that the app or extension can’t schedule background work.
///
/// This error usually occurs for one of following reasons:
///
/// - The user has disabled background refresh in settings.
/// - The app is running on Simulator which doesn’t support background processing.
- /// - The keyboard extension either hasn’t set
- /// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/nsextension/nsextensionattributes/requestsopenaccess>
- /// to `YES` in [The Info.plist
- /// File](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW22),
- /// or the user hasn’t granted open access.
+ /// - The keyboard extension either hasn’t set <doc://com.apple.documentation/documentation/bundleresources/information_property_list/nsextension/nsextensionattributes/requestsopenaccess>
+ /// to `YES` in [The Info.plist File](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW22), or the user hasn’t granted open access.
/// - The extension type isn’t able to schedule background tasks.
BGTaskSchedulerErrorCodeUnavailable = 1,
- /// A task scheduling error indicating that there are too many pending tasks
- /// of the type requested.
+ /// A task scheduling error indicating that there are too many pending tasks of the type requested.
///
- /// Try canceling some existing task requests and then resubmit the request
- /// that failed.
+ /// Try canceling some existing task requests and then resubmit the request that failed.
BGTaskSchedulerErrorCodeTooManyPendingTaskRequests = 2,
- /// A task scheduling error indicating the app isn’t permitted to schedule the
- /// task.
+ /// A task scheduling error indicating the app isn’t permitted to schedule the task.
///
- /// There are two causes for this error:
+ /// There are four causes for this error:
///
- /// - The app doesn’t set the appropriate mode in the
- /// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/uibackgroundmodes>
+ /// - The app doesn’t set the appropriate mode in the <doc://com.apple.documentation/documentation/bundleresources/information_property_list/uibackgroundmodes>
/// array.
- ///
- /// - The task identifier of the submitted task wasn’t in the
- /// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
- /// array in [the Info.plist
- /// File](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW22).
+ /// - The task identifier of the submitted task wasn’t in the <doc://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
+ /// array in [the Info.plist](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW22).
+ /// - The task requested additional ``BGContinuedProcessingTaskRequestResources`` that are unavailable.
+ /// - The user has explicitly denied background launches for your app.
BGTaskSchedulerErrorCodeNotPermitted = 3,
-} API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos);
+ /// A ``BGContinuedProcessingTaskRequest`` was not allowed to immediately run due to system conditions.
+ ///
+ /// This will only be returned when using the ``BGContinuedProcessingTaskRequestSubmissionStrategyFail`` when
+ /// submitting a ``BGContinuedProcessingTaskRequest``. Task requests that are successfully ran will not be
+ /// associated with any error code.
+ BGTaskSchedulerErrorCodeImmediateRunIneligible = 4,
+} API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos);
-/*!
- @class BGTaskScheduler
- @abstract The object you use to schedule deferrable work to be done in the background.
- */
-BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
/// A class for scheduling task requests that launch your app in the background.
///
/// Background tasks give your app a way to run code while the app is suspended.
/// To learn how to register, schedule, and run a background task, see
/// <doc://com.apple.documentation/documentation/uikit/app_and_environment/scenes/preparing_your_ui_to_run_in_the_background/using_background_tasks_to_update_your_app>.
+BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos)
@interface BGTaskScheduler : NSObject
- (instancetype)init NS_UNAVAILABLE; //Use the shared scheduler object instead
+ (instancetype)new NS_UNAVAILABLE; //Use the shared scheduler object instead
@@ -81,105 +68,64 @@
/// The shared background task scheduler instance.
@property (class, readonly, strong) __kindof BGTaskScheduler *sharedScheduler;
-/*!
- @abstract Register a handler to be called for tasks that launch the app.
- @param identifier The identifier for the task that will be handled by the provided launch handler.
- @param queue The queue on which the launch handler and the expiration handler for the task will be called. The queue should be serial to ensure consistent ordering. If you pass nil, handlers will be called on a background queue.
- @param launchHandler The block that will be called when the app is launched for the specified task. The block has no return value and takes a single parameter, task, a BGTask object. Assign an expiration handler to the task's expirationHandler property and call setTaskCompletedWithSuccess: when the background work is complete.
- @discussion You must register launch handlers before your application finishes launching. Attempting to register a handler after launch or multiple handlers for the same identifier is an error. Although you may submit task requests from some extensions, only the host app will be launched to handle background work.
- @return YES if the handler was registered, or NO if it was not because the provided identifier was not present in the BGTaskSchedulerPermittedIdentifiers array in the app's Info.plist.
- */
+/// A bitfield of the resources the device supports for ``BackgroundTasks/BGContinuedProcessingTaskRequest`` instances.
+@property (class, readonly) BGContinuedProcessingTaskRequestResources supportedResources API_AVAILABLE(ios(26.0)) API_UNAVAILABLE(macos, tvos, visionos, watchos, macCatalyst);
-/// Register a launch handler for the task with the associated identifier that’s
-/// executed on the specified queue.
+/// Register a launch handler for the task with the associated identifier that’s executed on the specified queue.
///
-/// Every identifier in the
-/// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
-/// requires a handler. Registration of all launch handlers must be complete
-/// before the end of
+/// Every identifier in the <doc://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
+/// requires a handler. Registration of all launch handlers must be complete before the end of
/// <doc://com.apple.documentation/documentation/uikit/uiapplicationdelegate/1623053-applicationdidfinishlaunching>.
///
-/// - Important: Register each task identifier only once. The system kills the
-/// app on the second registration of the same task identifier.
+/// You must register launch handlers before your application finishes launching (``BGContinuedProcessingTask``
+/// registrations are exempt from this requirement). Attempting to register a handler after launch or multiple handlers
+/// for the same identifier is an error. Although you may submit task requests from some extensions, only the host app
+/// will be launched to handle background work.
///
/// - Parameters:
-/// - identifier: A string containing the identifier of the task.
-///
-/// - queue: A queue for executing the task. Pass `nil` to use a default
-/// background queue.
-///
-/// - launchHandler: The system runs the block of code for the launch handler
-/// when it launches the app in the background. The block takes a single
-/// parameter, a ``BGTask`` object used for assigning an expiration handler and
-/// for setting a completion status. The block has no return value.
-///
-/// - Returns: Returns
-/// <doc://com.apple.documentation/documentation/objectivec/yes> if the launch
-/// handler was registered. Returns
-/// <doc://com.apple.documentation/documentation/objectivec/no> if the
-/// identifier isn't included in the
-/// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
-/// `Info.plist`.
-- (BOOL)registerForTaskWithIdentifier:(NSString *)identifier usingQueue:(nullable dispatch_queue_t)queue launchHandler:(void (^)(__kindof BGTask *task))launchHandler NS_EXTENSION_UNAVAILABLE("Only the host application may register launch handlers");
+/// - identifier: The identifier for the task that will be handled by the provided launch handler.
+/// - queue: A queue for executing the task. Pass `nil` to use a default background queue.
+/// - launchHandler: The system runs the block of code for the launch handler when it launches the app in the background. The block takes a single parameter, a ``BGTask`` object used for assigning an expiration handler and for setting a completion status. The block has no return value. Assign an expiration handler to the task's expirationHandler property and call setTaskCompletedWithSuccess: when the background work is complete.
+/// - Returns: Returns <doc://com.apple.documentation/documentation/objectivec/yes> if the launch handler was registered. Returns <doc://com.apple.documentation/documentation/objectivec/no> if the identifier isn't included in the <doc://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers> `Info.plist`.
+/// - Important: Register each task identifier only once. The system kills the app on the second registration of the same task identifier.
+- (BOOL)registerForTaskWithIdentifier:(NSString *)identifier
+ usingQueue:(nullable dispatch_queue_t)queue
+ launchHandler:(void (^)(__kindof BGTask *task))launchHandler NS_EXTENSION_UNAVAILABLE("Only the host application may register launch handlers");
-/*!
- @abstract Submit a request to be launched in the background to perform work.
- @param taskRequest The task request object representing the parameters of the background task to be scheduled.
- @param error If an error occurs, upon return contains an error object that indicates why the request was rejected.
- @discussion Submitting a task request with the same identifier as an existing request will replace that request.
- @return YES if the request was successfully submitted, NO if there was an error
- */
-
/// Submit a previously registered background task for execution.
///
-/// Submitting a task request for an unexecuted task that’s already in the queue
-/// replaces the previous task request.
+/// Submitting a task request for an unexecuted task that’s already in the queue replaces the previous task request.
///
-/// There can be a total of 1 refresh task and 10 processing tasks scheduled at
-/// any time. Trying to schedule more tasks returns
-/// ``BGTaskSchedulerErrorCode/BGTaskSchedulerErrorCodeTooManyPendingTaskRequests``.
+/// There can be a total of 1 refresh task and 10 processing tasks scheduled at any time. Trying to schedule more tasks
+/// returns ``BGTaskSchedulerErrorCode/BGTaskSchedulerErrorCodeTooManyPendingTaskRequests``.
///
/// - Parameters:
-/// - taskRequest: A background task request object specifying the task
-/// - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an error object containing the error information. Specify `nil` for this parameter to ignore the error information.
-/// identifier and optional configuration information.
-- (BOOL)submitTaskRequest:(BGTaskRequest *)taskRequest error:(NSError * _Nullable *)error;
+/// - taskRequest: The task request object representing the parameters of the background task to be scheduled.
+/// - error: If an error occurs, upon return contains an error object that indicates why the request was rejected
+/// - Returns: `YES` if the request was successfully submitted; `NO` if there was an error
+- (BOOL)submitTaskRequest:(BGTaskRequest *)taskRequest
+ error:(NSError * _Nullable *)error;
-/*!
- @abstract Cancel a previously submitted task request.
- @param identifier The identifier of the previously submitted task request to cancel.
- */
-
/// Cancel a previously scheduled task request.
///
/// - Parameters:
-/// - identifier: The string identifier of the task request to cancel.
+/// - identifier: The identifier of the previously submitted task request to cancel.
- (void)cancelTaskRequestWithIdentifier:(NSString *)identifier;
-/*!
- @abstract Cancel all previously submitted task requests.
- */
-
-/// Cancel all scheduled task requests.
+/// Cancel all previously submitted task requests.
- (void)cancelAllTaskRequests;
-/*!
- @abstract Returns a list of all task requests that have been submitted but not yet completed.
- @param completionHandler A block for processing task requests. This block may be executed on a background thread. The block has no return value and takes a single parameter, taskRequests, which is an array of BGTaskRequest objects. If there are no pending requests, this array is empty. The task request objects returned are copies and changing their property values will have no immediate effect. To modify the parameters of a pending task request, submit it again to the scheduler with submitTaskRequest:error:.
- */
-
-/// Request a list of unexecuted scheduled task requests.
+/// Returns a list of all task requests that have been submitted but not yet completed.
///
-/// - Parameters:
-/// - completionHandler: The completion handler called with the pending tasks.
-/// The handler may execute on a background thread.
-///
/// The handler takes a single parameter `tasksRequests`, an array of `BGTaskRequest`
/// objects. The array is empty if there are no scheduled tasks.
///
-/// The objects passed in the array are copies of the existing requests. Changing the
-/// attributes of a request has no effect. To change the attributes submit a new
-/// task request using ``BGTaskScheduler/submitTaskRequest:error:``.
+/// The objects passed in the array are copies of the existing requests. Changing the attributes of a request has no
+/// effect. To change the attributes submit a new task request using ``BGTaskScheduler/submitTaskRequest:error:``.
+///
+/// - Parameters:
+/// - completionHandler: The completion handler called with the pending tasks.
+/// - Note: The handler may execute on a background thread.
- (void)getPendingTaskRequestsWithCompletionHandler:(void (^)(NSArray<BGTaskRequest *> *taskRequests))completionHandler;
@end