BackgroundTasks macOS xcode14.3 beta1

#BackgroundTasks.framework

diff -ruN /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h
--- /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h	2022-11-12 15:58:40
+++ /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTask.h	2023-02-11 22:21:51
@@ -16,18 +16,45 @@
  @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.
 @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.
+ 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.
+///
+/// Not setting an expiration handler results in the system marking your task as
+/// complete and unsuccessful instead of sending a warning.
+///
+/// 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.
+///
+/// The handler may be called before the background process uses the full amount of its
+/// allocated time.
 @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
@@ -39,6 +66,19 @@
  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.
+///
+/// Not calling ``BGTask/setTaskCompletedWithSuccess:`` before the time for the
+/// task expires may result in the system killing your app.
+///
+/// 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.
 - (void)setTaskCompletedWithSuccess:(BOOL)success;
 
 @end
@@ -47,6 +87,22 @@
  @abstract A background task used to perform deferrable processing.
  */
 BG_EXTERN API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos)
+/// A time-consuming processing task that runs while the app is in the
+/// background.
+///
+/// Use processing tasks for long data updates, processing data, and app
+/// maintenance. Although processing tasks can run for minutes, the system can
+/// interrupt the process. Add an expiration handler by setting
+/// ``BGTask/expirationHandler`` for any required cleanup.
+///
+/// Executing processing tasks requires setting the `processing`
+/// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/uibackgroundmodes>
+/// capability. For information on setting this capability, see
+/// ``BGTaskScheduler``.
+///
+/// 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.
 @interface BGProcessingTask : BGTask
 
 @end
@@ -55,6 +111,16 @@
  @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)
+/// An object representing a short task typically used to refresh content that’s
+/// run while the app is in the background.
+///
+/// Use app refresh tasks for updating your app with small bits of information,
+/// such as the latest stock values.
+///
+/// Executing app refresh tasks requires setting the `fetch`
+/// <doc://com.apple.documentation/documentation/bundleresources/information_property_list/uibackgroundmodes>
+/// capability. For information on setting this capability, see
+/// ``BGTaskScheduler``.
 @interface BGAppRefreshTask : BGTask
 
 @end
diff -ruN /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h
--- /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h	2022-11-12 15:58:40
+++ /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskRequest.h	2023-02-12 14:13:41
@@ -16,16 +16,27 @@
  @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)
+/// An abstract class for representing task requests.
 @interface BGTaskRequest : NSObject <NSCopying>
 /*!
  @abstract The identifier associated with this request.
  */
+
+/// The identifier of the task associated with the request.
 @property (readonly, copy) NSString *identifier;
 
 /*!
  @abstract The earliest date at which the task may run.
  @discussion Setting this property does not guarantee that the task will begin at the specified date, but only that it will not begin sooner. If not specified, no start delay is used.
  */
+
+/// The earliest date and time at which to run the task.
+///
+/// Specify `nil` for no start delay.
+///
+/// Setting the property indicates that the background task shouldn’t start any
+/// earlier than this date. However, the system doesn’t guarantee launching the
+/// task at the specified date, but only that it won’t begin sooner.
 @property (copy, nullable) NSDate *earliestBeginDate;
 
 - (instancetype)init NS_UNAVAILABLE; // This is an abstract type and should not be directly instantiated
@@ -36,9 +47,15 @@
  @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)
 @interface BGAppRefreshTaskRequest : BGTaskRequest
 
+/// Return a new refresh task request for the specified identifier.
+///
+/// - Parameters:
+///     - identifier: The string identifier of the refresh task associated with the request.
 - (instancetype)initWithIdentifier:(NSString *)identifier;
 
 @end
@@ -47,9 +64,16 @@
  @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.
  */
+
+/// 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)
 @interface BGProcessingTaskRequest : BGTaskRequest
 
+/// Return a new processing task request for the specified identifier.
+///
+/// - Parameters:
+///     - identifier: The string identifier of the processing task associated with the request.
 - (instancetype)initWithIdentifier:(NSString *)identifier;
 
 /*!
@@ -57,6 +81,8 @@
  @discussion If this property is set to YES, the system will only launch your app to fulfill this request when the device has a network connection. If this is set to NO, your app may not have network access.
  The default value is NO.
  */
+
+/// A Boolean specifying if the processing task requires network connectivity.
 @property (assign) BOOL requiresNetworkConnectivity;
 
 /*!
@@ -65,6 +91,8 @@
  Specify YES if this task is resource intensive to minimize impact to battery life. Please note that, even if this value is NO, the system will not necessarily schedule this task while the device is on battery power, depending on the type of device and system conditions.
  The default value is NO.
  */
+
+/// A Boolean specifying if the processing task requires a device connected to power.
 @property (assign) BOOL requiresExternalPower;
 
 @end
diff -ruN /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h
--- /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h	2022-11-10 19:16:02
+++ /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/BackgroundTasks.framework/Headers/BGTaskScheduler.h	2023-02-12 14:10:33
@@ -15,6 +15,7 @@
 
 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)
 NSErrorDomain const BGTaskSchedulerErrorDomain;
 
@@ -24,9 +25,42 @@
  @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.
+    ///
+    /// 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 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.
+    ///
+    /// 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.
+///
+/// There are two causes for this error:
+///
+/// - 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).
     BGTaskSchedulerErrorCodeNotPermitted = 3,
 } API_AVAILABLE(ios(13.0), tvos(13.0)) API_UNAVAILABLE(macos, watchos);
 
@@ -35,10 +69,16 @@
  @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>.
 @interface BGTaskScheduler : NSObject
 - (instancetype)init NS_UNAVAILABLE; //Use the shared scheduler object instead
 + (instancetype)new NS_UNAVAILABLE; //Use the shared scheduler object instead
 
+/// The shared background task scheduler instance.
 @property (class, readonly, strong) __kindof BGTaskScheduler *sharedScheduler;
 
 /*!
@@ -49,6 +89,37 @@
  @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.
  */
+
+/// 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
+/// <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.
+///
+/// - 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");
 
 /*!
@@ -58,23 +129,57 @@
  @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.
+///
+/// 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;
 
 /*!
  @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.
 - (void)cancelTaskRequestWithIdentifier:(NSString *)identifier;
 
 /*!
  @abstract Cancel all previously submitted task requests.
  */
+
+/// Cancel all scheduled 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.
+///
+/// - 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:``.
 - (void)getPendingTaskRequestsWithCompletionHandler:(void (^)(NSArray<BGTaskRequest *> *taskRequests))completionHandler;
 
 @end