123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419 |
- #ifndef __XPC_ACTIVITY_H__
- #define __XPC_ACTIVITY_H__
- #ifndef __XPC_INDIRECT__
- #error "Please #include <xpc/xpc.h> instead of this file directly."
- // For HeaderDoc.
- #include <xpc/base.h>
- #endif // __XPC_INDIRECT__
- #ifdef __BLOCKS__
- __BEGIN_DECLS
- /*
- * The following are a collection of keys and values used to set an activity's
- * execution criteria.
- */
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_INTERVAL;
- /*!
- * @constant XPC_ACTIVITY_REPEATING
- * A boolean property indicating whether this is a repeating activity.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_REPEATING;
- /*!
- * @constant XPC_ACTIVITY_DELAY
- * An integer property indicating the number of seconds to delay before
- * beginning the activity.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_DELAY;
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_GRACE_PERIOD;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_1_MIN;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_5_MIN;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_15_MIN;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_30_MIN;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_1_HOUR;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_4_HOURS;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_8_HOURS;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_1_DAY;
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const int64_t XPC_ACTIVITY_INTERVAL_7_DAYS;
- /*!
- * @constant XPC_ACTIVITY_PRIORITY
- * A string property indicating the priority of the activity.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_PRIORITY;
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_PRIORITY_MAINTENANCE;
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_PRIORITY_UTILITY;
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_ALLOW_BATTERY;
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP; // bool
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL; // int (%)
- /*!
- * @constant 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const char *XPC_ACTIVITY_REQUIRE_HDD_SPINNING; // bool
- /*!
- * @define 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.
- */
- #define XPC_TYPE_ACTIVITY (&_xpc_type_activity)
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- XPC_TYPE(_xpc_type_activity);
- /*!
- * @typedef xpc_activity_t
- *
- * @abstract
- * An XPC activity object.
- *
- * @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.
- */
- XPC_DECL(xpc_activity);
- /*!
- * @typedef xpc_activity_handler_t
- *
- * @abstract
- * A block that is called when an XPC activity becomes eligible to run.
- */
- typedef void (^xpc_activity_handler_t)(xpc_activity_t activity);
- /*!
- * @constant 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).
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- const xpc_object_t XPC_ACTIVITY_CHECK_IN;
- /*!
- * @function xpc_activity_register
- *
- * @abstract
- * Registers an activity with the system.
- *
- * @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.
- *
- * @param identifier
- * A unique identifier for the activity. Each application has its own namespace.
- *
- * @param criteria
- * A dictionary of criteria for the activity.
- *
- * @param 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3
- void
- xpc_activity_register(const char *identifier, xpc_object_t criteria,
- xpc_activity_handler_t handler);
- /*!
- * @function xpc_activity_copy_criteria
- *
- * @abstract
- * 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.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_RETURNS_RETAINED
- xpc_object_t
- xpc_activity_copy_criteria(xpc_activity_t activity);
- /*!
- * @function xpc_activity_set_criteria
- *
- * @abstract
- * Modifies the execution criteria of an activity.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2
- void
- xpc_activity_set_criteria(xpc_activity_t activity, xpc_object_t criteria);
- /*!
- * @enum xpc_activity_state_t
- * 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
- *
- * @constant 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.
- *
- * @constant 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().
- *
- * @constant XPC_ACTIVITY_STATE_RUN
- * An activity in this state is eligible to run based on its criteria.
- *
- * @constant 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().
- *
- * @constant 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.
- *
- * @constant 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.
- */
- 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,
- };
- typedef long xpc_activity_state_t;
- /*!
- * @function xpc_activity_get_state
- *
- * @abstract
- * Returns the current state of an activity.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- xpc_activity_state_t
- xpc_activity_get_state(xpc_activity_t activity);
- /*!
- * @function xpc_activity_set_state
- *
- * @abstract
- * Updates the current state of an activity.
- *
- * @return
- * Returns true if the state was successfully updated; otherwise, returns
- * false if the requested state transition is not valid.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1
- bool
- xpc_activity_set_state(xpc_activity_t activity, xpc_activity_state_t state);
- /*!
- * @function xpc_activity_should_defer
- *
- * @abstract
- * Test whether an 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.
- *
- * @return
- * Returns true if the activity should be deferred.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT
- bool
- xpc_activity_should_defer(xpc_activity_t activity);
- /*!
- * @function xpc_activity_unregister
- *
- * @abstract
- * Unregisters an activity found by its identifier.
- *
- * @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.
- *
- * @param identifier
- * The identifier of the activity to unregister.
- */
- __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
- XPC_EXPORT XPC_NONNULL1
- void
- xpc_activity_unregister(const char *identifier);
- __END_DECLS
- #endif // __BLOCKS__
- #endif // __XPC_ACTIVITY_H__
|