1#ifndef __XPC_ACTIVITY_H__
2#define __XPC_ACTIVITY_H__
3
4#ifndef __XPC_INDIRECT__
5#error "Please #include <xpc/xpc.h> instead of this file directly."
6// For HeaderDoc.
7#include <xpc/base.h>
8#endif // __XPC_INDIRECT__
9
10#ifdef __BLOCKS__
11
12XPC_ASSUME_NONNULL_BEGIN
13__BEGIN_DECLS
14
15/*
16 * The following are a collection of keys and values used to set an activity's
17 * execution criteria.
18 */
19
20/*!
21 * @constant XPC_ACTIVITY_INTERVAL
22 * An integer property indicating the desired time interval (in seconds) of the
23 * activity. The activity will not be run more than once per time interval.
24 * Due to the nature of XPC Activity finding an opportune time to run
25 * the activity, any two occurrences may be more or less than 'interval'
26 * seconds apart, but on average will be 'interval' seconds apart.
27 * The presence of this key implies the following, unless overridden:
28 * - XPC_ACTIVITY_REPEATING with a value of true
29 * - XPC_ACTIVITY_DELAY with a value of half the 'interval'
30 * The delay enforces a minimum distance between any two occurrences.
31 * - XPC_ACTIVITY_GRACE_PERIOD with a value of half the 'interval'.
32 * The grace period is the amount of time allowed to pass after the end of
33 * the interval before more aggressive scheduling occurs. The grace period
34 * does not increase the size of the interval.
35 */
36API_AVAILABLE(macos(10.9))
37API_UNAVAILABLE(ios)
38XPC_EXPORT
39const char * const XPC_ACTIVITY_INTERVAL;
40
41/*!
42 * @constant XPC_ACTIVITY_REPEATING
43 * A boolean property indicating whether this is a repeating activity.
44 */
45API_AVAILABLE(macos(10.9))
46API_UNAVAILABLE(ios)
47XPC_EXPORT
48const char * const XPC_ACTIVITY_REPEATING;
49
50/*!
51 * @constant XPC_ACTIVITY_DELAY
52 * An integer property indicating the number of seconds to delay before
53 * beginning the activity.
54 */
55API_AVAILABLE(macos(10.9))
56API_UNAVAILABLE(ios)
57XPC_EXPORT
58const char * const XPC_ACTIVITY_DELAY;
59
60/*!
61 * @constant XPC_ACTIVITY_GRACE_PERIOD
62 * An integer property indicating the number of seconds to allow as a grace
63 * period before the scheduling of the activity becomes more aggressive.
64 */
65API_AVAILABLE(macos(10.9))
66API_UNAVAILABLE(ios)
67XPC_EXPORT
68const char * const XPC_ACTIVITY_GRACE_PERIOD;
69
70
71API_AVAILABLE(macos(10.9))
72API_UNAVAILABLE(ios)
73XPC_EXPORT
74const int64_t XPC_ACTIVITY_INTERVAL_1_MIN;
75
76API_AVAILABLE(macos(10.9))
77API_UNAVAILABLE(ios)
78XPC_EXPORT
79const int64_t XPC_ACTIVITY_INTERVAL_5_MIN;
80
81API_AVAILABLE(macos(10.9))
82API_UNAVAILABLE(ios)
83XPC_EXPORT
84const int64_t XPC_ACTIVITY_INTERVAL_15_MIN;
85
86API_AVAILABLE(macos(10.9))
87API_UNAVAILABLE(ios)
88XPC_EXPORT
89const int64_t XPC_ACTIVITY_INTERVAL_30_MIN;
90
91API_AVAILABLE(macos(10.9))
92API_UNAVAILABLE(ios)
93XPC_EXPORT
94const int64_t XPC_ACTIVITY_INTERVAL_1_HOUR;
95
96API_AVAILABLE(macos(10.9))
97API_UNAVAILABLE(ios)
98XPC_EXPORT
99const int64_t XPC_ACTIVITY_INTERVAL_4_HOURS;
100
101API_AVAILABLE(macos(10.9))
102API_UNAVAILABLE(ios)
103XPC_EXPORT
104const int64_t XPC_ACTIVITY_INTERVAL_8_HOURS;
105
106API_AVAILABLE(macos(10.9))
107API_UNAVAILABLE(ios)
108XPC_EXPORT
109const int64_t XPC_ACTIVITY_INTERVAL_1_DAY;
110
111API_AVAILABLE(macos(10.9))
112API_UNAVAILABLE(ios)
113XPC_EXPORT
114const int64_t XPC_ACTIVITY_INTERVAL_7_DAYS;
115
116/*!
117 * @constant XPC_ACTIVITY_PRIORITY
118 * A string property indicating the priority of the activity.
119 */
120API_AVAILABLE(macos(10.9))
121API_UNAVAILABLE(ios)
122XPC_EXPORT
123const char * const XPC_ACTIVITY_PRIORITY;
124
125/*!
126 * @constant XPC_ACTIVITY_PRIORITY_MAINTENANCE
127 * A string indicating activity is maintenance priority.
128 *
129 * Maintenance priority is intended for user-invisible maintenance tasks
130 * such as garbage collection or optimization.
131 *
132 * Maintenance activities are not permitted to run if the device thermal
133 * condition exceeds a nominal level or if the battery level is lower than 20%.
134 * In Low Power Mode (on supported devices), maintenance activities are not
135 * permitted to run while the device is on battery, or plugged in and the
136 * battery level is lower than 30%.
137 */
138API_AVAILABLE(macos(10.9))
139API_UNAVAILABLE(ios)
140XPC_EXPORT
141const char * const XPC_ACTIVITY_PRIORITY_MAINTENANCE;
142
143/*!
144 * @constant XPC_ACTIVITY_PRIORITY_UTILITY
145 * A string indicating activity is utility priority.
146 *
147 * Utility priority is intended for user-visible tasks such as fetching data
148 * from the network, copying files, or importing data.
149 *
150 * Utility activities are not permitted to run if the device thermal condition
151 * exceeds a moderate level or if the battery level is less than 10%. In Low
152 * Power Mode (on supported devices) when on battery power, utility activities
153 * are only permitted when they are close to their deadline (90% of their time
154 * window has elapsed).
155 */
156API_AVAILABLE(macos(10.9))
157API_UNAVAILABLE(ios)
158XPC_EXPORT
159const char * const XPC_ACTIVITY_PRIORITY_UTILITY;
160
161/*!
162 * @constant XPC_ACTIVITY_ALLOW_BATTERY
163 * A Boolean value indicating whether the activity should be allowed to run
164 * while the computer is on battery power. The default value is false for
165 * maintenance priority activity and true for utility priority activity.
166 */
167API_AVAILABLE(macos(10.9))
168API_UNAVAILABLE(ios)
169XPC_EXPORT
170const char * const XPC_ACTIVITY_ALLOW_BATTERY;
171
172/*!
173 * @constant XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP
174 * A Boolean value indicating whether the activity should only be performed
175 * while device appears to be asleep. Note that the definition of screen sleep
176 * may vary by platform and may include states where the device is known to be
177 * idle despite the fact that the display itself is still powered. Defaults to
178 * false.
179 */
180API_AVAILABLE(macos(10.9))
181API_UNAVAILABLE(ios)
182XPC_EXPORT
183const char * const XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP; // bool
184
185/*!
186 * @constant XPC_ACTIVITY_PREVENT_DEVICE_SLEEP
187 * A Boolean value indicating whether the activity should prevent system sleep while
188 * running on battery.
189 * If this property is set, the activity scheduler will take the appropriate power
190 * assertion to keep the device (but not the screen) awake while the activity is running.
191 * Only activities which perform critical system functions that do not want to be
192 * interrupted by system sleep should set this.
193 * Setting this property can impact battery life.
194 */
195API_AVAILABLE(macos(12.0))
196API_UNAVAILABLE(ios, watchos)
197XPC_EXPORT
198const char * const XPC_ACTIVITY_PREVENT_DEVICE_SLEEP; // bool
199
200/*!
201 * @constant XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL
202 * An integer percentage of minimum battery charge required to allow the
203 * activity to run. A default minimum battery level is determined by the
204 * system.
205 */
206__OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_9, __IPHONE_7_0, __IPHONE_7_0,
207 "REQUIRE_BATTERY_LEVEL is not implemented")
208XPC_EXPORT
209const char * const XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL; // int (%)
210
211/*!
212 * @constant XPC_ACTIVITY_REQUIRE_HDD_SPINNING
213 * A Boolean value indicating whether the activity should only be performed
214 * while the hard disk drive (HDD) is spinning. Computers with flash storage
215 * are considered to be equivalent to HDD spinning. Defaults to false.
216 */
217__OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_9, __IPHONE_7_0, __IPHONE_7_0,
218 "REQUIRE_HDD_SPINNING is not implemented")
219XPC_EXPORT
220const char * const XPC_ACTIVITY_REQUIRE_HDD_SPINNING; // bool
221
222/*!
223 * @define XPC_TYPE_ACTIVITY
224 * A type representing the XPC activity object.
225 */
226#define XPC_TYPE_ACTIVITY (&_xpc_type_activity)
227API_AVAILABLE(macos(10.9))
228API_UNAVAILABLE(ios)
229XPC_EXPORT
230XPC_TYPE(_xpc_type_activity);
231
232/*!
233 * @typedef xpc_activity_t
234 *
235 * @abstract
236 * An XPC activity object.
237 *
238 * @discussion
239 * This object represents a set of execution criteria and a current execution
240 * state for background activity on the system. Once an activity is registered,
241 * the system will evaluate its criteria to determine whether the activity is
242 * eligible to run under current system conditions. When an activity becomes
243 * eligible to run, its execution state will be updated and an invocation of
244 * its handler block will be made.
245 */
246XPC_DECL(xpc_activity);
247
248/*!
249 * @typedef xpc_activity_handler_t
250 *
251 * @abstract
252 * A block that is called when an XPC activity becomes eligible to run.
253 */
254XPC_NONNULL1
255typedef void (^xpc_activity_handler_t)(xpc_activity_t activity);
256
257/*!
258 * @constant XPC_ACTIVITY_CHECK_IN
259 * This constant may be passed to xpc_activity_register() as the criteria
260 * dictionary in order to check in with the system for previously registered
261 * activity using the same identifier (for example, an activity taken from a
262 * launchd property list).
263 */
264API_AVAILABLE(macos(10.9))
265API_UNAVAILABLE(ios)
266XPC_EXPORT
267const xpc_object_t XPC_ACTIVITY_CHECK_IN;
268
269/*!
270 * @function xpc_activity_register
271 *
272 * @abstract
273 * Registers an activity with the system.
274 *
275 * @discussion
276 * Registers a new activity with the system. The criteria of the activity are
277 * described by the dictionary passed to this function. If an activity with the
278 * same identifier already exists, the criteria provided override the existing
279 * criteria unless the special dictionary XPC_ACTIVITY_CHECK_IN is used. The
280 * XPC_ACTIVITY_CHECK_IN dictionary instructs the system to first look up an
281 * existing activity without modifying its criteria. Once the existing activity
282 * is found (or a new one is created with an empty set of criteria) the handler
283 * will be called with an activity object in the XPC_ACTIVITY_STATE_CHECK_IN
284 * state.
285 *
286 * @param identifier
287 * A unique identifier for the activity. Each application has its own namespace.
288 * The identifier should remain constant across registrations, relaunches of
289 * the application, and reboots. It should identify the kind of work being done,
290 * not a particular invocation of the work.
291 *
292 * @param criteria
293 * A dictionary of criteria for the activity.
294 *
295 * @param handler
296 * The handler block to be called when the activity changes state to one of the
297 * following states:
298 * - XPC_ACTIVITY_STATE_CHECK_IN (optional)
299 * - XPC_ACTIVITY_STATE_RUN
300 *
301 * The handler block is never invoked reentrantly. It will be invoked on a
302 * dispatch queue with an appropriate priority to perform the activity.
303 */
304API_AVAILABLE(macos(10.9))
305API_UNAVAILABLE(ios, tvos, watchos)
306XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3
307void
308xpc_activity_register(const char *identifier, xpc_object_t criteria,
309 xpc_activity_handler_t handler);
310
311/*!
312 * @function xpc_activity_copy_criteria
313 *
314 * @abstract
315 * Returns an XPC dictionary describing the execution criteria of an activity.
316 * This will return NULL in cases where the activity has already completed, e.g.
317 * when checking in to an event that finished and was not rescheduled.
318 */
319API_AVAILABLE(macos(10.9))
320API_UNAVAILABLE(ios, tvos, watchos)
321XPC_EXPORT XPC_WARN_RESULT XPC_RETURNS_RETAINED XPC_NONNULL1
322xpc_object_t _Nullable
323xpc_activity_copy_criteria(xpc_activity_t activity);
324
325/*!
326 * @function xpc_activity_set_criteria
327 *
328 * @abstract
329 * Modifies the execution criteria of an activity.
330 */
331API_AVAILABLE(macos(10.9))
332API_UNAVAILABLE(ios, tvos, watchos)
333XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
334void
335xpc_activity_set_criteria(xpc_activity_t activity, xpc_object_t criteria);
336
337/*!
338 * @enum xpc_activity_state_t
339 * An activity is defined to be in one of the following states. Applications
340 * may check the current state of the activity using xpc_activity_get_state()
341 * in the handler block provided to xpc_activity_register().
342 *
343 * The application can modify the state of the activity by calling
344 * xpc_activity_set_state() with one of the following:
345 * - XPC_ACTIVITY_STATE_DEFER
346 * - XPC_ACTIVITY_STATE_CONTINUE
347 * - XPC_ACTIVITY_STATE_DONE
348 *
349 * @constant XPC_ACTIVITY_STATE_CHECK_IN
350 * An activity in this state has just completed a checkin with the system after
351 * XPC_ACTIVITY_CHECK_IN was provided as the criteria dictionary to
352 * xpc_activity_register. The state gives the application an opportunity to
353 * inspect and modify the activity's criteria.
354 *
355 * @constant XPC_ACTIVITY_STATE_WAIT
356 * An activity in this state is waiting for an opportunity to run. This value
357 * is never returned within the activity's handler block, as the block is
358 * invoked in response to XPC_ACTIVITY_STATE_CHECK_IN or XPC_ACTIVITY_STATE_RUN.
359 *
360 * Note:
361 * A launchd job may idle exit while an activity is in the wait state and be
362 * relaunched in response to the activity becoming runnable. The launchd job
363 * simply needs to re-register for the activity on its next launch by passing
364 * XPC_ACTIVITY_STATE_CHECK_IN to xpc_activity_register().
365 *
366 * @constant XPC_ACTIVITY_STATE_RUN
367 * An activity in this state is eligible to run based on its criteria.
368 *
369 * @constant XPC_ACTIVITY_STATE_DEFER
370 * An application may pass this value to xpc_activity_set_state() to indicate
371 * that the activity should be deferred (placed back into the WAIT state) until
372 * a time when its criteria are met again. Deferring an activity does not reset
373 * any of its time-based criteria (in other words, it will remain past due).
374 *
375 * IMPORTANT:
376 * This should be done in response to observing xpc_activity_should_defer().
377 * It should not be done unilaterally. If you determine that conditions are bad
378 * to do your activity's work for reasons you can't express in a criteria
379 * dictionary, you should set the activity's state to XPC_ACTIVITY_STATE_DONE.
380 *
381 *
382 * @constant XPC_ACTIVITY_STATE_CONTINUE
383 * An application may pass this value to xpc_activity_set_state() to indicate
384 * that the activity will continue its operation beyond the return of its
385 * handler block. This can be used to extend an activity to include asynchronous
386 * operations. The activity's handler block will not be invoked again until the
387 * state has been updated to either XPC_ACTIVITY_STATE_DEFER or, in the case
388 * of repeating activity, XPC_ACTIVITY_STATE_DONE.
389 *
390 * @constant XPC_ACTIVITY_STATE_DONE
391 * An application may pass this value to xpc_activity_set_state() to indicate
392 * that the activity has completed. For non-repeating activity, the resources
393 * associated with the activity will be automatically released upon return from
394 * the handler block. For repeating activity, timers present in the activity's
395 * criteria will be reset.
396 */
397enum {
398 XPC_ACTIVITY_STATE_CHECK_IN,
399 XPC_ACTIVITY_STATE_WAIT,
400 XPC_ACTIVITY_STATE_RUN,
401 XPC_ACTIVITY_STATE_DEFER,
402 XPC_ACTIVITY_STATE_CONTINUE,
403 XPC_ACTIVITY_STATE_DONE,
404};
405typedef long xpc_activity_state_t;
406
407/*!
408 * @function xpc_activity_get_state
409 *
410 * @abstract
411 * Returns the current state of an activity.
412 */
413API_AVAILABLE(macos(10.9))
414API_UNAVAILABLE(ios, tvos, watchos)
415XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
416xpc_activity_state_t
417xpc_activity_get_state(xpc_activity_t activity);
418
419/*!
420 * @function xpc_activity_set_state
421 *
422 * @abstract
423 * Updates the current state of an activity.
424 *
425 * @return
426 * Returns true if the state was successfully updated; otherwise, returns
427 * false if the requested state transition is not valid.
428 */
429API_AVAILABLE(macos(10.9))
430API_UNAVAILABLE(ios, tvos, watchos)
431XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
432bool
433xpc_activity_set_state(xpc_activity_t activity, xpc_activity_state_t state);
434
435/*!
436 * @function xpc_activity_should_defer
437 *
438 * @abstract
439 * Test whether an activity should be deferred.
440 *
441 * @discussion
442 * This function may be used to test whether the criteria of a long-running
443 * activity are still satisfied. If not, the system indicates that the
444 * application should defer the activity. The application may acknowledge the
445 * deferral by calling xpc_activity_set_state() with XPC_ACTIVITY_STATE_DEFER.
446 * Once deferred, the system will place the activity back into the WAIT state
447 * and re-invoke the handler block at the earliest opportunity when the criteria
448 * are once again satisfied.
449 *
450 * @return
451 * Returns true if the activity should be deferred.
452 */
453API_AVAILABLE(macos(10.9))
454API_UNAVAILABLE(ios, tvos, watchos)
455XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
456bool
457xpc_activity_should_defer(xpc_activity_t activity);
458
459/*!
460 * @function xpc_activity_unregister
461 *
462 * @abstract
463 * Unregisters an activity found by its identifier.
464 *
465 * @discussion
466 * A dynamically registered activity will be deleted in response to this call.
467 * Statically registered activity (from a launchd property list) will be
468 * deleted until the job is next loaded (e.g. at next boot).
469 *
470 * Unregistering an activity has no effect on any outstanding xpc_activity_t
471 * objects or any currently executing xpc_activity_handler_t blocks; however,
472 * no new handler block invocations will be made after it is unregistered.
473 *
474 * @param identifier
475 * The identifier of the activity to unregister.
476 */
477API_AVAILABLE(macos(10.9))
478API_UNAVAILABLE(ios, tvos, watchos)
479XPC_EXPORT XPC_NONNULL1
480void
481xpc_activity_unregister(const char *identifier);
482
483__END_DECLS
484XPC_ASSUME_NONNULL_END
485
486#endif // __BLOCKS__
487
488#endif // __XPC_ACTIVITY_H__
489