Mac Developer Library

Developer

activity.h Reference

Options
Deployment Target:

On This Page
Language:

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

    Swift

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

    Objective-C

    xpc_object_t xpc_activity_copy_criteria ( xpc_activity_t activity );

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

  • Returns the current state of an activity.

    Declaration

    Swift

    func xpc_activity_get_state(_ activity: xpc_activity_t!) -> xpc_activity_state_t

    Objective-C

    xpc_activity_state_t xpc_activity_get_state ( xpc_activity_t activity );

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

  • Registers an activity with the system.

    Declaration

    Swift

    func xpc_activity_register(_ identifier: UnsafePointer<Int8>, _ criteria: xpc_object_t!, _ handler: xpc_activity_handler_t!)

    Objective-C

    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.

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

  • Modifies the execution criteria of an activity.

    Declaration

    Swift

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

    Objective-C

    void xpc_activity_set_criteria ( xpc_activity_t activity, xpc_object_t criteria );

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

  • Updates the current state of an activity.

    Declaration

    Swift

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

    Objective-C

    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.

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

  • Test whether an activity should be deferred.

    Declaration

    Swift

    func xpc_activity_should_defer(_ activity: xpc_activity_t!) -> Bool

    Objective-C

    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.

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

  • Unregisters an activity found by its identifier.

    Declaration

    Swift

    func xpc_activity_unregister(_ identifier: UnsafePointer<Int8>)

    Objective-C

    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.

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

  • An XPC activity object.

    Declaration

    Objective-C

    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.

    Import Statement

Callbacks

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

    Declaration

    Objective-C

    typedef void (^xpc_activity_handler_t)( xpc_activity_t activity);

    Import Statement

    import XPC

    Availability

    Available in OS X v10.9 and later.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    #define XPC_TYPE_ACTIVITY (&_xpc_type_activity)

    Constants

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

      Available in OS X v10.9 and later.

    Import Statement

  • Declaration

    Swift

    var XPC_ACTIVITY_ALLOW_BATTERY: UnsafePointer<Int8> let XPC_ACTIVITY_CHECK_IN: xpc_object_t! var XPC_ACTIVITY_DELAY: UnsafePointer<Int8> var XPC_ACTIVITY_GRACE_PERIOD: UnsafePointer<Int8> var XPC_ACTIVITY_INTERVAL: UnsafePointer<Int8> var XPC_ACTIVITY_PRIORITY: UnsafePointer<Int8> var XPC_ACTIVITY_PRIORITY_MAINTENANCE: UnsafePointer<Int8> var XPC_ACTIVITY_PRIORITY_UTILITY: UnsafePointer<Int8> var XPC_ACTIVITY_REPEATING: UnsafePointer<Int8> var XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL: UnsafePointer<Int8> var XPC_ACTIVITY_REQUIRE_HDD_SPINNING: UnsafePointer<Int8> var XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP: UnsafePointer<Int8>

    Objective-C

    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

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_CHECK_IN

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

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_DELAY

      XPC_ACTIVITY_DELAY

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

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_GRACE_PERIOD

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_INTERVAL

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_PRIORITY

      XPC_ACTIVITY_PRIORITY

      A string property indicating the priority of the activity.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_PRIORITY_MAINTENANCE

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_PRIORITY_UTILITY

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_REPEATING

      XPC_ACTIVITY_REPEATING

      A boolean property indicating whether this is a repeating activity.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_REQUIRE_HDD_SPINNING

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP

      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.

      Available in OS X v10.9 and later.

    Import Statement

  • Declaration

    Swift

    var XPC_ACTIVITY_STATE_CHECK_IN: Int { get } var XPC_ACTIVITY_STATE_WAIT: Int { get } var XPC_ACTIVITY_STATE_RUN: Int { get } var XPC_ACTIVITY_STATE_DEFER: Int { get } var XPC_ACTIVITY_STATE_CONTINUE: Int { get } var XPC_ACTIVITY_STATE_DONE: Int { get }

    Objective-C

    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

      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.

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_STATE_WAIT

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

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_STATE_RUN

      XPC_ACTIVITY_STATE_RUN

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

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_STATE_DEFER

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

      Available in OS X v10.9 and later.

    • XPC_ACTIVITY_STATE_CONTINUE

      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.

      Available in OS X v10.9 and later.

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

      Available in OS X v10.9 and later.

    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

    Import Statement