David Gonzalez Martin 38011a233c Integrate libs
2024-03-02 12:58:12 -06:00

462 lines
16 KiB
C

#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__
XPC_ASSUME_NONNULL_BEGIN
__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 * const 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 * const 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 * const 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 * const 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 * const 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.
*
* Maintenance activities are not permitted to run if the device thermal
* condition exceeds a nominal level or if the battery level is lower than 20%.
* In Low Power Mode (on supported devices), maintenance activities are not
* permitted to run while the device is on battery, or plugged in and the
* battery level is lower than 30%.
*/
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
XPC_EXPORT
const char * const 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.
*
* Utility activities are not permitted to run if the device thermal condition
* exceeds a moderate level or if the battery level is less than 10%. In Low
* Power Mode (on supported devices) when on battery power, utility activities
* are only permitted when they are close to their deadline (90% of their time
* window has elapsed).
*/
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
XPC_EXPORT
const char * const 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 * const XPC_ACTIVITY_ALLOW_BATTERY;
/*!
* @constant XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP
* A Boolean value indicating whether the activity should only be performed
* while device appears to be asleep. Note that the definition of screen sleep
* may vary by platform and may include states where the device is known to be
* idle despite the fact that the display itself is still powered. Defaults to
* false.
*/
__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0)
XPC_EXPORT
const char * const XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP; // bool
/*!
* @constant XPC_ACTIVITY_PREVENT_DEVICE_SLEEP
* A Boolean value indicating whether the activity should prevent system sleep while
* running on battery.
* If this property is set, the activity scheduler will take the appropriate power
* assertion to keep the device (but not the screen) awake while the activity is running.
* Only activities which perform critical system functions that do not want to be
* interrupted by system sleep should set this.
* Setting this property can impact battery life.
*/
__API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0))
XPC_EXPORT
const char * const XPC_ACTIVITY_PREVENT_DEVICE_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_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_9, __IPHONE_7_0, __IPHONE_7_0,
"REQUIRE_BATTERY_LEVEL is not implemented")
XPC_EXPORT
const char * const 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_BUT_DEPRECATED_MSG(__MAC_10_9, __MAC_10_9, __IPHONE_7_0, __IPHONE_7_0,
"REQUIRE_HDD_SPINNING is not implemented")
XPC_EXPORT
const char * const XPC_ACTIVITY_REQUIRE_HDD_SPINNING; // bool
/*!
* @define XPC_TYPE_ACTIVITY
* A type representing the XPC activity object.
*/
#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.
*/
XPC_NONNULL1
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.
* The identifier should remain constant across registrations, relaunches of
* the application, and reboots. It should identify the kind of work being done,
* not a particular invocation of the work.
*
* @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_NONNULL1
xpc_object_t _Nullable
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).
*
* IMPORTANT:
* This should be done in response to observing xpc_activity_should_defer().
* It should not be done unilaterally. If you determine that conditions are bad
* to do your activity's work for reasons you can't express in a criteria
* dictionary, you should set the activity's state to XPC_ACTIVITY_STATE_DONE.
*
*
* @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 XPC_WARN_RESULT XPC_NONNULL1
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
* deleted until the job is next loaded (e.g. at next boot).
*
* 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
XPC_ASSUME_NONNULL_END
#endif // __BLOCKS__
#endif // __XPC_ACTIVITY_H__