Mac Developer Library

Developer

activity.h Reference

Options
Deployment Target:

On This Page

activity.h Reference

Included Headers

  • <xpc/base.h>

Functions

  • 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.

    Declaration

    extern XPC_RETURNS_RETAINED xpc_object_t xpc_activity_copy_criteria( xpc_activity_t activity);

  • Returns the current state of an activity.

    Declaration

    extern xpc_activity_state_t xpc_activity_get_state( xpc_activity_t activity);

  • Registers an activity with the system.

    Declaration

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

    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.

    Discussion

    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.

    Declaration

    extern void xpc_activity_set_criteria( xpc_activity_t activity, xpc_object_t criteria);

  • Updates the current state of an activity.

    Declaration

    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.

    Declaration

    extern bool xpc_activity_should_defer( xpc_activity_t activity);

    Return Value

    Returns true if the activity should be deferred.

    Discussion

    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.

    Declaration

    extern void xpc_activity_unregister( const char *identifier);

    Parameters

    identifier

    The identifier of the activity to unregister.

    Discussion

    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.

    Declaration

    XPC_DECL( xpc_activity);

    Discussion

    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.

Callbacks

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

    Declaration

    typedef void (^xpc_activity_handler_t)( xpc_activity_t activity);

Constants

See the Overview section above for header-level documentation.

  • Declaration

    #define XPC_TYPE_ACTIVITY (&_xpc_type_activity)

    Constants

    • 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

    Constants

    • XPC_ACTIVITY_ALLOW_BATTERY

      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.

    • XPC_ACTIVITY_CHECK_IN

      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).

    • XPC_ACTIVITY_DELAY

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

    • XPC_ACTIVITY_GRACE_PERIOD

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

    • XPC_ACTIVITY_INTERVAL

      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.

    • XPC_ACTIVITY_PRIORITY

      A string property indicating the priority of the activity.

    • XPC_ACTIVITY_PRIORITY_MAINTENANCE

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

    • XPC_ACTIVITY_PRIORITY_UTILITY

      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.

    • XPC_ACTIVITY_REPEATING

      A boolean property indicating whether this is a repeating activity.

    • XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL

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

    • XPC_ACTIVITY_REQUIRE_HDD_SPINNING

      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.

    • XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP

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

  • Declaration

    enum { XPC_ACTIVITY_STATE_CHECK_IN, XPC_ACTIVITY_STATE_WAIT, XPC_ACTIVITY_STATE_RUN, XPC_ACTIVITY_STATE_DEFER, XPC_ACTIVITY_STATE_CONTINUE, XPC_ACTIVITY_STATE_DONE, };

    Constants

    • XPC_ACTIVITY_STATE_CHECK_IN

      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.

    • XPC_ACTIVITY_STATE_WAIT

      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().

    • XPC_ACTIVITY_STATE_RUN

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

    • XPC_ACTIVITY_STATE_DEFER

      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().

    • XPC_ACTIVITY_STATE_CONTINUE

      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.

    • 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.

    Discussion

    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