Mac Developer Library


activity.h Reference

Deployment Target:

On This Page

activity.h Reference

Included Headers

  • <xpc/base.h>


  • Returns an XPC dictionary describing the execution criteria of an activity. This will return NULL in cases where the activity has already completed, e.g. when checking in to an event that finished and was not rescheduled.


    extern XPC_RETURNS_RETAINED xpc_object_t xpc_activity_copy_criteria( xpc_activity_t activity);

  • Returns the current state of an activity.


    extern xpc_activity_state_t xpc_activity_get_state( xpc_activity_t activity);

  • Registers an activity with the system.


    extern void xpc_activity_register( const char *identifier, xpc_object_t criteria, xpc_activity_handler_t handler);



    A unique identifier for the activity. Each application has its own namespace.


    A dictionary of criteria for the activity.


    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.


    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.

  • Modifies the execution criteria of an activity.


    extern void xpc_activity_set_criteria( xpc_activity_t activity, xpc_object_t criteria);

  • Updates the current state of an activity.


    extern bool xpc_activity_set_state( xpc_activity_t activity, xpc_activity_state_t state);

    Return Value

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

  • Test whether an activity should be deferred.


    extern bool xpc_activity_should_defer( xpc_activity_t activity);

    Return Value

    Returns true if the activity should be deferred.


    This function may be used to test whether the criteria of a long-running activity are still satisfied. If not, the system indicates that the application should defer the activity. The application may acknowledge the deferral by calling xpc_activity_set_state() with XPC_ACTIVITY_STATE_DEFER. Once deferred, the system will place the activity back into the WAIT state and re-invoke the handler block at the earliest opportunity when the criteria are once again satisfied.

  • Unregisters an activity found by its identifier.


    extern void xpc_activity_unregister( const char *identifier);



    The identifier of the activity to unregister.


    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.

  • An XPC activity object.


    XPC_DECL( xpc_activity);


    This object represents a set of execution criteria and a current execution state for background activity on the system. Once an activity is registered, the system will evaluate 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 will be updated and an invocation of its handler block will be made.


  • A block that is called when an XPC activity becomes eligible to run.


    typedef void (^xpc_activity_handler_t)( xpc_activity_t activity);


See the Overview section above for header-level documentation.

  • Declaration

    #define XPC_TYPE_ACTIVITY (&_xpc_type_activity)



      A type representing a connection to a named service. This connection is bidirectional and can be used to both send and receive messages. A connection carries the credentials of the remote service provider.

  • Declaration

    extern const char *XPC_ACTIVITY_ALLOW_BATTERY; extern const xpc_object_t XPC_ACTIVITY_CHECK_IN; extern const char *XPC_ACTIVITY_DELAY; extern const char *XPC_ACTIVITY_GRACE_PERIOD; extern const char *XPC_ACTIVITY_INTERVAL; extern const char *XPC_ACTIVITY_PRIORITY; extern const char *XPC_ACTIVITY_PRIORITY_MAINTENANCE; extern const char *XPC_ACTIVITY_PRIORITY_UTILITY; extern const char *XPC_ACTIVITY_REPEATING; extern const char *XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL; // int (%) extern const char *XPC_ACTIVITY_REQUIRE_HDD_SPINNING; // bool extern const char *XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP; // bool



      A Boolean value indicating whether the activity should be allowed to run while the computer is on battery power. The default value is false for maintenance priority activity and true for utility priority activity.


      This constant may be passed to xpc_activity_register() as the criteria dictionary in order to check in with the system for previously registered activity using the same identifier (for example, an activity taken from a launchd property list).


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


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


      An integer property indicating the desired time interval (in seconds) of the activity. The activity will not be 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 'interval' seconds apart, but on average will be 'interval' seconds apart. The presence of this key implies the following, unless overridden: - 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 allowed to pass after the end of the interval before more aggressive scheduling occurs. The grace period does not increase the size of the interval.


      A string property indicating the priority of the activity.


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


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


      A boolean property indicating whether this is a repeating activity.


      An integer percentage of minimum battery charge required to allow the activity to run. A default minimum battery level is determined by the system.


      A Boolean value indicating whether the activity should only be performed while the hard disk drive (HDD) is spinning. Computers with flash storage are considered to be equivalent to HDD spinning. Defaults to false.


      A Boolean value indicating whether the activity should only be performed while the primary screen is in sleep mode. Defaults to false.

  • Declaration




      An activity in this state has just completed a checkin with the system after XPC_ACTIVITY_CHECK_IN was provided as the criteria dictionary to xpc_activity_register. The state gives the application an opportunity to inspect and modify the activity's criteria.


      An activity in this state is waiting for an opportunity to run. This value is never returned within the activity's handler block, as the block is invoked in response to XPC_ACTIVITY_STATE_CHECK_IN or XPC_ACTIVITY_STATE_RUN.

      Note: A launchd job may idle exit while an activity is in the wait state and be relaunched in response to the activity becoming runnable. The launchd job simply needs to re-register for the activity on its next launch by passing XPC_ACTIVITY_STATE_CHECK_IN to xpc_activity_register().


      An activity in this state is eligible to run based on its criteria.


      An application may pass this value to xpc_activity_set_state() to indicate that the activity should be deferred (placed back into the WAIT state) until a time when its criteria are met again. Deferring an activity does not reset any of its time-based criteria (in other words, it will remain past due). This should be done in response to observing xpc_activity_should_defer().


      An application may pass this value to xpc_activity_set_state() to indicate that the activity will continue its operation beyond the return of its handler block. This can be used to extend an activity to include asynchronous operations. The activity's handler block will not be invoked again until the state has been updated to either XPC_ACTIVITY_STATE_DEFER or, in the case of repeating activity, XPC_ACTIVITY_STATE_DONE.


      An application may pass this value to xpc_activity_set_state() to indicate that the activity has completed. For non-repeating activity, the resources associated with the activity will be automatically released upon return from the handler block. For repeating activity, timers present in the activity's criteria will be reset.


    An activity is defined to be in one of the following states. Applications may check the current state of the activity using xpc_activity_get_state() in the handler block provided to xpc_activity_register().

    The application can modify the state of the activity by calling xpc_activity_set_state() with one of the following: - XPC_ACTIVITY_STATE_DEFER - XPC_ACTIVITY_STATE_CONTINUE - XPC_ACTIVITY_STATE_DONE