← XPC

XPC activities

XPC Dokümantasyonu

API Collection | XPC

Schedule background activities for the system to execute.

Registration

  • xpc_activity_register(_:_:_:)) func xpc_activity_register(UnsafePointer<CChar>, xpc_object_t, xpc_activity_handler_t) — Registers an activity with the system.
  • xpc_activity_unregister(_:)) func xpc_activity_unregister(UnsafePointer<CChar>) — Unregisters an activity with the specified identifier.
  • XPC_ACTIVITY_CHECK_IN let XPC_ACTIVITY_CHECK_IN: xpc_object_t — A constant to check in with the system for a previously registered activity using the same identifier.
  • xpc_activity_t typealias xpc_activity_t — An XPC activity object.
  • xpc_activity_handler_t typealias xpc_activity_handler_t — A block to call when an XPC activity becomes eligible to run.

State

Execution criteria

  • xpc_activity_copy_criteria(_:)) func xpc_activity_copy_criteria(xpc_activity_t) -> xpc_object_t? — Returns an XPC dictionary that describes the execution criteria of an activity.
  • xpc_activity_set_criteria(_:_:)) func xpc_activity_set_criteria(xpc_activity_t, xpc_object_t) — Modifies the execution criteria of an activity.

Scheduling

  • XPC_ACTIVITY_REPEATING let XPC_ACTIVITY_REPEATING: UnsafePointer<CChar> — A Boolean property that indicates whether this is a repeating activity.
  • XPC_ACTIVITY_DELAY let XPC_ACTIVITY_DELAY: UnsafePointer<CChar> — An integer property that indicates the number of seconds to delay before beginning the activity.
  • XPC_ACTIVITY_GRACE_PERIOD let XPC_ACTIVITY_GRACE_PERIOD: UnsafePointer<CChar> — An integer property that indicates the number of seconds to allow as a grace period before the scheduling of the activity becomes more aggressive.

Time Intervals

Priority

  • XPC_ACTIVITY_PRIORITY let XPC_ACTIVITY_PRIORITY: UnsafePointer<CChar> — A string property that indicates the priority of the activity.
  • XPC_ACTIVITY_PRIORITY_MAINTENANCE let XPC_ACTIVITY_PRIORITY_MAINTENANCE: UnsafePointer<CChar> — A string that indicates an activity is maintenance priority.
  • XPC_ACTIVITY_PRIORITY_UTILITY let XPC_ACTIVITY_PRIORITY_UTILITY: UnsafePointer<CChar> — A string that indicates an activity is utility priority.

Power consumption

  • XPC_ACTIVITY_ALLOW_BATTERY let XPC_ACTIVITY_ALLOW_BATTERY: UnsafePointer<CChar> — A Boolean value that indicates whether to allow the activity to run while the computer is on battery power.
  • XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP let XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP: UnsafePointer<CChar> — A Boolean value that indicates whether the activity performs only while the primary screen is in sleep mode.
  • XPC_ACTIVITY_PREVENT_DEVICE_SLEEP let XPC_ACTIVITY_PREVENT_DEVICE_SLEEP: UnsafePointer<CChar> — A Boolean that indicates whether the activity prevents the system from sleeping while on battery power.

Deprecated

  • XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL let XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL: UnsafePointer<CChar> — An integer percentage of minimum battery charge required to allow the activity to run.
  • XPC_ACTIVITY_REQUIRE_HDD_SPINNING let XPC_ACTIVITY_REQUIRE_HDD_SPINNING: UnsafePointer<CChar> — A Boolean value indicating whether the activity should only be performed while the hard disk drive (HDD) is spinning.

XPC_ACTIVITY_CHECK_IN

Global Variable | XPC

A constant to check in with the system for a previously registered activity using the same identifier.

let XPC_ACTIVITY_CHECK_IN: xpc_object_t

Pass this constant to xpc_activity_register(_:_:_:)) as the criteria dictionary to check in with the system for previously registered activity using the same identifier (for example, an activity from a launchd property list).

See Also

Registration

xpc_activity_state_t

API Collection | XPC

A type that represents the state of an activity.

An activity is in one of the states that xpc_activity_state_t defines. Apps may check the current state of the activity using xpc_activity_get_state(_:)) in the handler block that you provide to xpc_activity_register(_:_:_:)).

The app can modify the state of the activity by calling xpc_activity_set_state(_:_:)) with one of the following:

Constants

See Also

State

XPC_ACTIVITY_ALLOW_BATTERY

Global Variable | XPC

A Boolean value that indicates whether to allow the activity to run while the computer is on battery power.

let XPC_ACTIVITY_ALLOW_BATTERY: UnsafePointer<CChar>

The default value is false for maintenance priority activity and true for utility priority activity.

See Also

Power consumption

xpc_activity_copy_criteria(_:)

Function | XPC

Returns an XPC dictionary that describes the execution criteria of an activity.

func xpc_activity_copy_criteria(_ activity: xpc_activity_t) -> xpc_object_t?

Returns NULL in cases where the activity has already completed, for example, when checking in to an event that finished and wasn’t rescheduled.

See Also

Execution criteria

XPC_ACTIVITY_DELAY

Global Variable | XPC

An integer property that indicates the number of seconds to delay before beginning the activity.

let XPC_ACTIVITY_DELAY: UnsafePointer<CChar>

See Also

Scheduling

xpc_activity_get_state(_:)

Function | XPC

Returns the current state of an activity.

func xpc_activity_get_state(_ activity: xpc_activity_t) -> xpc_activity_state_t

See Also

State

xpc_activity_handler_t

Type Alias | XPC

A block to call when an XPC activity becomes eligible to run.

typealias xpc_activity_handler_t = (xpc_activity_t) -> Void

See Also

Registration

XPC_ACTIVITY_INTERVAL

Global Variable | XPC

An integer property that indicates the desired time interval of the activity in seconds.

let XPC_ACTIVITY_INTERVAL: UnsafePointer<CChar>

The activity doesn’t run more than once per time interval. Due to the nature of XPC Activity finding an opportune time to run the activity, any two occurrences may be more or less than XPC_ACTIVITY_INTERVAL seconds apart, but on average are XPC_ACTIVITY_INTERVAL seconds apart. The presence of this key implies the following, unless you override these values:

  • XPC_ACTIVITY_REPEATING with a value of true
  • XPC_ACTIVITY_DELAY with a value of half the interval. The delay enforces a minimum distance between any two occurrences.
  • XPC_ACTIVITY_GRACE_PERIOD with a value of half the interval. The grace period is the amount of time that passes after the end of the interval before more aggressive scheduling occurs. The grace period doesn’t increase the size of the interval.

See Also

Time Intervals

XPC_ACTIVITY_GRACE_PERIOD

Global Variable | XPC

An integer property that indicates the number of seconds to allow as a grace period before the scheduling of the activity becomes more aggressive.

let XPC_ACTIVITY_GRACE_PERIOD: UnsafePointer<CChar>

See Also

Scheduling

XPC_ACTIVITY_INTERVAL_15_MIN

Global Variable | XPC

A constant that represents a 15-minute time interval.

let XPC_ACTIVITY_INTERVAL_15_MIN: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_1_DAY

Global Variable | XPC

A constant that represents a one-day time interval.

let XPC_ACTIVITY_INTERVAL_1_DAY: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_1_HOUR

Global Variable | XPC

A constant that represents a 1-hour time interval.

let XPC_ACTIVITY_INTERVAL_1_HOUR: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_1_MIN

Global Variable | XPC

A constant that represents a 1-minute time interval.

let XPC_ACTIVITY_INTERVAL_1_MIN: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_4_HOURS

Global Variable | XPC

A constant that represents a 4-hour time interval.

let XPC_ACTIVITY_INTERVAL_4_HOURS: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_30_MIN

Global Variable | XPC

A constant that represents a 30-minute time interval.

let XPC_ACTIVITY_INTERVAL_30_MIN: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_5_MIN

Global Variable | XPC

A constant that represents a 5-minute time interval.

let XPC_ACTIVITY_INTERVAL_5_MIN: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_7_DAYS

Global Variable | XPC

A constant that represents a seven-day time interval.

let XPC_ACTIVITY_INTERVAL_7_DAYS: Int64

See Also

Time Intervals

XPC_ACTIVITY_INTERVAL_8_HOURS

Global Variable | XPC

A constant that represents an 8-hour time interval.

let XPC_ACTIVITY_INTERVAL_8_HOURS: Int64

See Also

Time Intervals

XPC_ACTIVITY_PREVENT_DEVICE_SLEEP

Global Variable | XPC

A Boolean that indicates whether the activity prevents the system from sleeping while on battery power.

let XPC_ACTIVITY_PREVENT_DEVICE_SLEEP: UnsafePointer<CChar>

When set to true, the activity scheduler takes the necessary power assertions to keep the device awake, excluding the screen. Only set this property for activities that perform critical system functions, and that system sleep can’t interrupt. Note that setting this property can affect battery life.

See Also

Power consumption

XPC_ACTIVITY_PRIORITY_MAINTENANCE

Global Variable | XPC

A string that indicates an activity is maintenance priority.

let XPC_ACTIVITY_PRIORITY_MAINTENANCE: UnsafePointer<CChar>

Maintenance priority is intended for user-invisible maintenance tasks such as garbage collection or optimization.

See Also

Priority

XPC_ACTIVITY_PRIORITY

Global Variable | XPC

A string property that indicates the priority of the activity.

let XPC_ACTIVITY_PRIORITY: UnsafePointer<CChar>

See Also

Priority

XPC_ACTIVITY_PRIORITY_UTILITY

Global Variable | XPC

A string that indicates an activity is utility priority.

let XPC_ACTIVITY_PRIORITY_UTILITY: UnsafePointer<CChar>

Utility priority is intended for user-visible tasks such as fetching data from the network, copying files, or importing data.

See Also

Priority

xpc_activity_register(_:_:_:)

Function | XPC

Registers an activity with the system.

func xpc_activity_register(_ identifier: UnsafePointer<CChar>, _ criteria: xpc_object_t, _ handler: @escaping xpc_activity_handler_t)

Registers a new activity with the system. The criteria of the activity are described by the dictionary passed to this function. If an activity with the same identifier already exists, the criteria provided override the existing criteria unless the special dictionary XPC_ACTIVITY_CHECK_IN is used. The XPC_ACTIVITY_CHECK_IN dictionary instructs the system to first look up an existing activity without modifying its criteria. Once the existing activity is found (or a new one is created with an empty set of criteria) the handler will be called with an activity object in the XPC_ACTIVITY_STATE_CHECK_IN state.

Parameters

  • identifier: A unique identifier for the activity. Each application has its own namespace.
  • criteria: A dictionary of criteria for the activity.
  • handler: The handler block to be called when the activity changes state to one of the following states:
  • XPC_ACTIVITY_STATE_CHECK_IN (optional)
  • XPC_ACTIVITY_STATE_RUN

The handler block is never invoked reentrantly. It will be invoked on a dispatch queue with an appropriate priority to perform the activity.

See Also

Registration

XPC_ACTIVITY_REPEATING

Global Variable | XPC

A Boolean property that indicates whether this is a repeating activity.

let XPC_ACTIVITY_REPEATING: UnsafePointer<CChar>

See Also

Scheduling

XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL

Global Variable | XPC

An integer percentage of minimum battery charge required to allow the activity to run.

let XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL: UnsafePointer<CChar>

A default minimum battery level is determined by the system.

See Also

Deprecated

XPC_ACTIVITY_REQUIRE_HDD_SPINNING

Global Variable | XPC

A Boolean value indicating whether the activity should only be performed while the hard disk drive (HDD) is spinning.

let XPC_ACTIVITY_REQUIRE_HDD_SPINNING: UnsafePointer<CChar>

Computers with flash storage are considered to be equivalent to HDD spinning. Defaults to NO.

See Also

Deprecated

XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP

Global Variable | XPC

A Boolean value that indicates whether the activity performs only while the primary screen is in sleep mode.

let XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP: UnsafePointer<CChar>

Defaults to false.

See Also

Power consumption

xpc_activity_should_defer(_:)

Function | XPC

Tests whether to defer an activity.

func xpc_activity_should_defer(_ activity: xpc_activity_t) -> Bool

Returns true if the activity should be deferred.

See Also

State

xpc_activity_set_criteria(_:_:)

Function | XPC

Modifies the execution criteria of an activity.

func xpc_activity_set_criteria(_ activity: xpc_activity_t, _ criteria: xpc_object_t)

See Also

Execution criteria

xpc_activity_set_state(_:_:)

Function | XPC

Updates the current state of an activity.

func xpc_activity_set_state(_ activity: xpc_activity_t, _ state: xpc_activity_state_t) -> Bool

Returns true if the state was successfully updated; otherwise, returns false if the requested state transition is not valid.

See Also

State

XPC_ACTIVITY_STATE_CONTINUE

Global Variable | XPC

The activity continues its operation beyond the return of its handler block.

var XPC_ACTIVITY_STATE_CONTINUE: Int { get }

An app may pass this value to xpc_activity_set_state(_:_:)) to indicate that the activity continues its operation beyond the return of its handler block. Use this to extend an activity to include asynchronous operations. The system doesn’t invoke the activity’s handler block again until the state updates to either XPC_ACTIVITY_STATE_DEFER or, in the case of repeating activity, XPC_ACTIVITY_STATE_DONE.

See Also

State

XPC_ACTIVITY_STATE_DEFER

Global Variable | XPC

The activity needs to wait until it satisfies its criteria again.

var XPC_ACTIVITY_STATE_DEFER: Int { get }

An app may pass this value to xpc_activity_set_state(_:_:)) to indicate that the system needs to defer the activity (place it back into the XPC_ACTIVITY_STATE_WAIT state) until satisfying its criteria again. Deferring an activity doesn’t reset any of its time-based criteria; it remains past due. Do this in response to observing xpc_activity_should_defer(_:)).

See Also

State

XPC_ACTIVITY_STATE_CHECK_IN

Global Variable | XPC

The activity has completed a check-in with the system.

var XPC_ACTIVITY_STATE_CHECK_IN: Int { get }

An activity in this state has just completed a check-in with the system after providing XPC_ACTIVITY_CHECK_IN as the criteria dictionary to xpc_activity_register(_:_:_:)). The state gives the app an opportunity to inspect and modify the activity’s criteria.

See Also

State

XPC_ACTIVITY_STATE_DONE

Global Variable | XPC

The activity is complete.

var XPC_ACTIVITY_STATE_DONE: Int { get }

An app may pass this value to xpc_activity_set_state(_:_:)) to indicate when the activity completes. For nonrepeating activity, the resources for the activity automatically release upon return from the handler block. For repeating activity, timers present in the activity’s criteria reset.

See Also

State

XPC_ACTIVITY_STATE_RUN

Global Variable | XPC

The activity is eligible to run according to its criteria.

var XPC_ACTIVITY_STATE_RUN: Int { get }

See Also

State

XPC_ACTIVITY_STATE_WAIT

Global Variable | XPC

The activity is waiting for an opportunity to run.

var XPC_ACTIVITY_STATE_WAIT: Int { get }

This value never returns within the activity’s handler block because the block’s invocation is in response to XPC_ACTIVITY_STATE_CHECK_IN or XPC_ACTIVITY_STATE_RUN.

A launchd job may idle exit while an activity is in the wait state and relaunch in response to the activity becoming runnable. The launchd job simply needs to reregister for the activity on its next launch by passing XPC_ACTIVITY_STATE_CHECK_IN to xpc_activity_register(_:_:_:)).

See Also

State

xpc_activity_t

Type Alias | XPC

An XPC activity object.

typealias xpc_activity_t = xpc_object_t

This object represents a set of execution criteria and a current execution state for background activity on the system. After registering an activity, the system evaluates its criteria to determine whether the activity is eligible to run under current system conditions. When an activity becomes eligible to run, its execution state updates and an invocation of its handler block occurs.

See Also

Registration

xpc_activity_state_t

Type Alias | XPC

A type that represents the state of an activity.

typealias xpc_activity_state_t = Int

An activity is in one of the states that xpc_activity_state_t defines. Apps may check the current state of the activity using xpc_activity_get_state(_:)) in the handler block that you provide to xpc_activity_register(_:_:_:)).

The app can modify the state of the activity by calling xpc_activity_set_state(_:_:)) with one of the following:

See Also

State

xpc_activity_unregister(_:)

Function | XPC

Unregisters an activity with the specified identifier.

func xpc_activity_unregister(_ identifier: UnsafePointer<CChar>)

A dynamically registered activity will be deleted in response to this call. Statically registered activity (from a launchd property list) will be reverted to its original criteria if any modifications were made.

Unregistering an activity has no effect on any outstanding xpc_activity_t objects or any currently executing xpc_activity_handler_t blocks; however, no new handler block invocations will be made after it is unregistered.

Parameters

  • identifier: The identifier of the activity to unregister.

See Also

Registration