activity.h (16579B) - Raw
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 12 XPC_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 */ 36 API_AVAILABLE(macos(10.9)) 37 API_UNAVAILABLE(ios) 38 XPC_EXPORT 39 const char * const XPC_ACTIVITY_INTERVAL; 40 41 /*! 42 * @constant XPC_ACTIVITY_REPEATING 43 * A boolean property indicating whether this is a repeating activity. 44 */ 45 API_AVAILABLE(macos(10.9)) 46 API_UNAVAILABLE(ios) 47 XPC_EXPORT 48 const 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 */ 55 API_AVAILABLE(macos(10.9)) 56 API_UNAVAILABLE(ios) 57 XPC_EXPORT 58 const 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 */ 65 API_AVAILABLE(macos(10.9)) 66 API_UNAVAILABLE(ios) 67 XPC_EXPORT 68 const char * const XPC_ACTIVITY_GRACE_PERIOD; 69 70 71 API_AVAILABLE(macos(10.9)) 72 API_UNAVAILABLE(ios) 73 XPC_EXPORT 74 const int64_t XPC_ACTIVITY_INTERVAL_1_MIN; 75 76 API_AVAILABLE(macos(10.9)) 77 API_UNAVAILABLE(ios) 78 XPC_EXPORT 79 const int64_t XPC_ACTIVITY_INTERVAL_5_MIN; 80 81 API_AVAILABLE(macos(10.9)) 82 API_UNAVAILABLE(ios) 83 XPC_EXPORT 84 const int64_t XPC_ACTIVITY_INTERVAL_15_MIN; 85 86 API_AVAILABLE(macos(10.9)) 87 API_UNAVAILABLE(ios) 88 XPC_EXPORT 89 const int64_t XPC_ACTIVITY_INTERVAL_30_MIN; 90 91 API_AVAILABLE(macos(10.9)) 92 API_UNAVAILABLE(ios) 93 XPC_EXPORT 94 const int64_t XPC_ACTIVITY_INTERVAL_1_HOUR; 95 96 API_AVAILABLE(macos(10.9)) 97 API_UNAVAILABLE(ios) 98 XPC_EXPORT 99 const int64_t XPC_ACTIVITY_INTERVAL_4_HOURS; 100 101 API_AVAILABLE(macos(10.9)) 102 API_UNAVAILABLE(ios) 103 XPC_EXPORT 104 const int64_t XPC_ACTIVITY_INTERVAL_8_HOURS; 105 106 API_AVAILABLE(macos(10.9)) 107 API_UNAVAILABLE(ios) 108 XPC_EXPORT 109 const int64_t XPC_ACTIVITY_INTERVAL_1_DAY; 110 111 API_AVAILABLE(macos(10.9)) 112 API_UNAVAILABLE(ios) 113 XPC_EXPORT 114 const 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 */ 120 API_AVAILABLE(macos(10.9)) 121 API_UNAVAILABLE(ios) 122 XPC_EXPORT 123 const 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 */ 138 API_AVAILABLE(macos(10.9)) 139 API_UNAVAILABLE(ios) 140 XPC_EXPORT 141 const 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 */ 156 API_AVAILABLE(macos(10.9)) 157 API_UNAVAILABLE(ios) 158 XPC_EXPORT 159 const 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 */ 167 API_AVAILABLE(macos(10.9)) 168 API_UNAVAILABLE(ios) 169 XPC_EXPORT 170 const 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 */ 180 API_AVAILABLE(macos(10.9)) 181 API_UNAVAILABLE(ios) 182 XPC_EXPORT 183 const 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 */ 195 API_AVAILABLE(macos(12.0)) 196 API_UNAVAILABLE(ios, watchos) 197 XPC_EXPORT 198 const 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") 208 XPC_EXPORT 209 const 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") 219 XPC_EXPORT 220 const 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) 227 API_AVAILABLE(macos(10.9)) 228 API_UNAVAILABLE(ios) 229 XPC_EXPORT 230 XPC_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 */ 246 XPC_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 */ 254 XPC_NONNULL1 255 typedef 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 */ 264 API_AVAILABLE(macos(10.9)) 265 API_UNAVAILABLE(ios) 266 XPC_EXPORT 267 const 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 */ 304 API_AVAILABLE(macos(10.9)) 305 API_UNAVAILABLE(ios) 306 XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 307 void 308 xpc_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 */ 319 API_AVAILABLE(macos(10.9)) 320 API_UNAVAILABLE(ios) 321 XPC_EXPORT XPC_WARN_RESULT XPC_RETURNS_RETAINED XPC_NONNULL1 322 xpc_object_t _Nullable 323 xpc_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 */ 331 API_AVAILABLE(macos(10.9)) 332 API_UNAVAILABLE(ios) 333 XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 334 void 335 xpc_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 */ 397 enum { 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 }; 405 typedef 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 */ 413 API_AVAILABLE(macos(10.9)) 414 API_UNAVAILABLE(ios) 415 XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 416 xpc_activity_state_t 417 xpc_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 */ 429 API_AVAILABLE(macos(10.9)) 430 API_UNAVAILABLE(ios) 431 XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 432 bool 433 xpc_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 */ 453 API_AVAILABLE(macos(10.9)) 454 API_UNAVAILABLE(ios) 455 XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 456 bool 457 xpc_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 */ 477 API_AVAILABLE(macos(10.9)) 478 API_UNAVAILABLE(ios) 479 XPC_EXPORT XPC_NONNULL1 480 void 481 xpc_activity_unregister(const char *identifier); 482 483 __END_DECLS 484 XPC_ASSUME_NONNULL_END 485 486 #endif // __BLOCKS__ 487 488 #endif // __XPC_ACTIVITY_H__ 489