objc2_background_tasks/generated/BGTaskScheduler.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5#[cfg(feature = "dispatch2")]
6use dispatch2::*;
7use objc2::__framework_prelude::*;
8use objc2_foundation::*;
9
10use crate::*;
11
12extern "C" {
13 /// The background tasks error domain as a string.
14 ///
15 /// See also [Apple's documentation](https://developer.apple.com/documentation/backgroundtasks/bgtaskschedulererrordomain?language=objc)
16 pub static BGTaskSchedulerErrorDomain: &'static NSErrorDomain;
17}
18
19/// An enumeration of the task scheduling errors.
20///
21/// See also [Apple's documentation](https://developer.apple.com/documentation/backgroundtasks/bgtaskschedulererrorcode?language=objc)
22// NS_ERROR_ENUM
23#[repr(transparent)]
24#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
25pub struct BGTaskSchedulerErrorCode(pub NSInteger);
26impl BGTaskSchedulerErrorCode {
27 /// A task scheduling error indicating that the app or extension can’t
28 /// schedule background work.
29 ///
30 /// This error usually occurs for one of following reasons:
31 ///
32 /// - The user has disabled background refresh in settings.
33 /// - The app is running on Simulator which doesn’t support background processing.
34 /// - The keyboard extension either hasn’t set
35 /// <doc
36 /// ://com.apple.documentation/documentation/bundleresources/information_property_list/nsextension/nsextensionattributes/requestsopenaccess>
37 /// to `YES` in [The Info.plist
38 /// File](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW22),
39 /// or the user hasn’t granted open access.
40 /// - The extension type isn’t able to schedule background tasks.
41 #[doc(alias = "BGTaskSchedulerErrorCodeUnavailable")]
42 pub const Unavailable: Self = Self(1);
43 /// A task scheduling error indicating that there are too many pending tasks
44 /// of the type requested.
45 ///
46 /// Try canceling some existing task requests and then resubmit the request
47 /// that failed.
48 #[doc(alias = "BGTaskSchedulerErrorCodeTooManyPendingTaskRequests")]
49 pub const TooManyPendingTaskRequests: Self = Self(2);
50 /// A task scheduling error indicating the app isn’t permitted to schedule the
51 /// task.
52 ///
53 /// There are two causes for this error:
54 ///
55 /// - The app doesn’t set the appropriate mode in the
56 /// <doc
57 /// ://com.apple.documentation/documentation/bundleresources/information_property_list/uibackgroundmodes>
58 /// array.
59 ///
60 /// - The task identifier of the submitted task wasn’t in the
61 /// <doc
62 /// ://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
63 /// array in [the Info.plist
64 /// File](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW22).
65 #[doc(alias = "BGTaskSchedulerErrorCodeNotPermitted")]
66 pub const NotPermitted: Self = Self(3);
67}
68
69unsafe impl Encode for BGTaskSchedulerErrorCode {
70 const ENCODING: Encoding = NSInteger::ENCODING;
71}
72
73unsafe impl RefEncode for BGTaskSchedulerErrorCode {
74 const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
75}
76
77extern_class!(
78 /// A class for scheduling task requests that launch your app in the background.
79 ///
80 /// Background tasks give your app a way to run code while the app is suspended.
81 /// To learn how to register, schedule, and run a background task, see
82 /// <doc
83 /// ://com.apple.documentation/documentation/uikit/app_and_environment/scenes/preparing_your_ui_to_run_in_the_background/using_background_tasks_to_update_your_app>.
84 ///
85 /// See also [Apple's documentation](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler?language=objc)
86 #[unsafe(super(NSObject))]
87 #[derive(Debug, PartialEq, Eq, Hash)]
88 pub struct BGTaskScheduler;
89);
90
91extern_conformance!(
92 unsafe impl NSObjectProtocol for BGTaskScheduler {}
93);
94
95impl BGTaskScheduler {
96 extern_methods!(
97 #[unsafe(method(init))]
98 #[unsafe(method_family = init)]
99 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
100
101 #[unsafe(method(new))]
102 #[unsafe(method_family = new)]
103 pub unsafe fn new() -> Retained<Self>;
104
105 /// The shared background task scheduler instance.
106 #[unsafe(method(sharedScheduler))]
107 #[unsafe(method_family = none)]
108 pub unsafe fn sharedScheduler() -> Retained<BGTaskScheduler>;
109
110 #[cfg(all(feature = "BGTask", feature = "block2", feature = "dispatch2"))]
111 /// Register a launch handler for the task with the associated identifier that’s
112 /// executed on the specified queue.
113 ///
114 /// Every identifier in the
115 /// <doc
116 /// ://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
117 /// requires a handler. Registration of all launch handlers must be complete
118 /// before the end of
119 /// <doc
120 /// ://com.apple.documentation/documentation/uikit/uiapplicationdelegate/1623053-applicationdidfinishlaunching>.
121 ///
122 /// - Important: Register each task identifier only once. The system kills the
123 /// app on the second registration of the same task identifier.
124 ///
125 /// - Parameters:
126 /// - identifier: A string containing the identifier of the task.
127 ///
128 /// - queue: A queue for executing the task. Pass `nil` to use a default
129 /// background queue.
130 ///
131 /// - launchHandler: The system runs the block of code for the launch handler
132 /// when it launches the app in the background. The block takes a single
133 /// parameter, a ``BGTask`` object used for assigning an expiration handler and
134 /// for setting a completion status. The block has no return value.
135 ///
136 /// - Returns: Returns
137 /// <doc
138 /// ://com.apple.documentation/documentation/objectivec/yes> if the launch
139 /// handler was registered. Returns
140 /// <doc
141 /// ://com.apple.documentation/documentation/objectivec/no> if the
142 /// identifier isn't included in the
143 /// <doc
144 /// ://com.apple.documentation/documentation/bundleresources/information_property_list/bgtaskschedulerpermittedidentifiers>
145 /// `Info.plist`.
146 #[unsafe(method(registerForTaskWithIdentifier:usingQueue:launchHandler:))]
147 #[unsafe(method_family = none)]
148 pub unsafe fn registerForTaskWithIdentifier_usingQueue_launchHandler(
149 &self,
150 identifier: &NSString,
151 queue: Option<&DispatchQueue>,
152 launch_handler: &block2::DynBlock<dyn Fn(NonNull<BGTask>)>,
153 ) -> bool;
154
155 #[cfg(feature = "BGTaskRequest")]
156 /// Submit a previously registered background task for execution.
157 ///
158 /// Submitting a task request for an unexecuted task that’s already in the queue
159 /// replaces the previous task request.
160 ///
161 /// There can be a total of 1 refresh task and 10 processing tasks scheduled at
162 /// any time. Trying to schedule more tasks returns
163 /// ``BGTaskSchedulerErrorCode/BGTaskSchedulerErrorCodeTooManyPendingTaskRequests``.
164 ///
165 /// - Parameters:
166 /// - taskRequest: A background task request object specifying the task
167 /// - 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.
168 /// identifier and optional configuration information.
169 #[unsafe(method(submitTaskRequest:error:_))]
170 #[unsafe(method_family = none)]
171 pub unsafe fn submitTaskRequest_error(
172 &self,
173 task_request: &BGTaskRequest,
174 ) -> Result<(), Retained<NSError>>;
175
176 /// Cancel a previously scheduled task request.
177 ///
178 /// - Parameters:
179 /// - identifier: The string identifier of the task request to cancel.
180 #[unsafe(method(cancelTaskRequestWithIdentifier:))]
181 #[unsafe(method_family = none)]
182 pub unsafe fn cancelTaskRequestWithIdentifier(&self, identifier: &NSString);
183
184 /// Cancel all scheduled task requests.
185 #[unsafe(method(cancelAllTaskRequests))]
186 #[unsafe(method_family = none)]
187 pub unsafe fn cancelAllTaskRequests(&self);
188
189 #[cfg(all(feature = "BGTaskRequest", feature = "block2"))]
190 /// Request a list of unexecuted scheduled task requests.
191 ///
192 /// - Parameters:
193 /// - completionHandler: The completion handler called with the pending tasks.
194 /// The handler may execute on a background thread.
195 ///
196 /// The handler takes a single parameter `tasksRequests`, an array of `BGTaskRequest`
197 /// objects. The array is empty if there are no scheduled tasks.
198 ///
199 /// The objects passed in the array are copies of the existing requests. Changing the
200 /// attributes of a request has no effect. To change the attributes submit a new
201 /// task request using ``BGTaskScheduler/submitTaskRequest:error:``.
202 #[unsafe(method(getPendingTaskRequestsWithCompletionHandler:))]
203 #[unsafe(method_family = none)]
204 pub unsafe fn getPendingTaskRequestsWithCompletionHandler(
205 &self,
206 completion_handler: &block2::DynBlock<dyn Fn(NonNull<NSArray<BGTaskRequest>>)>,
207 );
208 );
209}