From c37f5b7e2877a10521edf498f734d211b74203a4 Mon Sep 17 00:00:00 2001 From: roy <7907969+ohroy@users.noreply.github.com> Date: Tue, 11 Jun 2024 17:59:56 +0800 Subject: [PATCH] feat: integration xpc --- headers/launch.h | 341 +++++ headers/xpc/XPC.apinotes | 7 + headers/xpc/activity.h | 433 ++++++ headers/xpc/availability.h | 108 ++ headers/xpc/base.h | 200 +++ headers/xpc/connection.h | 747 ++++++++++ headers/xpc/debug.h | 23 + headers/xpc/endpoint.h | 22 + headers/xpc/module.modulemap | 10 + headers/xpc/xpc.h | 2647 ++++++++++++++++++++++++++++++++++ 10 files changed, 4538 insertions(+) create mode 100644 headers/launch.h create mode 100644 headers/xpc/XPC.apinotes create mode 100644 headers/xpc/activity.h create mode 100644 headers/xpc/availability.h create mode 100644 headers/xpc/base.h create mode 100644 headers/xpc/connection.h create mode 100644 headers/xpc/debug.h create mode 100644 headers/xpc/endpoint.h create mode 100644 headers/xpc/module.modulemap create mode 100644 headers/xpc/xpc.h diff --git a/headers/launch.h b/headers/launch.h new file mode 100644 index 0000000..669e1f5 --- /dev/null +++ b/headers/launch.h @@ -0,0 +1,341 @@ +/* + * Copyright (c) 2005 Apple Computer, Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +#ifndef __LAUNCH_H__ +#define __LAUNCH_H__ + +#include +#include +#include +#include + +#pragma GCC visibility push(default) + +__BEGIN_DECLS + +#ifdef __GNUC__ +#define __ld_normal __attribute__((__nothrow__)) +#define __ld_setter __attribute__((__nothrow__, __nonnull__)) +#define __ld_getter __attribute__((__nothrow__, __nonnull__, __pure__, __warn_unused_result__)) +#define __ld_iterator(x, y) __attribute__((__nonnull__(x, y))) +#define __ld_allocator __attribute__((__nothrow__, __malloc__, __nonnull__, __warn_unused_result__)) +#else +#define __ld_normal +#define __ld_setter +#define __ld_getter +#define __ld_iterator(x, y) +#define __ld_allocator +#endif + +#define LAUNCH_KEY_SUBMITJOB "SubmitJob" +#define LAUNCH_KEY_REMOVEJOB "RemoveJob" +#define LAUNCH_KEY_STARTJOB "StartJob" +#define LAUNCH_KEY_STOPJOB "StopJob" +#define LAUNCH_KEY_GETJOB "GetJob" +#define LAUNCH_KEY_GETJOBS "GetJobs" +#define LAUNCH_KEY_CHECKIN "CheckIn" + +#define LAUNCH_JOBKEY_LABEL "Label" +#define LAUNCH_JOBKEY_DISABLED "Disabled" +#define LAUNCH_JOBKEY_USERNAME "UserName" +#define LAUNCH_JOBKEY_GROUPNAME "GroupName" +#define LAUNCH_JOBKEY_TIMEOUT "TimeOut" +#define LAUNCH_JOBKEY_EXITTIMEOUT "ExitTimeOut" +#define LAUNCH_JOBKEY_INITGROUPS "InitGroups" +#define LAUNCH_JOBKEY_SOCKETS "Sockets" +#define LAUNCH_JOBKEY_MACHSERVICES "MachServices" +#define LAUNCH_JOBKEY_MACHSERVICELOOKUPPOLICIES "MachServiceLookupPolicies" +#define LAUNCH_JOBKEY_INETDCOMPATIBILITY "inetdCompatibility" +#define LAUNCH_JOBKEY_ENABLEGLOBBING "EnableGlobbing" +#define LAUNCH_JOBKEY_PROGRAMARGUMENTS "ProgramArguments" +#define LAUNCH_JOBKEY_PROGRAM "Program" +#define LAUNCH_JOBKEY_ONDEMAND "OnDemand" +#define LAUNCH_JOBKEY_KEEPALIVE "KeepAlive" +#define LAUNCH_JOBKEY_LIMITLOADTOHOSTS "LimitLoadToHosts" +#define LAUNCH_JOBKEY_LIMITLOADFROMHOSTS "LimitLoadFromHosts" +#define LAUNCH_JOBKEY_LIMITLOADTOSESSIONTYPE "LimitLoadToSessionType" +#define LAUNCH_JOBKEY_LIMITLOADTOHARDWARE "LimitLoadToHardware" +#define LAUNCH_JOBKEY_LIMITLOADFROMHARDWARE "LimitLoadFromHardware" +#define LAUNCH_JOBKEY_RUNATLOAD "RunAtLoad" +#define LAUNCH_JOBKEY_ROOTDIRECTORY "RootDirectory" +#define LAUNCH_JOBKEY_WORKINGDIRECTORY "WorkingDirectory" +#define LAUNCH_JOBKEY_ENVIRONMENTVARIABLES "EnvironmentVariables" +#define LAUNCH_JOBKEY_USERENVIRONMENTVARIABLES "UserEnvironmentVariables" +#define LAUNCH_JOBKEY_UMASK "Umask" +#define LAUNCH_JOBKEY_NICE "Nice" +#define LAUNCH_JOBKEY_HOPEFULLYEXITSFIRST "HopefullyExitsFirst" +#define LAUNCH_JOBKEY_HOPEFULLYEXITSLAST "HopefullyExitsLast" +#define LAUNCH_JOBKEY_LOWPRIORITYIO "LowPriorityIO" +#define LAUNCH_JOBKEY_SESSIONCREATE "SessionCreate" +#define LAUNCH_JOBKEY_STARTONMOUNT "StartOnMount" +#define LAUNCH_JOBKEY_SOFTRESOURCELIMITS "SoftResourceLimits" +#define LAUNCH_JOBKEY_HARDRESOURCELIMITS "HardResourceLimits" +#define LAUNCH_JOBKEY_STANDARDINPATH "StandardInPath" +#define LAUNCH_JOBKEY_STANDARDOUTPATH "StandardOutPath" +#define LAUNCH_JOBKEY_STANDARDERRORPATH "StandardErrorPath" +#define LAUNCH_JOBKEY_DEBUG "Debug" +#define LAUNCH_JOBKEY_WAITFORDEBUGGER "WaitForDebugger" +#define LAUNCH_JOBKEY_QUEUEDIRECTORIES "QueueDirectories" +#define LAUNCH_JOBKEY_WATCHPATHS "WatchPaths" +#define LAUNCH_JOBKEY_STARTINTERVAL "StartInterval" +#define LAUNCH_JOBKEY_STARTCALENDARINTERVAL "StartCalendarInterval" +#define LAUNCH_JOBKEY_BONJOURFDS "BonjourFDs" +#define LAUNCH_JOBKEY_LASTEXITSTATUS "LastExitStatus" +#define LAUNCH_JOBKEY_PID "PID" +#define LAUNCH_JOBKEY_THROTTLEINTERVAL "ThrottleInterval" +#define LAUNCH_JOBKEY_LAUNCHONLYONCE "LaunchOnlyOnce" +#define LAUNCH_JOBKEY_ABANDONPROCESSGROUP "AbandonProcessGroup" +#define LAUNCH_JOBKEY_IGNOREPROCESSGROUPATSHUTDOWN "IgnoreProcessGroupAtShutdown" +#define LAUNCH_JOBKEY_POLICIES "Policies" +#define LAUNCH_JOBKEY_ENABLETRANSACTIONS "EnableTransactions" + +#define LAUNCH_JOBPOLICY_DENYCREATINGOTHERJOBS "DenyCreatingOtherJobs" + +#define LAUNCH_JOBINETDCOMPATIBILITY_WAIT "Wait" + +#define LAUNCH_JOBKEY_MACH_RESETATCLOSE "ResetAtClose" +#define LAUNCH_JOBKEY_MACH_HIDEUNTILCHECKIN "HideUntilCheckIn" +#define LAUNCH_JOBKEY_MACH_DRAINMESSAGESONCRASH "DrainMessagesOnCrash" +#define LAUNCH_JOBKEY_MACH_PINGEVENTUPDATES "PingEventUpdates" + +#define LAUNCH_JOBKEY_KEEPALIVE_SUCCESSFULEXIT "SuccessfulExit" +#define LAUNCH_JOBKEY_KEEPALIVE_NETWORKSTATE "NetworkState" +#define LAUNCH_JOBKEY_KEEPALIVE_PATHSTATE "PathState" +#define LAUNCH_JOBKEY_KEEPALIVE_OTHERJOBACTIVE "OtherJobActive" +#define LAUNCH_JOBKEY_KEEPALIVE_OTHERJOBENABLED "OtherJobEnabled" +#define LAUNCH_JOBKEY_KEEPALIVE_AFTERINITIALDEMAND "AfterInitialDemand" +#define LAUNCH_JOBKEY_KEEPALIVE_CRASHED "Crashed" + +#define LAUNCH_JOBKEY_LAUNCHEVENTS "LaunchEvents" + +#define LAUNCH_JOBKEY_CAL_MINUTE "Minute" +#define LAUNCH_JOBKEY_CAL_HOUR "Hour" +#define LAUNCH_JOBKEY_CAL_DAY "Day" +#define LAUNCH_JOBKEY_CAL_WEEKDAY "Weekday" +#define LAUNCH_JOBKEY_CAL_MONTH "Month" + +#define LAUNCH_JOBKEY_RESOURCELIMIT_CORE "Core" +#define LAUNCH_JOBKEY_RESOURCELIMIT_CPU "CPU" +#define LAUNCH_JOBKEY_RESOURCELIMIT_DATA "Data" +#define LAUNCH_JOBKEY_RESOURCELIMIT_FSIZE "FileSize" +#define LAUNCH_JOBKEY_RESOURCELIMIT_MEMLOCK "MemoryLock" +#define LAUNCH_JOBKEY_RESOURCELIMIT_NOFILE "NumberOfFiles" +#define LAUNCH_JOBKEY_RESOURCELIMIT_NPROC "NumberOfProcesses" +#define LAUNCH_JOBKEY_RESOURCELIMIT_RSS "ResidentSetSize" +#define LAUNCH_JOBKEY_RESOURCELIMIT_STACK "Stack" + +#define LAUNCH_JOBKEY_DISABLED_MACHINETYPE "MachineType" +#define LAUNCH_JOBKEY_DISABLED_MODELNAME "ModelName" + +#define LAUNCH_JOBSOCKETKEY_TYPE "SockType" +#define LAUNCH_JOBSOCKETKEY_PASSIVE "SockPassive" +#define LAUNCH_JOBSOCKETKEY_BONJOUR "Bonjour" +#define LAUNCH_JOBSOCKETKEY_SECUREWITHKEY "SecureSocketWithKey" +#define LAUNCH_JOBSOCKETKEY_PATHNAME "SockPathName" +#define LAUNCH_JOBSOCKETKEY_PATHMODE "SockPathMode" +#define LAUNCH_JOBSOCKETKEY_NODENAME "SockNodeName" +#define LAUNCH_JOBSOCKETKEY_SERVICENAME "SockServiceName" +#define LAUNCH_JOBSOCKETKEY_FAMILY "SockFamily" +#define LAUNCH_JOBSOCKETKEY_PROTOCOL "SockProtocol" +#define LAUNCH_JOBSOCKETKEY_MULTICASTGROUP "MulticastGroup" + +/* These APIs are NOT suitable for general use. Their use should be constrained + * to checking into launchd to obtain socket file descriptors using the + * LAUNCH_CHECK_IN message type. + */ +typedef struct _launch_data *launch_data_t; + +typedef enum { + LAUNCH_DATA_DICTIONARY = 1, + LAUNCH_DATA_ARRAY, + LAUNCH_DATA_FD, + LAUNCH_DATA_INTEGER, + LAUNCH_DATA_REAL, + LAUNCH_DATA_BOOL, + LAUNCH_DATA_STRING, + LAUNCH_DATA_OPAQUE, + LAUNCH_DATA_ERRNO, + LAUNCH_DATA_MACHPORT, +} launch_data_type_t; + +__ld_allocator +launch_data_t +launch_data_alloc(launch_data_type_t); + +__ld_allocator +launch_data_t +launch_data_copy(launch_data_t); + +__ld_getter +launch_data_type_t +launch_data_get_type(const launch_data_t); + +__ld_setter +void +launch_data_free(launch_data_t); + +__ld_setter +bool +launch_data_dict_insert(launch_data_t, const launch_data_t, const char *); + +__ld_getter +launch_data_t +launch_data_dict_lookup(const launch_data_t, const char *); + +__ld_setter +bool +launch_data_dict_remove(launch_data_t, const char *); + +__ld_iterator(1, 2) +void +launch_data_dict_iterate(const launch_data_t, + void (*)(const launch_data_t, const char *, void *), void *); + +__ld_getter +size_t +launch_data_dict_get_count(const launch_data_t); + +__ld_setter +bool +launch_data_array_set_index(launch_data_t, const launch_data_t, size_t); + +__ld_getter +launch_data_t +launch_data_array_get_index(const launch_data_t, size_t); + +__ld_getter +size_t +launch_data_array_get_count(const launch_data_t); + +__ld_allocator +launch_data_t +launch_data_new_fd(int); + +__ld_allocator +launch_data_t +launch_data_new_machport(mach_port_t); + +__ld_allocator +launch_data_t +launch_data_new_integer(long long); + +__ld_allocator +launch_data_t +launch_data_new_bool(bool); + +__ld_allocator +launch_data_t +launch_data_new_real(double); + +__ld_allocator +launch_data_t +launch_data_new_string(const char *); + +__ld_allocator +launch_data_t +launch_data_new_opaque(const void *, size_t); + + __ld_setter +bool +launch_data_set_fd(launch_data_t, int); + + __ld_setter +bool +launch_data_set_machport(launch_data_t, mach_port_t); + + __ld_setter +bool +launch_data_set_integer(launch_data_t, long long); + + __ld_setter +bool +launch_data_set_bool(launch_data_t, bool); + + __ld_setter +bool +launch_data_set_real(launch_data_t, double); + + __ld_setter +bool +launch_data_set_string(launch_data_t, const char *); + + __ld_setter +bool +launch_data_set_opaque(launch_data_t, const void *, size_t); + +__ld_getter +int +launch_data_get_fd(const launch_data_t); + +__ld_getter +mach_port_t +launch_data_get_machport(const launch_data_t); + +__ld_getter +long long +launch_data_get_integer(const launch_data_t); + +__ld_getter +bool +launch_data_get_bool(const launch_data_t); + +__ld_getter +double +launch_data_get_real(const launch_data_t); + +__ld_getter +const char * +launch_data_get_string(const launch_data_t); + +__ld_getter +void * +launch_data_get_opaque(const launch_data_t); + +__ld_getter +size_t +launch_data_get_opaque_size(const launch_data_t); + +__ld_getter +int +launch_data_get_errno(const launch_data_t); + + +/* launch_get_fd() + * + * Use this to get the FD if you're doing asynchronous I/O with select(), + * poll() or kevent(). + */ +__ld_normal +int +launch_get_fd(void); + +/* launch_msg() + * + * Use this API to check in. Nothing else. + */ +__ld_normal +launch_data_t +launch_msg(const launch_data_t); + +__END_DECLS + +#pragma GCC visibility pop + +#endif /* __LAUNCH_H__ */ diff --git a/headers/xpc/XPC.apinotes b/headers/xpc/XPC.apinotes new file mode 100644 index 0000000..8b14f5c --- /dev/null +++ b/headers/xpc/XPC.apinotes @@ -0,0 +1,7 @@ +Name: XPC +Functions: +# xpc_object +- Name: xpc_retain + Availability: nonswift +- Name: xpc_release + Availability: nonswift diff --git a/headers/xpc/activity.h b/headers/xpc/activity.h new file mode 100644 index 0000000..c0928dc --- /dev/null +++ b/headers/xpc/activity.h @@ -0,0 +1,433 @@ +#ifndef __XPC_ACTIVITY_H__ +#define __XPC_ACTIVITY_H__ + +#ifndef __XPC_INDIRECT__ +#error "Please #include instead of this file directly." +// For HeaderDoc. +#include +#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 *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 device appears to be asleep. Note that the definition of screen sleep + * may very 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 *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_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 *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 *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__ + diff --git a/headers/xpc/availability.h b/headers/xpc/availability.h new file mode 100644 index 0000000..7cb9d03 --- /dev/null +++ b/headers/xpc/availability.h @@ -0,0 +1,108 @@ +#ifndef __XPC_AVAILABILITY_H__ +#define __XPC_AVAILABILITY_H__ + +#include + +// Certain parts of the project use all the project's headers but have to build +// against newer OSX SDKs than ebuild uses -- liblaunch_host being the example. +// So we need to define these. +#ifndef __MAC_10_13 +#define __MAC_10_13 101300 +#define __AVAILABILITY_INTERNAL__MAC_10_13 \ + __attribute__((availability(macosx, introduced=10.13))) +#endif // __MAC_10_13 + +#ifndef __MAC_10_12 +#define __MAC_10_12 101200 +#define __AVAILABILITY_INTERNAL__MAC_10_12 \ + __attribute__((availability(macosx, introduced=10.12))) +#endif // __MAC_10_12 + +#ifndef __MAC_10_11 +#define __MAC_10_11 101100 +#define __AVAILABILITY_INTERNAL__MAC_10_11 \ + __attribute__((availability(macosx, introduced=10.11))) +#endif // __MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_2_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_2_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_2_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_3_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_3_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_3_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_4_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_4_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_4_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_5_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_5_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_5_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_7_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_7_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_7_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_8_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_8_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_8_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_9_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_9_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_9_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_10_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_10_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_10_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_11_DEP__MAC_10_11 +#define __AVAILABILITY_INTERNAL__MAC_10_11_DEP__MAC_10_11 +#endif // __AVAILABILITY_INTERNAL__MAC_10_11_DEP__MAC_10_11 + +#ifndef __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_13 +#define __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_13 +#endif // __AVAILABILITY_INTERNAL__MAC_10_6_DEP__MAC_10_13 + +#if __has_include() +#include +#else // __has_include() +#ifndef IPHONE_SIMULATOR_HOST_MIN_VERSION_REQUIRED +#define IPHONE_SIMULATOR_HOST_MIN_VERSION_REQUIRED 999999 +#endif // IPHONE_SIMULATOR_HOST_MIN_VERSION_REQUIRED +#endif // __has_include() + +#ifndef __WATCHOS_UNAVAILABLE +#define __WATCHOS_UNAVAILABLE +#endif + +#ifndef __TVOS_UNAVAILABLE +#define __TVOS_UNAVAILABLE +#endif + +// simulator host-side bits build against SDKs not having __*_AVAILABLE() yet +#ifndef __OSX_AVAILABLE +#define __OSX_AVAILABLE(...) +#endif + +#ifndef __IOS_AVAILABLE +#define __IOS_AVAILABLE(...) +#endif + +#ifndef __TVOS_AVAILABLE +#define __TVOS_AVAILABLE(...) +#endif + +#ifndef __WATCHOS_AVAILABLE +#define __WATCHOS_AVAILABLE(...) +#endif + +#ifndef __API_AVAILABLE +#define __API_AVAILABLE(...) +#endif + +#endif // __XPC_AVAILABILITY_H__ diff --git a/headers/xpc/base.h b/headers/xpc/base.h new file mode 100644 index 0000000..44d97f5 --- /dev/null +++ b/headers/xpc/base.h @@ -0,0 +1,200 @@ +// Copyright (c) 2009-2011 Apple Inc. All rights reserved. + +#ifndef __XPC_BASE_H__ +#define __XPC_BASE_H__ + +#include + +__BEGIN_DECLS + +#if !defined(__has_include) +#define __has_include(x) 0 +#endif // !defined(__has_include) + +#if !defined(__has_attribute) +#define __has_attribute(x) 0 +#endif // !defined(__has_attribute) + +#if !defined(__has_feature) +#define __has_feature(x) 0 +#endif // !defined(__has_feature) + +#if !defined(__has_extension) +#define __has_extension(x) 0 +#endif // !defined(__has_extension) + +#if __has_include() +#include +#else // __has_include() +#include +#endif // __has_include() + +#if XPC_SERVICE_MAIN_IN_LIBXPC +#define XPC_HOSTING_OLD_MAIN 1 +#else // XPC_SERVICE_MAIN_IN_LIBXPC +#define XPC_HOSTING_OLD_MAIN 0 +#endif // XPC_SERVICE_MAIN_IN_LIBXPC + +#ifndef __XPC_INDIRECT__ +#error "Please #include instead of this file directly." +#endif // __XPC_INDIRECT__ + +#pragma mark Attribute Shims +#ifdef __GNUC__ +#define XPC_CONSTRUCTOR __attribute__((constructor)) +#define XPC_NORETURN __attribute__((__noreturn__)) +#define XPC_NOTHROW __attribute__((__nothrow__)) +#define XPC_NONNULL1 __attribute__((__nonnull__(1))) +#define XPC_NONNULL2 __attribute__((__nonnull__(2))) +#define XPC_NONNULL3 __attribute__((__nonnull__(3))) +#define XPC_NONNULL4 __attribute__((__nonnull__(4))) +#define XPC_NONNULL5 __attribute__((__nonnull__(5))) +#define XPC_NONNULL6 __attribute__((__nonnull__(6))) +#define XPC_NONNULL7 __attribute__((__nonnull__(7))) +#define XPC_NONNULL8 __attribute__((__nonnull__(8))) +#define XPC_NONNULL9 __attribute__((__nonnull__(9))) +#define XPC_NONNULL10 __attribute__((__nonnull__(10))) +#define XPC_NONNULL11 __attribute__((__nonnull__(11))) +#define XPC_NONNULL_ALL __attribute__((__nonnull__)) +#define XPC_SENTINEL __attribute__((__sentinel__)) +#define XPC_PURE __attribute__((__pure__)) +#define XPC_WARN_RESULT __attribute__((__warn_unused_result__)) +#define XPC_MALLOC __attribute__((__malloc__)) +#define XPC_UNUSED __attribute__((__unused__)) +#define XPC_USED __attribute__((__used__)) +#define XPC_PACKED __attribute__((__packed__)) +#define XPC_PRINTF(m, n) __attribute__((format(printf, m, n))) +#define XPC_INLINE static __inline__ __attribute__((__always_inline__)) +#define XPC_NOINLINE __attribute__((noinline)) +#define XPC_NOIMPL __attribute__((unavailable)) + +#if __has_attribute(noescape) +#define XPC_NOESCAPE __attribute__((__noescape__)) +#else +#define XPC_NOESCAPE +#endif + +#if __has_extension(attribute_unavailable_with_message) +#define XPC_UNAVAILABLE(m) __attribute__((unavailable(m))) +#else // __has_extension(attribute_unavailable_with_message) +#define XPC_UNAVAILABLE(m) XPC_NOIMPL +#endif // __has_extension(attribute_unavailable_with_message) + +#define XPC_EXPORT extern __attribute__((visibility("default"))) +#define XPC_NOEXPORT __attribute__((visibility("hidden"))) +#define XPC_WEAKIMPORT extern __attribute__((weak_import)) +#define XPC_DEBUGGER_EXCL XPC_NOEXPORT XPC_USED +#define XPC_TRANSPARENT_UNION __attribute__((transparent_union)) +#if __clang__ +#define XPC_DEPRECATED(m) __attribute__((deprecated(m))) +#else // __clang__ +#define XPC_DEPRECATED(m) __attribute__((deprecated)) +#endif // __clang + +#if __XPC_TEST__ +#define XPC_TESTSTATIC +#else // __XPC_TEST__ +#define XPC_TESTSTATIC static +#endif // __XPC_TEST__ + +#if __has_feature(objc_arc) +#define XPC_GIVES_REFERENCE __strong +#define XPC_UNRETAINED __unsafe_unretained +#define XPC_BRIDGE(xo) ((__bridge void *)(xo)) +#define XPC_BRIDGEREF_BEGIN(xo) ((__bridge_retained void *)(xo)) +#define XPC_BRIDGEREF_BEGIN_WITH_REF(xo) ((__bridge void *)(xo)) +#define XPC_BRIDGEREF_MIDDLE(xo) ((__bridge id)(xo)) +#define XPC_BRIDGEREF_END(xo) ((__bridge_transfer id)(xo)) +#else // __has_feature(objc_arc) +#define XPC_GIVES_REFERENCE +#define XPC_UNRETAINED +#define XPC_BRIDGE(xo) (xo) +#define XPC_BRIDGEREF_BEGIN(xo) (xo) +#define XPC_BRIDGEREF_BEGIN_WITH_REF(xo) (xo) +#define XPC_BRIDGEREF_MIDDLE(xo) (xo) +#define XPC_BRIDGEREF_END(xo) (xo) +#endif // __has_feature(objc_arc) + +#define _xpc_unreachable() __builtin_unreachable() +#else // __GNUC__ +/*! @parseOnly */ +#define XPC_CONSTRUCTOR +/*! @parseOnly */ +#define XPC_NORETURN +/*! @parseOnly */ +#define XPC_NOTHROW +/*! @parseOnly */ +#define XPC_NONNULL1 +/*! @parseOnly */ +#define XPC_NONNULL2 +/*! @parseOnly */ +#define XPC_NONNULL3 +/*! @parseOnly */ +#define XPC_NONNULL4 +/*! @parseOnly */ +#define XPC_NONNULL5 +/*! @parseOnly */ +#define XPC_NONNULL6 +/*! @parseOnly */ +#define XPC_NONNULL7 +/*! @parseOnly */ +#define XPC_NONNULL8 +/*! @parseOnly */ +#define XPC_NONNULL9 +/*! @parseOnly */ +#define XPC_NONNULL10 +/*! @parseOnly */ +#define XPC_NONNULL11 +/*! @parseOnly */ +#define XPC_NONNULL(n) +/*! @parseOnly */ +#define XPC_NONNULL_ALL +/*! @parseOnly */ +#define XPC_SENTINEL +/*! @parseOnly */ +#define XPC_PURE +/*! @parseOnly */ +#define XPC_WARN_RESULT +/*! @parseOnly */ +#define XPC_MALLOC +/*! @parseOnly */ +#define XPC_UNUSED +/*! @parseOnly */ +#define XPC_PACKED +/*! @parseOnly */ +#define XPC_PRINTF(m, n) +/*! @parseOnly */ +#define XPC_INLINE static inline +/*! @parseOnly */ +#define XPC_NOINLINE +/*! @parseOnly */ +#define XPC_NOIMPL +/*! @parseOnly */ +#define XPC_EXPORT extern +/*! @parseOnly */ +#define XPC_WEAKIMPORT +/*! @parseOnly */ +#define XPC_DEPRECATED +/*! @parseOnly */ +#define XPC_UNAVAILABLE(m) +/*! @parseOnly */ +#define XPC_NOESCAPE +#endif // __GNUC__ + +#if __has_feature(assume_nonnull) +#define XPC_ASSUME_NONNULL_BEGIN _Pragma("clang assume_nonnull begin") +#define XPC_ASSUME_NONNULL_END _Pragma("clang assume_nonnull end") +#else +#define XPC_ASSUME_NONNULL_BEGIN +#define XPC_ASSUME_NONNULL_END +#endif + +#if __has_feature(nullability_on_arrays) +#define XPC_NONNULL_ARRAY _Nonnull +#else +#define XPC_NONNULL_ARRAY +#endif + +__END_DECLS + +#endif // __XPC_BASE_H__ diff --git a/headers/xpc/connection.h b/headers/xpc/connection.h new file mode 100644 index 0000000..d319c72 --- /dev/null +++ b/headers/xpc/connection.h @@ -0,0 +1,747 @@ +#ifndef __XPC_CONNECTION_H__ +#define __XPC_CONNECTION_H__ + +#ifndef __XPC_INDIRECT__ +#error "Please #include instead of this file directly." +// For HeaderDoc. +#include +#endif // __XPC_INDIRECT__ + +#ifndef __BLOCKS__ +#error "XPC connections require Blocks support." +#endif // __BLOCKS__ + +XPC_ASSUME_NONNULL_BEGIN +__BEGIN_DECLS + +/*! + * @constant XPC_ERROR_CONNECTION_INTERRUPTED + * Will be delivered to the connection's event handler if the remote service + * exited. The connection is still live even in this case, and resending a + * message will cause the service to be launched on-demand. This error serves + * as a client's indication that it should resynchronize any state that it had + * given the service. + * + * Any messages in the queue to be sent will be unwound and canceled when this + * error occurs. In the case where a message waiting to be sent has a reply + * handler, that handler will be invoked with this error. In the context of the + * reply handler, this error indicates that a reply to the message will never + * arrive. + * + * Messages that do not have reply handlers associated with them will be + * silently disposed of. This error will only be given to peer connections. + */ +#define XPC_ERROR_CONNECTION_INTERRUPTED \ + XPC_GLOBAL_OBJECT(_xpc_error_connection_interrupted) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +const struct _xpc_dictionary_s _xpc_error_connection_interrupted; + +/*! + * @constant XPC_ERROR_CONNECTION_INVALID + * Will be delivered to the connection's event handler if the named service + * provided to xpc_connection_create() could not be found in the XPC service + * namespace. The connection is useless and should be disposed of. + * + * Any messages in the queue to be sent will be unwound and canceled when this + * error occurs, similarly to the behavior when XPC_ERROR_CONNECTION_INTERRUPTED + * occurs. The only difference is that the XPC_ERROR_CONNECTION_INVALID will be + * given to outstanding reply handlers and the connection's event handler. + * + * This error may be given to any type of connection. + */ +#define XPC_ERROR_CONNECTION_INVALID \ + XPC_GLOBAL_OBJECT(_xpc_error_connection_invalid) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +const struct _xpc_dictionary_s _xpc_error_connection_invalid; + +/*! + * @constant XPC_ERROR_TERMINATION_IMMINENT + * On macOS, this error will be delivered to a peer connection's event handler + * when the XPC runtime has determined that the program should exit and that + * all outstanding transactions must be wound down, and no new transactions can + * be opened. + * + * After this error has been delivered to the event handler, no more messages + * will be received by the connection. The runtime will still attempt to deliver + * outgoing messages, but this error should be treated as an indication that + * the program will exit very soon, and any outstanding business over the + * connection should be wrapped up as quickly as possible and the connection + * canceled shortly thereafter. + * + * This error will only be delivered to peer connections received through a + * listener or the xpc_main() event handler. + */ +#define XPC_ERROR_TERMINATION_IMMINENT \ + XPC_GLOBAL_OBJECT(_xpc_error_termination_imminent) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +const struct _xpc_dictionary_s _xpc_error_termination_imminent; + +/*! + * @constant XPC_CONNECTION_MACH_SERVICE_LISTENER + * Passed to xpc_connection_create_mach_service(). This flag indicates that the + * caller is the listener for the named service. This flag may only be passed + * for services which are advertised in the process' launchd.plist(5). You may + * not use this flag to dynamically add services to the Mach bootstrap + * namespace. + */ +#define XPC_CONNECTION_MACH_SERVICE_LISTENER (1 << 0) + +/*! + * @constant XPC_CONNECTION_MACH_SERVICE_PRIVILEGED + * Passed to xpc_connection_create_mach_service(). This flag indicates that the + * job advertising the service name in its launchd.plist(5) should be in the + * privileged Mach bootstrap. This is typically accomplished by placing your + * launchd.plist(5) in /Library/LaunchDaemons. If specified alongside the + * XPC_CONNECTION_MACH_SERVICE_LISTENER flag, this flag is a no-op. + */ +#define XPC_CONNECTION_MACH_SERVICE_PRIVILEGED (1 << 1) + +/*! + * @typedef xpc_finalizer_f + * A function that is invoked when a connection is being torn down and its + * context needs to be freed. The sole argument is the value that was given to + * {@link xpc_connection_set_context} or NULL if no context has been set. It is + * not safe to reference the connection from within this function. + * + * @param value + * The context object that is to be disposed of. + */ +typedef void (*xpc_finalizer_t)(void * _Nullable value); + +/*! + * @function xpc_connection_create + * Creates a new connection object. + * + * @param name + * If non-NULL, the name of the service with which to connect. The returned + * connection will be a peer. + * + * If NULL, an anonymous listener connection will be created. You can embed the + * ability to create new peer connections in an endpoint, which can be inserted + * into a message and sent to another process . + * + * @param targetq + * The GCD queue to which the event handler block will be submitted. This + * parameter may be NULL, in which case the connection's target queue will be + * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. + * The target queue may be changed later with a call to + * xpc_connection_set_target_queue(). + * + * @result + * A new connection object. The caller is responsible for disposing of the + * returned object with {@link xpc_release} when it is no longer needed. + * + * @discussion + * This method will succeed even if the named service does not exist. This is + * because the XPC namespace is not queried for the service name until the + * connection has been activated. See {@link xpc_connection_activate()}. + * + * XPC connections, like dispatch sources, are returned in an inactive state, so + * you must call {@link xpc_connection_activate()} in order to begin receiving + * events from the connection. Also like dispatch sources, connections must be + * activated and not suspended in order to be safely released. It is + * a programming error to release an inactive or suspended connection. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_connection_t +xpc_connection_create(const char * _Nullable name, + dispatch_queue_t _Nullable targetq); + +/*! + * @function xpc_connection_create_mach_service + * Creates a new connection object representing a Mach service. + * + * @param name + * The name of the remote service with which to connect. The service name must + * exist in a Mach bootstrap that is accessible to the process and be advertised + * in a launchd.plist. + * + * @param targetq + * The GCD queue to which the event handler block will be submitted. This + * parameter may be NULL, in which case the connection's target queue will be + * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. + * The target queue may be changed later with a call to + * xpc_connection_set_target_queue(). + * + * @param flags + * Additional attributes with which to create the connection. + * + * @result + * A new connection object. + * + * @discussion + * If the XPC_CONNECTION_MACH_SERVICE_LISTENER flag is given to this method, + * then the connection returned will be a listener connection. Otherwise, a peer + * connection will be returned. See the documentation for + * {@link xpc_connection_set_event_handler()} for the semantics of listener + * connections versus peer connections. + * + * This method will succeed even if the named service does not exist. This is + * because the Mach namespace is not queried for the service name until the + * connection has been activated. See {@link xpc_connection_activate()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +xpc_connection_t +xpc_connection_create_mach_service(const char *name, + dispatch_queue_t _Nullable targetq, uint64_t flags); + +/*! + * @function xpc_connection_create_from_endpoint + * Creates a new connection from the given endpoint. + * + * @param endpoint + * The endpoint from which to create the new connection. + * + * @result + * A new peer connection to the listener represented by the given endpoint. + * + * The same responsibilities of setting an event handler and activating the + * connection after calling xpc_connection_create() apply to the connection + * returned by this API. Since the connection yielded by this API is not + * associated with a name (and therefore is not rediscoverable), this connection + * will receive XPC_ERROR_CONNECTION_INVALID if the listening side crashes, + * exits or cancels the listener connection. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_connection_t +xpc_connection_create_from_endpoint(xpc_endpoint_t endpoint); + +/*! + * @function xpc_connection_set_target_queue + * Sets the target queue of the given connection. + * + * @param connection + * The connection object which is to be manipulated. + * + * @param targetq + * The GCD queue to which the event handler block will be submitted. This + * parameter may be NULL, in which case the connection's target queue will be + * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. + * + * @discussion + * Setting the target queue is asynchronous and non-preemptive and therefore + * this method will not interrupt the execution of an already-running event + * handler block. Setting the target queue may be likened to issuing a barrier + * to the connection which does the actual work of changing the target queue. + * + * The XPC runtime guarantees this non-preemptiveness even for concurrent target + * queues. If the target queue is a concurrent queue, then XPC still guarantees + * that there will never be more than one invocation of the connection's event + * handler block executing concurrently. If you wish to process events + * concurrently, you can dispatch_async(3) to a concurrent queue from within + * the event handler. + * + * IMPORTANT: When called from within the event handler block, + * dispatch_get_current_queue(3) is NOT guaranteed to return a pointer to the + * queue set with this method. + * + * Despite this seeming inconsistency, the XPC runtime guarantees that, when the + * target queue is a serial queue, the event handler block will execute + * synchonously with respect to other blocks submitted to that same queue. When + * the target queue is a concurrent queue, the event handler block may run + * concurrently with other blocks submitted to that queue, but it will never run + * concurrently with other invocations of itself for the same connection, as + * discussed previously. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_connection_set_target_queue(xpc_connection_t connection, + dispatch_queue_t _Nullable targetq); + +/*! + * @function xpc_connection_set_event_handler + * Sets the event handler block for the connection. + * + * @param connection + * The connection object which is to be manipulated. + * + * @param handler + * The event handler block. + * + * @discussion + * Setting the event handler is asynchronous and non-preemptive, and therefore + * this method will not interrupt the execution of an already-running event + * handler block. If the event handler is executing at the time of this call, it + * will finish, and then the connection's event handler will be changed before + * the next invocation of the event handler. The XPC runtime guarantees this + * non-preemptiveness even for concurrent target queues. + * + * Connection event handlers are non-reentrant, so it is safe to call + * xpc_connection_set_event_handler() from within the event handler block. + * + * The event handler's execution should be treated as a barrier to all + * connection activity. When it is executing, the connection will not attempt to + * send or receive messages, including reply messages. Thus, it is not safe to + * call xpc_connection_send_message_with_reply_sync() on the connection from + * within the event handler. + * + * You do not hold a reference on the object received as the event handler's + * only argument. Regardless of the type of object received, it is safe to call + * xpc_retain() on the object to obtain a reference to it. + * + * A connection may receive different events depending upon whether it is a + * listener or not. Any connection may receive an error in its event handler. + * But while normal connections may receive messages in addition to errors, + * listener connections will receive connections and and not messages. + * + * Connections received by listeners are equivalent to those returned by + * xpc_connection_create() with a non-NULL name argument and a NULL targetq + * argument with the exception that you do not hold a reference on them. + * You must set an event handler and activate the connection. If you do not wish + * to accept the connection, you may simply call xpc_connection_cancel() on it + * and return. The runtime will dispose of it for you. + * + * If there is an error in the connection, this handler will be invoked with the + * error dictionary as its argument. This dictionary will be one of the well- + * known XPC_ERROR_* dictionaries. + * + * Regardless of the type of event, ownership of the event object is NOT + * implicitly transferred. Thus, the object will be released and deallocated at + * some point in the future after the event handler returns. If you wish the + * event's lifetime to persist, you must retain it with xpc_retain(). + * + * Connections received through the event handler will be released and + * deallocated after the connection has gone invalid and delivered that event to + * its event handler. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +void +xpc_connection_set_event_handler(xpc_connection_t connection, + xpc_handler_t handler); + +/*! + * @function xpc_connection_activate + * Activates the connection. Connections start in an inactive state, so you must + * call xpc_connection_activate() on a connection before it will send or receive + * any messages. + * + * @param connection + * The connection object which is to be manipulated. + * + * @discussion + * Calling xpc_connection_activate() on an active connection has no effect. + * Releasing the last reference on an inactive connection that was created with + * an xpc_connection_create*() call is undefined. + * + * For backward compatibility reasons, xpc_connection_resume() on an inactive + * and not otherwise suspended xpc connection has the same effect as calling + * xpc_connection_activate(). For new code, using xpc_connection_activate() + * is preferred. + */ +__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) +__TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0) +XPC_EXPORT XPC_NONNULL_ALL +void +xpc_connection_activate(xpc_connection_t connection); + +/*! + * @function xpc_connection_suspend + * Suspends the connection so that the event handler block will not fire and + * that the connection will not attempt to send any messages it has in its + * queue. All calls to xpc_connection_suspend() must be balanced with calls to + * xpc_connection_resume() before releasing the last reference to the + * connection. + * + * @param connection + * The connection object which is to be manipulated. + * + * @discussion + * Suspension is asynchronous and non-preemptive, and therefore this method will + * not interrupt the execution of an already-running event handler block. If + * the event handler is executing at the time of this call, it will finish, and + * then the connection will be suspended before the next scheduled invocation + * of the event handler. The XPC runtime guarantees this non-preemptiveness even + * for concurrent target queues. + * + * Connection event handlers are non-reentrant, so it is safe to call + * xpc_connection_suspend() from within the event handler block. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +void +xpc_connection_suspend(xpc_connection_t connection); + +/*! + * @function xpc_connection_resume + * Resumes the connection. + * + * @param connection + * The connection object which is to be manipulated. + * + * @discussion + * In order for a connection to become live, every call to + * xpc_connection_suspend() must be balanced with a call to + * xpc_connection_resume(). + * + * For backward compatibility reasons, xpc_connection_resume() on an inactive + * and not otherwise suspended xpc connection has the same effect as calling + * xpc_connection_activate(). For new code, using xpc_connection_activate() + * is preferred. + * + * Calling xpc_connection_resume() more times than xpc_connection_suspend() + * has been called is otherwise considered an error. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +void +xpc_connection_resume(xpc_connection_t connection); + +/*! + * @function xpc_connection_send_message + * Sends a message over the connection to the destination service. + * + * @param connection + * The connection over which the message shall be sent. + * + * @param message + * The message to send. This must be a dictionary object. This dictionary is + * logically copied by the connection, so it is safe to modify the dictionary + * after this call. + * + * @discussion + * Messages are delivered in FIFO order. This API is safe to call from multiple + * GCD queues. There is no indication that a message was delivered successfully. + * This is because even once the message has been successfully enqueued on the + * remote end, there are no guarantees about when the runtime will dequeue the + * message and invoke the other connection's event handler block. + * + * If this API is used to send a message that is in reply to another message, + * there is no guarantee of ordering between the invocations of the connection's + * event handler and the reply handler for that message, even if they are + * targeted to the same queue. + * + * After extensive study, we have found that clients who are interested in + * the state of the message on the server end are typically holding open + * transactions related to that message. And the only reliable way to track the + * lifetime of that transaction is at the protocol layer. So the server should + * send a reply message, which upon receiving, will cause the client to close + * its transaction. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +void +xpc_connection_send_message(xpc_connection_t connection, xpc_object_t message); + +/*! + * @function xpc_connection_send_barrier + * Issues a barrier against the connection's message-send activity. + * + * @param connection + * The connection against which the barrier is to be issued. + * + * @param barrier + * The barrier block to issue. This barrier prevents concurrent message-send + * activity on the connection. No messages will be sent while the barrier block + * is executing. + * + * @discussion + * XPC guarantees that, even if the connection's target queue is a concurrent + * queue, there are no other messages being sent concurrently while the barrier + * block is executing. XPC does not guarantee that the reciept of messages + * (either through the connection's event handler or through reply handlers) + * will be suspended while the barrier is executing. + * + * A barrier is issued relative to the message-send queue. Thus, if you call + * xpc_connection_send_message() five times and then call + * xpc_connection_send_barrier(), the barrier will be invoked after the fifth + * message has been sent and its memory disposed of. You may safely cancel a + * connection from within a barrier block. + * + * If a barrier is issued after sending a message which expects a reply, the + * behavior is the same as described above. The receipt of a reply message will + * not influence when the barrier runs. + * + * A barrier block can be useful for throttling resource consumption on the + * connected side of a connection. For example, if your connection sends many + * large messages, you can use a barrier to limit the number of messages that + * are inflight at any given time. This can be particularly useful for messages + * that contain kernel resources (like file descriptors) which have a system- + * wide limit. + * + * If a barrier is issued on a canceled connection, it will be invoked + * immediately. If a connection has been canceled and still has outstanding + * barriers, those barriers will be invoked as part of the connection's + * unwinding process. + * + * It is important to note that a barrier block's execution order is not + * guaranteed with respect to other blocks that have been scheduled on the + * target queue of the connection. Or said differently, + * xpc_connection_send_barrier(3) is not equivalent to dispatch_async(3). + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +void +xpc_connection_send_barrier(xpc_connection_t connection, + dispatch_block_t barrier); + +/*! + * @function xpc_connection_send_message_with_reply + * Sends a message over the connection to the destination service and associates + * a handler to be invoked when the remote service sends a reply message. + * + * @param connection + * The connection over which the message shall be sent. + * + * @param message + * The message to send. This must be a dictionary object. + * + * @param replyq + * The GCD queue to which the reply handler will be submitted. This may be a + * concurrent queue. + * + * @param handler + * The handler block to invoke when a reply to the message is received from + * the connection. If the remote service exits prematurely before the reply was + * received, the XPC_ERROR_CONNECTION_INTERRUPTED error will be returned. + * If the connection went invalid before the message could be sent, the + * XPC_ERROR_CONNECTION_INVALID error will be returned. + * + * @discussion + * If the given GCD queue is a concurrent queue, XPC cannot guarantee that there + * will not be multiple reply handlers being invoked concurrently. XPC does not + * guarantee any ordering for the invocation of reply handers. So if multiple + * messages are waiting for replies and the connection goes invalid, there is no + * guarantee that the reply handlers will be invoked in FIFO order. Similarly, + * XPC does not guarantee that reply handlers will not run concurrently with + * the connection's event handler in the case that the reply queue and the + * connection's target queue are the same concurrent queue. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL4 +void +xpc_connection_send_message_with_reply(xpc_connection_t connection, + xpc_object_t message, dispatch_queue_t _Nullable replyq, + xpc_handler_t handler); + +/*! + * @function xpc_connection_send_message_with_reply_sync + * Sends a message over the connection and blocks the caller until a reply is + * received. + * + * @param connection + * The connection over which the message shall be sent. + * + * @param message + * The message to send. This must be a dictionary object. + * + * @result + * The message that the remote service sent in reply to the original message. + * If the remote service exits prematurely before the reply was received, the + * XPC_ERROR_CONNECTION_INTERRUPTED error will be returned. If the connection + * went invalid before the message could be sent, the + * XPC_ERROR_CONNECTION_INVALID error will be returned. + * + * You are responsible for releasing the returned object. + * + * @discussion + * This API is primarily for transitional purposes. Its implementation is + * conceptually equivalent to calling xpc_connection_send_message_with_reply() + * and then immediately blocking the calling thread on a semaphore and + * signaling the semaphore from the reply block. + * + * Be judicious about your use of this API. It can block indefinitely, so if you + * are using it to implement an API that can be called from the main thread, you + * may wish to consider allowing the API to take a queue and callback block so + * that results may be delivered asynchronously if possible. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT XPC_RETURNS_RETAINED +xpc_object_t +xpc_connection_send_message_with_reply_sync(xpc_connection_t connection, + xpc_object_t message); + +/*! + * @function xpc_connection_cancel + * Cancels the connection and ensures that its event handler will not fire + * again. After this call, any messages that have not yet been sent will be + * discarded, and the connection will be unwound. If there are messages that are + * awaiting replies, they will have their reply handlers invoked with the + * XPC_ERROR_CONNECTION_INVALID error. + * + * @param connection + * The connection object which is to be manipulated. + * + * @discussion + * Cancellation is asynchronous and non-preemptive and therefore this method + * will not interrupt the execution of an already-running event handler block. + * If the event handler is executing at the time of this call, it will finish, + * and then the connection will be canceled, causing a final invocation of the + * event handler to be scheduled with the XPC_ERROR_CONNECTION_INVALID error. + * After that invocation, there will be no further invocations of the event + * handler. + * + * The XPC runtime guarantees this non-preemptiveness even for concurrent target + * queues. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +void +xpc_connection_cancel(xpc_connection_t connection); + +/*! + * @function xpc_connection_get_name + * Returns the name of the service with which the connections was created. + * + * @param connection + * The connection object which is to be examined. + * + * @result + * The name of the remote service. If you obtained the connection through an + * invocation of another connection's event handler, NULL is returned. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT +const char * _Nullable +xpc_connection_get_name(xpc_connection_t connection); + +/*! + * @function xpc_connection_get_euid + * Returns the EUID of the remote peer. + * + * @param connection + * The connection object which is to be examined. + * + * @result + * The EUID of the remote peer at the time the connection was made. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT +uid_t +xpc_connection_get_euid(xpc_connection_t connection); + +/*! + * @function xpc_connection_get_egid + * Returns the EGID of the remote peer. + * + * @param connection + * The connection object which is to be examined. + * + * @result + * The EGID of the remote peer at the time the connection was made. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT +gid_t +xpc_connection_get_egid(xpc_connection_t connection); + +/*! + * @function xpc_connection_get_pid + * Returns the PID of the remote peer. + * + * @param connection + * The connection object which is to be examined. + * + * @result + * The PID of the remote peer. + * + * @discussion + * A given PID is not guaranteed to be unique across an entire boot cycle. + * Great care should be taken when dealing with this information, as it can go + * stale after the connection is established. OS X recycles PIDs, and therefore + * another process could spawn and claim the PID before a message is actually + * received from the connection. + * + * XPC will deliver an error to your event handler if the remote process goes + * away, but there are no guarantees as to the timing of this notification's + * delivery either at the kernel layer or at the XPC layer. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT +pid_t +xpc_connection_get_pid(xpc_connection_t connection); + +/*! + * @function xpc_connection_get_asid + * Returns the audit session identifier of the remote peer. + * + * @param connection + * The connection object which is to be examined. + * + * @result + * The audit session ID of the remote peer at the time the connection was made. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT +au_asid_t +xpc_connection_get_asid(xpc_connection_t connection); + +/*! + * @function xpc_connection_set_context + * Sets context on an connection. + * + * @param connection + * The connection which is to be manipulated. + * + * @param context + * The context to associate with the connection. + * + * @discussion + * If you must manage the memory of the context object, you must set a finalizer + * to dispose of it. If this method is called on a connection which already has + * context associated with it, the finalizer will NOT be invoked. The finalizer + * is only invoked when the connection is being deallocated. + * + * It is recommended that, instead of changing the actual context pointer + * associated with the object, you instead change the state of the context + * object itself. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_connection_set_context(xpc_connection_t connection, + void * _Nullable context); + +/*! + * @function xpc_connection_get_context + * Returns the context associated with the connection. + * + * @param connection + * The connection which is to be examined. + * + * @result + * The context associated with the connection. NULL if there has been no context + * associated with the object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT +void * _Nullable +xpc_connection_get_context(xpc_connection_t connection); + +/*! + * @function xpc_connection_set_finalizer_f + * Sets the finalizer for the given connection. + * + * @param connection + * The connection on which to set the finalizer. + * + * @param finalizer + * The function that will be invoked when the connection's retain count has + * dropped to zero and is being torn down. + * + * @discussion + * This method disposes of the context value associated with a connection, as + * set by {@link xpc_connection_set_context}. + * + * For many uses of context objects, this API allows for a convenient shorthand + * for freeing them. For example, for a context object allocated with malloc(3): + * + * xpc_connection_set_finalizer_f(object, free); + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_connection_set_finalizer_f(xpc_connection_t connection, + xpc_finalizer_t _Nullable finalizer); + +__END_DECLS +XPC_ASSUME_NONNULL_END + +#endif // __XPC_CONNECTION_H__ diff --git a/headers/xpc/debug.h b/headers/xpc/debug.h new file mode 100644 index 0000000..b50361c --- /dev/null +++ b/headers/xpc/debug.h @@ -0,0 +1,23 @@ +#ifndef __XPC_DEBUG_H__ +#define __XPC_DEBUG_H__ + +/*! + * @function xpc_debugger_api_misuse_info + * Returns a pointer to a string describing the reason XPC aborted the calling + * process. On OS X, this will be the same string present in the "Application + * Specific Information" section of the crash report. + * + * @result + * A pointer to the human-readable string describing the reason the caller was + * aborted. If XPC was not responsible for the program's termination, NULL will + * be returned. + * + * @discussion + * This function is only callable from within a debugger. It is not meant to be + * called by the program directly. + */ +XPC_DEBUGGER_EXCL +const char * +xpc_debugger_api_misuse_info(void); + +#endif // __XPC_DEBUG_H__ diff --git a/headers/xpc/endpoint.h b/headers/xpc/endpoint.h new file mode 100644 index 0000000..aa43449 --- /dev/null +++ b/headers/xpc/endpoint.h @@ -0,0 +1,22 @@ +#ifndef __XPC_ENDPOINT_H__ +#define __XPC_ENDPOINT_H__ + +/*! + * @function xpc_endpoint_create + * Creates a new endpoint from a connection that is suitable for embedding into + * messages. + * + * @param connection + * Only connections obtained through calls to xpc_connection_create*() may be + * given to this API. Passing any other type of connection is not supported and + * will result in undefined behavior. + * + * @result + * A new endpoint object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +xpc_endpoint_t _Nonnull +xpc_endpoint_create(xpc_connection_t _Nonnull connection); + +#endif // __XPC_ENDPOINT_H__ diff --git a/headers/xpc/module.modulemap b/headers/xpc/module.modulemap new file mode 100644 index 0000000..5328f1f --- /dev/null +++ b/headers/xpc/module.modulemap @@ -0,0 +1,10 @@ +module XPC [system] [extern_c] { + header "xpc.h" + header "availability.h" + header "base.h" + header "activity.h" + header "connection.h" + header "debug.h" + header "endpoint.h" + export * +} diff --git a/headers/xpc/xpc.h b/headers/xpc/xpc.h new file mode 100644 index 0000000..df2ca8a --- /dev/null +++ b/headers/xpc/xpc.h @@ -0,0 +1,2647 @@ +// Copyright (c) 2009-2011 Apple Inc. All rights reserved. + +#ifndef __XPC_H__ +#define __XPC_H__ + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#ifndef __XPC_INDIRECT__ +#define __XPC_INDIRECT__ +#endif // __XPC_INDIRECT__ + +#include + +XPC_ASSUME_NONNULL_BEGIN +__BEGIN_DECLS + +#ifndef __OSX_AVAILABLE_STARTING +#define __OSX_AVAILABLE_STARTING(x, y) +#endif // __OSX_AVAILABLE_STARTING + +#define XPC_API_VERSION 20121012 + +/*! + * @typedef xpc_type_t + * A type that describes XPC object types. + */ +typedef const struct _xpc_type_s * xpc_type_t; +#ifndef __XPC_BUILDING_XPC__ +#define XPC_TYPE(type) const struct _xpc_type_s type +#endif // __XPC_BUILDING_XPC__ + +/*! + * @typedef xpc_object_t + * A type that can describe all XPC objects. Dictionaries, arrays, strings, etc. + * are all described by this type. + * + * XPC objects are created with a retain count of 1, and therefore it is the + * caller's responsibility to call xpc_release() on them when they are no longer + * needed. + */ + +#if OS_OBJECT_USE_OBJC +/* By default, XPC objects are declared as Objective-C types when building with + * an Objective-C compiler. This allows them to participate in ARC, in RR + * management by the Blocks runtime and in leaks checking by the static + * analyzer, and enables them to be added to Cocoa collections. + * + * See for details. + */ +OS_OBJECT_DECL(xpc_object); +#ifndef __XPC_PROJECT_BUILD__ +#define XPC_DECL(name) typedef xpc_object_t name##_t +#endif // __XPC_PROJECT_BUILD__ + +#define XPC_GLOBAL_OBJECT(object) ((OS_OBJECT_BRIDGE xpc_object_t)&(object)) +#define XPC_RETURNS_RETAINED OS_OBJECT_RETURNS_RETAINED +XPC_INLINE XPC_NONNULL_ALL +void +_xpc_object_validate(xpc_object_t object) { + void *isa = *(void * volatile *)(OS_OBJECT_BRIDGE void *)object; + (void)isa; +} +#else // OS_OBJECT_USE_OBJC +typedef void * xpc_object_t; +#define XPC_DECL(name) typedef struct _##name##_s * name##_t +#define XPC_GLOBAL_OBJECT(object) (&(object)) +#define XPC_RETURNS_RETAINED +#endif // OS_OBJECT_USE_OBJC + +/*! + * @typedef xpc_handler_t + * The type of block that is accepted by the XPC connection APIs. + * + * @param object + * An XPC object that is to be handled. If there was an error, this object will + * be equal to one of the well-known XPC_ERROR_* dictionaries and can be + * compared with the equality operator. + * + * @discussion + * You are not responsible for releasing the event object. + */ +#if __BLOCKS__ +typedef void (^xpc_handler_t)(xpc_object_t object); +#endif // __BLOCKS__ + +/*! + * @define XPC_TYPE_CONNECTION + * 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_CONNECTION (&_xpc_type_connection) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_connection); +XPC_DECL(xpc_connection); + +/*! + * @typedef xpc_connection_handler_t + * The type of the function that will be invoked for a bundled XPC service when + * there is a new connection on the service. + * + * @param connection + * A new connection that is equivalent to one received by a listener connection. + * See the documentation for {@link xpc_connection_set_event_handler} for the + * semantics associated with the received connection. + */ +typedef void (*xpc_connection_handler_t)(xpc_connection_t connection); + +/*! + * @define XPC_TYPE_ENDPOINT + * A type representing a connection in serialized form. Unlike a connection, an + * endpoint is an inert object that does not have any runtime activity + * associated with it. Thus, it is safe to pass an endpoint in a message. Upon + * receiving an endpoint, the recipient can use + * xpc_connection_create_from_endpoint() to create as many distinct connections + * as desired. + */ +#define XPC_TYPE_ENDPOINT (&_xpc_type_endpoint) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_endpoint); +XPC_DECL(xpc_endpoint); + +/*! + * @define XPC_TYPE_NULL + * A type representing a null object. This type is useful for disambiguating + * an unset key in a dictionary and one which has been reserved but set empty. + * Also, this type is a way to represent a "null" value in dictionaries, which + * do not accept NULL. + */ +#define XPC_TYPE_NULL (&_xpc_type_null) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_null); + +/*! + * @define XPC_TYPE_BOOL + * A type representing a Boolean value. + */ +#define XPC_TYPE_BOOL (&_xpc_type_bool) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_bool); + +/*! + * @define XPC_BOOL_TRUE + * A constant representing a Boolean value of true. You may compare a Boolean + * object against this constant to determine its value. + */ +#define XPC_BOOL_TRUE XPC_GLOBAL_OBJECT(_xpc_bool_true) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +const struct _xpc_bool_s _xpc_bool_true; + +/*! + * @define XPC_BOOL_FALSE + * A constant representing a Boolean value of false. You may compare a Boolean + * object against this constant to determine its value. + */ +#define XPC_BOOL_FALSE XPC_GLOBAL_OBJECT(_xpc_bool_false) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +const struct _xpc_bool_s _xpc_bool_false; + +/*! + * @define XPC_TYPE_INT64 + * A type representing a signed, 64-bit integer value. + */ +#define XPC_TYPE_INT64 (&_xpc_type_int64) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_int64); + +/*! + * @define XPC_TYPE_UINT64 + * A type representing an unsigned, 64-bit integer value. + */ +#define XPC_TYPE_UINT64 (&_xpc_type_uint64) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_uint64); + +/*! + * @define XPC_TYPE_DOUBLE + * A type representing an IEEE-compliant, double-precision floating point value. + */ +#define XPC_TYPE_DOUBLE (&_xpc_type_double) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_double); + +/*! + * @define XPC_TYPE_DATE +* A type representing a date interval. The interval is with respect to the + * Unix epoch. XPC dates are in Unix time and are thus unaware of local time + * or leap seconds. + */ +#define XPC_TYPE_DATE (&_xpc_type_date) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_date); + +/*! + * @define XPC_TYPE_DATA + * A type representing a an arbitrary buffer of bytes. + */ +#define XPC_TYPE_DATA (&_xpc_type_data) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_data); + +/*! + * @define XPC_TYPE_STRING + * A type representing a NUL-terminated C-string. + */ +#define XPC_TYPE_STRING (&_xpc_type_string) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_string); + +/*! + * @define XPC_TYPE_UUID + * A type representing a Universally Unique Identifier as defined by uuid(3). + */ +#define XPC_TYPE_UUID (&_xpc_type_uuid) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_uuid); + +/*! + * @define XPC_TYPE_FD + * A type representing a POSIX file descriptor. + */ +#define XPC_TYPE_FD (&_xpc_type_fd) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_fd); + +/*! + * @define XPC_TYPE_SHMEM + * A type representing a region of shared memory. + */ +#define XPC_TYPE_SHMEM (&_xpc_type_shmem) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_shmem); + +/*! + * @define XPC_TYPE_ARRAY + * A type representing an array of XPC objects. This array must be contiguous, + * i.e. it cannot contain NULL values. If you wish to indicate that a slot + * is empty, you can insert a null object. The array will grow as needed to + * accommodate more objects. + */ +#define XPC_TYPE_ARRAY (&_xpc_type_array) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_array); + +/*! + * @define XPC_TYPE_DICTIONARY + * A type representing a dictionary of XPC objects, keyed off of C-strings. + * You may insert NULL values into this collection. The dictionary will grow + * as needed to accommodate more key/value pairs. + */ +#define XPC_TYPE_DICTIONARY (&_xpc_type_dictionary) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_dictionary); + +/*! + * @define XPC_TYPE_ERROR + * A type representing an error object. Errors in XPC are dictionaries, but + * xpc_get_type() will return this type when given an error object. You + * cannot create an error object directly; XPC will only give them to handlers. + * These error objects have pointer values that are constant across the lifetime + * of your process and can be safely compared. + * + * These constants are enumerated in the header for the connection object. Error + * dictionaries may reserve keys so that they can be queried to obtain more + * detailed information about the error. Currently, the only reserved key is + * XPC_ERROR_KEY_DESCRIPTION. + */ +#define XPC_TYPE_ERROR (&_xpc_type_error) +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +XPC_TYPE(_xpc_type_error); + +/*! + * @define XPC_ERROR_KEY_DESCRIPTION + * In an error dictionary, querying for this key will return a string object + * that describes the error in a human-readable way. + */ +#define XPC_ERROR_KEY_DESCRIPTION _xpc_error_key_description +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +const char *const _xpc_error_key_description; + +/*! + * @define XPC_EVENT_KEY_NAME + * In an event dictionary, this querying for this key will return a string + * object that describes the event. + */ +#define XPC_EVENT_KEY_NAME _xpc_event_key_name +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +const char *const _xpc_event_key_name; + +XPC_ASSUME_NONNULL_END +#ifndef __XPC_BUILDING_XPC__ +#include +#include +#if __BLOCKS__ +#include +#include +#endif // __BLOCKS__ +#undef __XPC_INDIRECT__ +#include +#endif // __XPC_BUILDING_XPC__ +XPC_ASSUME_NONNULL_BEGIN + +#pragma mark XPC Object Protocol +/*! + * @function xpc_retain + * + * @abstract + * Increments the reference count of an object. + * + * @param object + * The object which is to be manipulated. + * + * @result + * The object which was given. + * + * @discussion + * Calls to xpc_retain() must be balanced with calls to xpc_release() + * to avoid leaking memory. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +xpc_object_t +xpc_retain(xpc_object_t object); +#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE +#undef xpc_retain +#define xpc_retain(object) ({ xpc_object_t _o = (object); \ + _xpc_object_validate(_o); [_o retain]; }) +#endif // OS_OBJECT_USE_OBJC_RETAIN_RELEASE + +/*! + * @function xpc_release + * + * @abstract + * Decrements the reference count of an object. + * + * @param object + * The object which is to be manipulated. + * + * @discussion + * The caller must take care to balance retains and releases. When creating or + * retaining XPC objects, the creator obtains a reference on the object. Thus, + * it is the caller's responsibility to call xpc_release() on those objects when + * they are no longer needed. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_release(xpc_object_t object); +#if OS_OBJECT_USE_OBJC_RETAIN_RELEASE +#undef xpc_release +#define xpc_release(object) ({ xpc_object_t _o = (object); \ + _xpc_object_validate(_o); [_o release]; }) +#endif // OS_OBJECT_USE_OBJC_RETAIN_RELEASE + +/*! + * @function xpc_get_type + * + * @abstract + * Returns the type of an object. + * + * @param object + * The object to examine. + * + * @result + * An opaque pointer describing the type of the object. This pointer is suitable + * direct comparison to exported type constants with the equality operator. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT +xpc_type_t +xpc_get_type(xpc_object_t object); + +/*! + * @function xpc_copy + * + * @abstract + * Creates a copy of the object. + * + * @param object + * The object to copy. + * + * @result + * The new object. NULL if the object type does not support copying or if + * sufficient memory for the copy could not be allocated. Service objects do + * not support copying. + * + * @discussion + * When called on an array or dictionary, xpc_copy() will perform a deep copy. + * + * The object returned is not necessarily guaranteed to be a new object, and + * whether it is will depend on the implementation of the object being copied. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT XPC_RETURNS_RETAINED +xpc_object_t _Nullable +xpc_copy(xpc_object_t object); + +/*! + * @function xpc_equal + * + * @abstract + * Compares two objects for equality. + * + * @param object1 + * The first object to compare. + * + * @param object2 + * The second object to compare. + * + * @result + * Returns true if the objects are equal, otherwise false. Two objects must be + * of the same type in order to be equal. + * + * For two arrays to be equal, they must contain the same values at the + * same indexes. For two dictionaries to be equal, they must contain the same + * values for the same keys. + * + * Two objects being equal implies that their hashes (as returned by xpc_hash()) + * are also equal. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_WARN_RESULT +bool +xpc_equal(xpc_object_t object1, xpc_object_t object2); + +/*! + * @function xpc_hash + * + * @abstract + * Calculates a hash value for the given object. + * + * @param object + * The object for which to calculate a hash value. This value may be modded + * with a table size for insertion into a dictionary-like data structure. + * + * @result + * The calculated hash value. + * + * @discussion + * Note that the computed hash values for any particular type and value of an + * object can change from across releases and platforms and should not be + * assumed to be constant across all time and space or stored persistently. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_WARN_RESULT +size_t +xpc_hash(xpc_object_t object); + +/*! + * @function xpc_copy_description + * + * @abstract + * Copies a debug string describing the object. + * + * @param object + * The object which is to be examined. + * + * @result + * A string describing object which contains information useful for debugging. + * This string should be disposed of with free(3) when done. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_WARN_RESULT XPC_NONNULL1 +char * +xpc_copy_description(xpc_object_t object); + +#pragma mark XPC Object Types +#pragma mark Null +/*! + * @function xpc_null_create + * + * @abstract + * Creates an XPC object representing the null object. + * + * @result + * A new null object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_null_create(void); + +#pragma mark Boolean +/*! + * @function xpc_bool_create + * + * @abstract + * Creates an XPC Boolean object. + * + * @param value + * The Boolean primitive value which is to be boxed. + * + * @result + * A new Boolean object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_bool_create(bool value); + +/*! + * @function xpc_bool_get_value + * + * @abstract + * Returns the underlying Boolean value from the object. + * + * @param xbool + * The Boolean object which is to be examined. + * + * @result + * The underlying Boolean value or false if the given object was not an XPC + * Boolean object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +bool +xpc_bool_get_value(xpc_object_t xbool); + +#pragma mark Signed Integer +/*! + * @function xpc_int64_create + * + * @abstract + * Creates an XPC signed integer object. + * + * @param value + * The signed integer value which is to be boxed. + * + * @result + * A new signed integer object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_int64_create(int64_t value); + +/*! + * @function xpc_int64_get_value + * + * @abstract + * Returns the underlying signed 64-bit integer value from an object. + * + * @param xint + * The signed integer object which is to be examined. + * + * @result + * The underlying signed 64-bit value or 0 if the given object was not an XPC + * integer object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +int64_t +xpc_int64_get_value(xpc_object_t xint); + +#pragma mark Unsigned Integer +/*! + * @function xpc_uint64_create + * + * @abstract + * Creates an XPC unsigned integer object. + * + * @param value + * The unsigned integer value which is to be boxed. + * + * @result + * A new unsigned integer object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_uint64_create(uint64_t value); + +/*! + * @function xpc_uint64_get_value + * + * @abstract + * Returns the underlying unsigned 64-bit integer value from an object. + * + * @param xuint + * The unsigned integer object which is to be examined. + * + * @result + * The underlying unsigned integer value or 0 if the given object was not an XPC + * unsigned integer object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +uint64_t +xpc_uint64_get_value(xpc_object_t xuint); + +#pragma mark Double +/*! + * @function xpc_double_create + * + * @abstract + * Creates an XPC double object. + * + * @param value + * The floating point quantity which is to be boxed. + * + * @result + * A new floating point object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_double_create(double value); + +/*! + * @function xpc_double_get_value + * + * @abstract + * Returns the underlying double-precision floating point value from an object. + * + * @param xdouble + * The floating point object which is to be examined. + * + * @result + * The underlying floating point value or NAN if the given object was not an XPC + * floating point object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +double +xpc_double_get_value(xpc_object_t xdouble); + +#pragma mark Date +/*! + * @function xpc_date_create + * + * @abstract + * Creates an XPC date object. + * + * @param interval + * The date interval which is to be boxed. Negative values indicate the number + * of nanoseconds before the epoch. Positive values indicate the number of + * nanoseconds after the epoch. + * + * @result + * A new date object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_date_create(int64_t interval); + +/*! + * @function xpc_date_create_from_current + * + * @abstract + * Creates an XPC date object representing the current date. + * + * @result + * A new date object representing the current date. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_date_create_from_current(void); + +/*! + * @function xpc_date_get_value + * + * @abstract + * Returns the underlying date interval from an object. + * + * @param xdate + * The date object which is to be examined. + * + * @result + * The underlying date interval or 0 if the given object was not an XPC date + * object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +int64_t +xpc_date_get_value(xpc_object_t xdate); + +#pragma mark Data +/*! + * @function xpc_data_create + * + * @abstract + * Creates an XPC object representing buffer of bytes. + * + * @param bytes + * The buffer of bytes which is to be boxed. You may create an empty data object + * by passing NULL for this parameter and 0 for the length. Passing NULL with + * any other length will result in undefined behavior. + * + * @param length + * The number of bytes which are to be boxed. + * + * @result + * A new data object. + * + * @discussion + * This method will copy the buffer given into internal storage. After calling + * this method, it is safe to dispose of the given buffer. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_data_create(const void * _Nullable bytes, size_t length); + +/*! + * @function xpc_data_create_with_dispatch_data + * + * @abstract + * Creates an XPC object representing buffer of bytes described by the given GCD + * data object. + * + * @param ddata + * The GCD data object containing the bytes which are to be boxed. This object + * is retained by the data object. + * + * @result + * A new data object. + * + * @discussion + * The object returned by this method will refer to the buffer returned by + * dispatch_data_create_map(). The point where XPC will make the call to + * dispatch_data_create_map() is undefined. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +xpc_object_t +xpc_data_create_with_dispatch_data(dispatch_data_t ddata); + +/*! + * @function xpc_data_get_length + * + * @abstract + * Returns the length of the data encapsulated by an XPC data object. + * + * @param xdata + * The data object which is to be examined. + * + * @result + * The length of the underlying boxed data or 0 if the given object was not an + * XPC data object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +size_t +xpc_data_get_length(xpc_object_t xdata); + +/*! + * @function xpc_data_get_bytes_ptr + * + * @abstract + * Returns a pointer to the internal storage of a data object. + * + * @param xdata + * The data object which is to be examined. + * + * @result + * A pointer to the underlying boxed data or NULL if the given object was not an + * XPC data object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +const void * _Nullable +xpc_data_get_bytes_ptr(xpc_object_t xdata); + +/*! + * @function xpc_data_get_bytes + * + * @abstract + * Copies the bytes stored in an data objects into the specified buffer. + * + * @param xdata + * The data object which is to be examined. + * + * @param buffer + * The buffer in which to copy the data object's bytes. + * + * @param off + * The offset at which to begin the copy. If this offset is greater than the + * length of the data element, nothing is copied. Pass 0 to start the copy + * at the beginning of the buffer. + * + * @param length + * The length of the destination buffer. + * + * @result + * The number of bytes that were copied into the buffer or 0 if the given object + * was not an XPC data object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2 +size_t +xpc_data_get_bytes(xpc_object_t xdata, + void *buffer, size_t off, size_t length); + +#pragma mark String +/*! + * @function xpc_string_create + * + * @abstract + * Creates an XPC object representing a NUL-terminated C-string. + * + * @param string + * The C-string which is to be boxed. + * + * @result + * A new string object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +xpc_object_t +xpc_string_create(const char *string); + +/*! + * @function xpc_string_create_with_format + * + * @abstract + * Creates an XPC object representing a C-string that is generated from the + * given format string and arguments. + * + * @param fmt + * The printf(3)-style format string from which to construct the final C-string + * to be boxed. + * + * @param ... + * The arguments which correspond to those specified in the format string. + * + * @result + * A new string object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +XPC_PRINTF(1, 2) +xpc_object_t +xpc_string_create_with_format(const char *fmt, ...); + +/*! + * @function xpc_string_create_with_format_and_arguments + * + * @abstract + * Creates an XPC object representing a C-string that is generated from the + * given format string and argument list pointer. + * + * @param fmt + * The printf(3)-style format string from which to construct the final C-string + * to be boxed. + * + * @param ap + * A pointer to the arguments which correspond to those specified in the format + * string. + * + * @result + * A new string object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +XPC_PRINTF(1, 0) +xpc_object_t +xpc_string_create_with_format_and_arguments(const char *fmt, va_list ap); + +/*! + * @function xpc_string_get_length + * + * @abstract + * Returns the length of the underlying string. + * + * @param xstring + * The string object which is to be examined. + * + * @result + * The length of the underlying string, not including the NUL-terminator, or 0 + * if the given object was not an XPC string object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +size_t +xpc_string_get_length(xpc_object_t xstring); + +/*! + * @function xpc_string_get_string_ptr + * + * @abstract + * Returns a pointer to the internal storage of a string object. + * + * @param xstring + * The string object which is to be examined. + * + * @result + * A pointer to the string object's internal storage or NULL if the given object + * was not an XPC string object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +const char * _Nullable +xpc_string_get_string_ptr(xpc_object_t xstring); + +#pragma mark UUID +/*! + * @function xpc_uuid_create + * + * @abstract + * Creates an XPC object representing a universally-unique identifier (UUID) as + * described by uuid(3). + * + * @param uuid + * The UUID which is to be boxed. + * + * @result + * A new UUID object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +xpc_object_t +xpc_uuid_create(const uuid_t XPC_NONNULL_ARRAY uuid); + +/*! + * @function xpc_uuid_get_bytes + * + * @abstract + * Returns a pointer to the the boxed UUID bytes in an XPC UUID object. + * + * @param xuuid + * The UUID object which is to be examined. + * + * @result + * The underlying uuid_t bytes or NULL if the given object was not + * an XPC UUID object. The returned pointer may be safely passed to the uuid(3) + * APIs. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +const uint8_t * _Nullable +xpc_uuid_get_bytes(xpc_object_t xuuid); + +#pragma mark File Descriptors +/*! + * @function xpc_fd_create + * + * @abstract + * Creates an XPC object representing a POSIX file descriptor. + * + * @param fd + * The file descriptor which is to be boxed. + * + * @result + * A new file descriptor object. NULL if sufficient memory could not be + * allocated or if the given file descriptor was not valid. + * + * @discussion + * This method performs the equivalent of a dup(2) on the descriptor, and thus + * it is safe to call close(2) on the descriptor after boxing it with a file + * descriptor object. + * + * IMPORTANT: Pointer equality is the ONLY valid test for equality between two + * file descriptor objects. There is no reliable way to determine whether two + * file descriptors refer to the same inode with the same capabilities, so two + * file descriptor objects created from the same underlying file descriptor + * number will not compare equally with xpc_equal(). This is also true of a + * file descriptor object created using xpc_copy() and the original. + * + * This also implies that two collections containing file descriptor objects + * cannot be equal unless the exact same object was inserted into both. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t _Nullable +xpc_fd_create(int fd); + +/*! + * @function xpc_fd_dup + * + * @abstract + * Returns a file descriptor that is equivalent to the one boxed by the file + * file descriptor object. + * + * @param xfd + * The file descriptor object which is to be examined. + * + * @result + * A file descriptor that is equivalent to the one originally given to + * xpc_fd_create(). If the descriptor could not be created or if the given + * object was not an XPC file descriptor, -1 is returned. + * + * @discussion + * Multiple invocations of xpc_fd_dup() will not return the same file descriptor + * number, but they will return descriptors that are equivalent, as though they + * had been created by dup(2). + * + * The caller is responsible for calling close(2) on the returned descriptor. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +int +xpc_fd_dup(xpc_object_t xfd); + +#pragma mark Shared Memory +/*! + * @function xpc_shmem_create + * + * @abstract + * Creates an XPC object representing the given shared memory region. + * + * @param region + * A pointer to a region of shared memory, created through a call to mmap(2) + * with the MAP_SHARED flag, which is to be boxed. + * + * @param length + * The length of the region. + * + * @result + * A new shared memory object. + * + * @discussion + * Only memory regions whose exact characteristics are known to the caller + * should be boxed using this API. Memory returned from malloc(3) may not be + * safely shared on either OS X or iOS because the underlying virtual memory + * objects for malloc(3)ed allocations are owned by the malloc(3) subsystem and + * not the caller of malloc(3). + * + * If you wish to share a memory region that you receive from another subsystem, + * part of the interface contract with that other subsystem must include how to + * create the region of memory, or sharing it may be unsafe. + * + * Certain operations may internally fragment a region of memory in a way that + * would truncate the range detected by the shared memory object. vm_copy(), for + * example, may split the region into multiple parts to avoid copying certain + * page ranges. For this reason, it is recommended that you delay all VM + * operations until the shared memory object has been created so that the VM + * system knows that the entire range is intended for sharing. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +xpc_object_t +xpc_shmem_create(void *region, size_t length); + +/*! + * @function xpc_shmem_map + * + * @abstract + * Maps the region boxed by the XPC shared memory object into the caller's + * address space. + * + * @param xshmem + * The shared memory object to be examined. + * + * @param region + * On return, this will point to the region at which the shared memory was + * mapped. + * + * @result + * The length of the region that was mapped. If the mapping failed or if the + * given object was not an XPC shared memory object, 0 is returned. The length + * of the mapped region will always be an integral page size, even if the + * creator of the region specified a non-integral page size. + * + * @discussion + * The resulting region must be disposed of with munmap(2). + * + * It is the responsibility of the caller to manage protections on the new + * region accordingly. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +size_t +xpc_shmem_map(xpc_object_t xshmem, void * _Nullable * _Nonnull region); + +#pragma mark Array +/*! + * @typedef xpc_array_applier_t + * A block to be invoked for every value in the array. + * + * @param index + * The current index in the iteration. + * + * @param value + * The current value in the iteration. + * + * @result + * A Boolean indicating whether iteration should continue. + */ +#ifdef __BLOCKS__ +typedef bool (^xpc_array_applier_t)(size_t index, xpc_object_t _Nonnull value); +#endif // __BLOCKS__ + +/*! + * @function xpc_array_create + * + * @abstract + * Creates an XPC object representing an array of XPC objects. + * + * @discussion + * This array must be contiguous and cannot contain any NULL values. If you + * wish to insert the equivalent of a NULL value, you may use the result of + * {@link xpc_null_create}. + * + * @param objects + * An array of XPC objects which is to be boxed. The order of this array is + * preserved in the object. If this array contains a NULL value, the behavior + * is undefined. This parameter may be NULL only if the count is 0. + * + * @param count + * The number of objects in the given array. If the number passed is less than + * the actual number of values in the array, only the specified number of items + * are inserted into the resulting array. If the number passed is more than + * the the actual number of values, the behavior is undefined. + * + * @result + * A new array object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_array_create(const xpc_object_t _Nonnull * _Nullable objects, size_t count); + +/*! + * @function xpc_array_set_value + * + * @abstract + * Inserts the specified object into the array at the specified index. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array). + * If the index is outside that range, the behavior is undefined. + * + * @param value + * The object to insert. This value is retained by the array and cannot be + * NULL. If there is already a value at the specified index, it is released, + * and the new value is inserted in its place. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 +void +xpc_array_set_value(xpc_object_t xarray, size_t index, xpc_object_t value); + +/*! + * @function xpc_array_append_value + * + * @abstract + * Appends an object to an XPC array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param value + * The object to append. This object is retained by the array. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_array_append_value(xpc_object_t xarray, xpc_object_t value); + +/*! + * @function xpc_array_get_count + * + * @abstract + * Returns the count of values currently in the array. + * + * @param xarray + * The array object which is to be examined. + * + * @result + * The count of values in the array or 0 if the given object was not an XPC + * array. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +size_t +xpc_array_get_count(xpc_object_t xarray); + +/*! + * @function xpc_array_get_value + * + * @abstract + * Returns the value at the specified index in the array. + * + * @param xarray + * The array object which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the range of + * indexes as specified in xpc_array_set_value(). + * + * @result + * The object at the specified index within the array or NULL if the given + * object was not an XPC array. + * + * @discussion + * This method does not grant the caller a reference to the underlying object, + * and thus the caller is not responsible for releasing the object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +xpc_object_t +xpc_array_get_value(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_apply + * + * @abstract + * Invokes the given block for every value in the array. + * + * @param xarray + * The array object which is to be examined. + * + * @param applier + * The block which this function applies to every element in the array. + * + * @result + * A Boolean indicating whether iteration of the array completed successfully. + * Iteration will only fail if the applier block returns false. + * + * @discussion + * You should not modify an array's contents during iteration. The array indexes + * are iterated in order. + */ +#ifdef __BLOCKS__ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +bool +xpc_array_apply(xpc_object_t xarray, XPC_NOESCAPE xpc_array_applier_t applier); +#endif // __BLOCKS__ + +#pragma mark Array Primitive Setters +/*! + * @define XPC_ARRAY_APPEND + * A constant that may be passed as the destination index to the class of + * primitive XPC array setters indicating that the given primitive should be + * appended to the array. + */ +#define XPC_ARRAY_APPEND ((size_t)(-1)) + +/*! + * @function xpc_array_set_bool + * + * @abstract + * Inserts a bool (primitive) value into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param value + * The bool value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_array_set_bool(xpc_object_t xarray, size_t index, bool value); + +/*! + * @function xpc_array_set_int64 + * + * @abstract + * Inserts an int64_t (primitive) value into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param value + * The int64_t value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_array_set_int64(xpc_object_t xarray, size_t index, int64_t value); + +/*! + * @function xpc_array_set_uint64 + * + * @abstract + * Inserts a uint64_t (primitive) value into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param value + * The uint64_t value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_array_set_uint64(xpc_object_t xarray, size_t index, uint64_t value); + +/*! + * @function xpc_array_set_double + * + * @abstract + * Inserts a double (primitive) value into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param value + * The double value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_array_set_double(xpc_object_t xarray, size_t index, double value); + +/*! + * @function xpc_array_set_date + * + * @abstract + * Inserts a date value into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param value + * The date value to insert, represented as an int64_t. After + * calling this method, the XPC object corresponding to the primitive value + * inserted may be safely retrieved with {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_array_set_date(xpc_object_t xarray, size_t index, int64_t value); + +/*! + * @function xpc_array_set_data + * + * @abstract + * Inserts a raw data value into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param bytes + * The raw data to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved with + * {@link xpc_array_get_value()}. + * + * @param length + * The length of the data. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 +void +xpc_array_set_data(xpc_object_t xarray, size_t index, const void *bytes, + size_t length); + +/*! + * @function xpc_array_set_string + * + * @abstract + * Inserts a C string into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param string + * The C string to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved with + * {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 +void +xpc_array_set_string(xpc_object_t xarray, size_t index, const char *string); + +/*! + * @function xpc_array_set_uuid + * + * @abstract + * Inserts a uuid_t (primitive) value into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param uuid + * The UUID primitive to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved with + * {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 +void +xpc_array_set_uuid(xpc_object_t xarray, size_t index, + const uuid_t XPC_NONNULL_ARRAY uuid); + +/*! + * @function xpc_array_set_fd + * + * @abstract + * Inserts a file descriptor into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param fd + * The file descriptor to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved with + * {@link xpc_array_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 +void +xpc_array_set_fd(xpc_object_t xarray, size_t index, int fd); + +/*! + * @function xpc_array_set_connection + * + * @abstract + * Inserts a connection into an array. + * + * @param xarray + * The array object which is to be manipulated. + * + * @param index + * The index at which to insert the value. This value must lie within the index + * space of the array (0 to N-1 inclusive, where N is the count of the array) or + * be XPC_ARRAY_APPEND. If the index is outside that range, the behavior is + * undefined. + * + * @param connection + * The connection to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved with + * {@link xpc_array_get_value()}. The connection is NOT retained by the array. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 +void +xpc_array_set_connection(xpc_object_t xarray, size_t index, + xpc_connection_t connection); + +#pragma mark Array Primitive Getters +/*! + * @function xpc_array_get_bool + * + * @abstract + * Gets a bool primitive value from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * The underlying bool value at the specified index. false if the + * value at the specified index is not a Boolean value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +bool +xpc_array_get_bool(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_get_int64 + * + * @abstract + * Gets an int64_t primitive value from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * The underlying int64_t value at the specified index. 0 if the + * value at the specified index is not a signed integer value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +int64_t +xpc_array_get_int64(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_get_uint64 + * + * @abstract + * Gets a uint64_t primitive value from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * The underlying uint64_t value at the specified index. 0 if the + * value at the specified index is not an unsigned integer value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +uint64_t +xpc_array_get_uint64(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_get_double + * + * @abstract + * Gets a double primitive value from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * The underlying double value at the specified index. NAN if the + * value at the specified index is not a floating point value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +double +xpc_array_get_double(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_get_date + * + * @abstract + * Gets a date interval from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * The underlying date interval at the specified index. 0 if the value at the + * specified index is not a date value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +int64_t +xpc_array_get_date(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_get_data + * + * @abstract + * Gets a pointer to the raw bytes of a data object from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @param length + * Upon return output, will contain the length of the data corresponding to the + * specified key. + * + * @result + * The underlying bytes at the specified index. NULL if the value at the + * specified index is not a data value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +const void * _Nullable +xpc_array_get_data(xpc_object_t xarray, size_t index, + size_t * _Nullable length); + +/*! + * @function xpc_array_get_string + * + * @abstract + * Gets a C string value from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * The underlying C string at the specified index. NULL if the value at the + * specified index is not a C string value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +const char * _Nullable +xpc_array_get_string(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_get_uuid + * + * @abstract + * Gets a uuid_t value from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * The underlying uuid_t value at the specified index. The null + * UUID if the value at the specified index is not a UUID value. The returned + * pointer may be safely passed to the uuid(3) APIs. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +const uint8_t * _Nullable +xpc_array_get_uuid(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_dup_fd + * + * @abstract + * Gets a file descriptor from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * A new file descriptor created from the value at the specified index. You are + * responsible for close(2)ing this descriptor. -1 if the value at the specified + * index is not a file descriptor value. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +int +xpc_array_dup_fd(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_create_connection + * + * @abstract + * Creates a connection object from an array directly. + * + * @param xarray + * The array which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the index space + * of the array (0 to N-1 inclusive, where N is the count of the array). If the + * index is outside that range, the behavior is undefined. + * + * @result + * A new connection created from the value at the specified index. You are + * responsible for calling xpc_release() on the returned connection. NULL if the + * value at the specified index is not an endpoint containing a connection. Each + * call to this method for the same index in the same array will yield a + * different connection. See {@link xpc_connection_create_from_endpoint()} for + * discussion as to the responsibilities when dealing with the returned + * connection. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1 +xpc_connection_t _Nullable +xpc_array_create_connection(xpc_object_t xarray, size_t index); + +/*! + * @function xpc_array_get_dictionary + * + * @abstract + * Returns the dictionary at the specified index in the array. + * + * @param xarray + * The array object which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the range of + * indexes as specified in xpc_array_set_value(). + * + * @result + * The object at the specified index within the array or NULL if the given + * object was not an XPC array or if the the value at the specified index was + * not a dictionary. + * + * @discussion + * This method does not grant the caller a reference to the underlying object, + * and thus the caller is not responsible for releasing the object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_object_t _Nullable +xpc_array_get_dictionary(xpc_object_t self, size_t index); + +/*! + * @function xpc_array_get_array + * + * @abstract + * Returns the array at the specified index in the array. + * + * @param xarray + * The array object which is to be examined. + * + * @param index + * The index of the value to obtain. This value must lie within the range of + * indexes as specified in xpc_array_set_value(). + * + * @result + * The object at the specified index within the array or NULL if the given + * object was not an XPC array or if the the value at the specified index was + * not an array. + * + * @discussion + * This method does not grant the caller a reference to the underlying object, + * and thus the caller is not responsible for releasing the object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_object_t _Nullable +xpc_array_get_array(xpc_object_t self, size_t index); + +#pragma mark Dictionary +/*! + * @typedef xpc_dictionary_applier_t + * A block to be invoked for every key/value pair in the dictionary. + * + * @param key + * The current key in the iteration. + * + * @param value + * The current value in the iteration. + * + * @result + * A Boolean indicating whether iteration should continue. + */ +#ifdef __BLOCKS__ +typedef bool (^xpc_dictionary_applier_t)(const char * _Nonnull key, + xpc_object_t _Nonnull value); +#endif // __BLOCKS__ + +/*! + * @function xpc_dictionary_create + * + * @abstract + * Creates an XPC object representing a dictionary of XPC objects keyed to + * C-strings. + * + * @param keys + * An array of C-strings that are to be the keys for the values to be inserted. + * Each element of this array is copied into the dictionary's internal storage. + * Elements of this array may NOT be NULL. + * + * @param values + * A C-array that is parallel to the array of keys, consisting of objects that + * are to be inserted. Each element in this array is retained. Elements in this + * array may be NULL. + * + * @param count + * The number of key/value pairs in the given arrays. If the count is less than + * the actual count of values, only that many key/value pairs will be inserted + * into the dictionary. + * + * If the count is more than the the actual count of key/value pairs, the + * behavior is undefined. If one array is NULL and the other is not, the + * behavior is undefined. If both arrays are NULL and the count is non-0, the + * behavior is undefined. + * + * @result + * The new dictionary object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT +xpc_object_t +xpc_dictionary_create(const char * _Nonnull const * _Nullable keys, + const xpc_object_t _Nullable * _Nullable values, size_t count); + +/*! + * @function xpc_dictionary_create_reply + * + * @abstract + * Creates a dictionary that is in reply to the given dictionary. + * + * @param original + * The original dictionary that is to be replied to. + * + * @result + * The new dictionary object. NULL if the object was not a dictionary with a + * reply context. + * + * @discussion + * After completing successfully on a dictionary, this method may not be called + * again on that same dictionary. Attempts to do so will return NULL. + * + * When this dictionary is sent across the reply connection, the remote end's + * reply handler is invoked. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_object_t _Nullable +xpc_dictionary_create_reply(xpc_object_t original); + +/*! + * @function xpc_dictionary_set_value + * + * @abstract + * Sets the value for the specified key to the specified object. + * + * @param xdict + * The dictionary object which is to be manipulated. + * + * @param key + * The key for which the value shall be set. + * + * @param value + * The object to insert. The object is retained by the dictionary. If there + * already exists a value for the specified key, the old value is released + * and overwritten by the new value. This parameter may be NULL, in which case + * the value corresponding to the specified key is deleted if present. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_dictionary_set_value(xpc_object_t xdict, const char *key, + xpc_object_t _Nullable value); + +/*! + * @function xpc_dictionary_get_value + * + * @abstract + * Returns the value for the specified key. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The object for the specified key within the dictionary. NULL if there is no + * value associated with the specified key or if the given object was not an + * XPC dictionary. + * + * @discussion + * This method does not grant the caller a reference to the underlying object, + * and thus the caller is not responsible for releasing the object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2 +xpc_object_t _Nullable +xpc_dictionary_get_value(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_count + * + * @abstract + * Returns the number of values stored in the dictionary. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @result + * The number of values stored in the dictionary or 0 if the given object was + * not an XPC dictionary. Calling xpc_dictionary_set_value() with a non-NULL + * value will increment the count. Calling xpc_dictionary_set_value() with a + * NULL value will decrement the count. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +size_t +xpc_dictionary_get_count(xpc_object_t xdict); + +/*! + * @function xpc_dictionary_apply + * + * @abstract + * Invokes the given block for every key/value pair in the dictionary. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param applier + * The block which this function applies to every key/value pair in the + * dictionary. + * + * @result + * A Boolean indicating whether iteration of the dictionary completed + * successfully. Iteration will only fail if the applier block returns false. + * + * @discussion + * You should not modify a dictionary's contents during iteration. There is no + * guaranteed order of iteration over dictionaries. + */ +#ifdef __BLOCKS__ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL_ALL +bool +xpc_dictionary_apply(xpc_object_t xdict, + XPC_NOESCAPE xpc_dictionary_applier_t applier); +#endif // __BLOCKS__ + +/*! + * @function xpc_dictionary_get_remote_connection + * + * @abstract + * Returns the connection from which the dictionary was received. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @result + * If the dictionary was received by a connection event handler or a dictionary + * created through xpc_dictionary_create_reply(), a connection object over which + * a reply message can be sent is returned. For any other dictionary, NULL is + * returned. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_connection_t _Nullable +xpc_dictionary_get_remote_connection(xpc_object_t xdict); + +#pragma mark Dictionary Primitive Setters +/*! + * @function xpc_dictionary_set_bool + * + * @abstract + * Inserts a bool (primitive) value into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param value + * The bool value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_dictionary_set_bool(xpc_object_t xdict, const char *key, bool value); + +/*! + * @function xpc_dictionary_set_int64 + * + * @abstract + * Inserts an int64_t (primitive) value into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param value + * The int64_t value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_dictionary_set_int64(xpc_object_t xdict, const char *key, int64_t value); + +/*! + * @function xpc_dictionary_set_uint64 + * + * @abstract + * Inserts a uint64_t (primitive) value into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param value + * The uint64_t value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_dictionary_set_uint64(xpc_object_t xdict, const char *key, uint64_t value); + +/*! + * @function xpc_dictionary_set_double + * + * @abstract + * Inserts a double (primitive) value into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param value + * The double value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_dictionary_set_double(xpc_object_t xdict, const char *key, double value); + +/*! + * @function xpc_dictionary_set_date + * + * @abstract + * Inserts a date (primitive) value into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param value + * The date value to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved with + * {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_dictionary_set_date(xpc_object_t xdict, const char *key, int64_t value); + +/*! + * @function xpc_dictionary_set_data + * + * @abstract + * Inserts a raw data value into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param bytes + * The bytes to insert. After calling this method, the XPC object corresponding + * to the primitive value inserted may be safely retrieved with + * {@link xpc_dictionary_get_value()}. + * + * @param length + * The length of the data. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 +void +xpc_dictionary_set_data(xpc_object_t xdict, const char *key, const void *bytes, + size_t length); + +/*! + * @function xpc_dictionary_set_string + * + * @abstract + * Inserts a C string value into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param string + * The C string to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved with + * {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 +void +xpc_dictionary_set_string(xpc_object_t xdict, const char *key, + const char *string); + +/*! + * @function xpc_dictionary_set_uuid + * + * @abstract + * Inserts a uuid (primitive) value into an array. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param uuid + * The uuid_t value to insert. After calling this method, the XPC + * object corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 +void +xpc_dictionary_set_uuid(xpc_object_t xdict, const char *key, + const uuid_t XPC_NONNULL_ARRAY uuid); + +/*! + * @function xpc_dictionary_set_fd + * + * @abstract + * Inserts a file descriptor into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param fd + * The file descriptor to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_dictionary_get_value()}. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 +void +xpc_dictionary_set_fd(xpc_object_t xdict, const char *key, int fd); + +/*! + * @function xpc_dictionary_set_connection + * + * @abstract + * Inserts a connection into a dictionary. + * + * @param xdict + * The dictionary which is to be manipulated. + * + * @param key + * The key for which the primitive value shall be set. + * + * @param connection + * The connection to insert. After calling this method, the XPC object + * corresponding to the primitive value inserted may be safely retrieved + * with {@link xpc_dictionary_get_value()}. The connection is NOT retained by + * the dictionary. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL3 +void +xpc_dictionary_set_connection(xpc_object_t xdict, const char *key, + xpc_connection_t connection); + +#pragma mark Dictionary Primitive Getters +/*! + * @function xpc_dictionary_get_bool + * + * @abstract + * Gets a bool primitive value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The underlying bool value for the specified key. false if the + * the value for the specified key is not a Boolean value or if there is no + * value for the specified key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +bool +xpc_dictionary_get_bool(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_int64 + * + * @abstract + * Gets an int64 primitive value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The underlying int64_t value for the specified key. 0 if the + * value for the specified key is not a signed integer value or if there is no + * value for the specified key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +int64_t +xpc_dictionary_get_int64(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_uint64 + * + * @abstract + * Gets a uint64 primitive value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The underlying uint64_t value for the specified key. 0 if the + * value for the specified key is not an unsigned integer value or if there is + * no value for the specified key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +uint64_t +xpc_dictionary_get_uint64(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_double + * + * @abstract + * Gets a double primitive value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The underlying double value for the specified key. NAN if the + * value for the specified key is not a floating point value or if there is no + * value for the specified key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +double +xpc_dictionary_get_double(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_date + * + * @abstract + * Gets a date value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The underlying date interval for the specified key. 0 if the value for the + * specified key is not a date value or if there is no value for the specified + * key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +int64_t +xpc_dictionary_get_date(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_data + * + * @abstract + * Gets a raw data value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @param length + * For the data type, the third parameter, upon output, will contain the length + * of the data corresponding to the specified key. May be NULL. + * + * @result + * The underlying raw data for the specified key. NULL if the value for the + * specified key is not a data value or if there is no value for the specified + * key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 +const void * _Nullable +xpc_dictionary_get_data(xpc_object_t xdict, const char *key, + size_t * _Nullable length); + +/*! + * @function xpc_dictionary_get_string + * + * @abstract + * Gets a C string value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The underlying C string for the specified key. NULL if the value for the + * specified key is not a C string value or if there is no value for the + * specified key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +const char * _Nullable +xpc_dictionary_get_string(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_uuid + * + * @abstract + * Gets a uuid value from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The underlying uuid_t value for the specified key. NULL is the + * value at the specified index is not a UUID value. The returned pointer may be + * safely passed to the uuid(3) APIs. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL1 XPC_NONNULL2 +const uint8_t * _Nullable +xpc_dictionary_get_uuid(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_dup_fd + * + * @abstract + * Creates a file descriptor from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * A new file descriptor created from the value for the specified key. You are + * responsible for close(2)ing this descriptor. -1 if the value for the + * specified key is not a file descriptor value or if there is no value for the + * specified key. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +int +xpc_dictionary_dup_fd(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_create_connection + * + * @abstract + * Creates a connection from a dictionary directly. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * A new connection created from the value for the specified key. You are + * responsible for calling xpc_release() on the returned connection. NULL if the + * value for the specified key is not an endpoint containing a connection or if + * there is no value for the specified key. Each call to this method for the + * same key in the same dictionary will yield a different connection. See + * {@link xpc_connection_create_from_endpoint()} for discussion as to the + * responsibilities when dealing with the returned connection. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_connection_t _Nullable +xpc_dictionary_create_connection(xpc_object_t xdict, const char *key); + +/*! + * @function xpc_dictionary_get_dictionary + * + * @abstract + * Returns the dictionary value for the specified key. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The object for the specified key within the dictionary. NULL if there is no + * value associated with the specified key, if the given object was not an + * XPC dictionary, or if the object for the specified key is not a dictionary. + * + * @discussion + * This method does not grant the caller a reference to the underlying object, + * and thus the caller is not responsible for releasing the object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_object_t _Nullable +xpc_dictionary_get_dictionary(xpc_object_t self, const char *key); + +/*! + * @function xpc_dictionary_get_array + * + * @abstract + * Returns the array value for the specified key. + * + * @param xdict + * The dictionary object which is to be examined. + * + * @param key + * The key whose value is to be obtained. + * + * @result + * The object for the specified key within the dictionary. NULL if there is no + * value associated with the specified key, if the given object was not an + * XPC dictionary, or if the object for the specified key is not an array. + * + * @discussion + * This method does not grant the caller a reference to the underlying object, + * and thus the caller is not responsible for releasing the object. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0) +XPC_EXPORT XPC_WARN_RESULT XPC_NONNULL_ALL +xpc_object_t _Nullable +xpc_dictionary_get_array(xpc_object_t self, const char *key); + +#pragma mark Runtime +/*! + * @function xpc_main + * The springboard into the XPCService runtime. This function will set up your + * service bundle's listener connection and manage it automatically. After this + * initial setup, this function will, by default, call dispatch_main(). You may + * override this behavior by setting the RunLoopType key in your XPC service + * bundle's Info.plist under the XPCService dictionary. + * + * @param handler + * The handler with which to accept new connections. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NORETURN XPC_NONNULL1 +void +xpc_main(xpc_connection_handler_t handler); + +#if XPC_HOSTING_OLD_MAIN +typedef void (*xpc_service_event_handler_t)(xpc_connection_t, xpc_object_t); + +__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_7, __IPHONE_5_0, __IPHONE_5_0) +XPC_EXPORT XPC_NORETURN XPC_NONNULL3 +void +xpc_service_main(int argc, const char *argv[], + xpc_service_event_handler_t handler); +#endif // XPC_HOSTING_OLD_MAIN + +#pragma mark Transactions +/*! + * @function xpc_transaction_begin + * Informs the XPC runtime that a transaction has begun and that the service + * should not exit due to inactivity. + * + * @discussion + * A service with no outstanding transactions may automatically exit due to + * inactivity as determined by the system. + * + * This function may be used to manually manage transactions in cases where + * their automatic management (as described below) does not meet the needs of an + * XPC service. This function also updates the transaction count used for sudden + * termination, i.e. vproc_transaction_begin(), and these two interfaces may be + * used in combination. + * + * The XPC runtime will automatically begin a transaction on behalf of a service + * when a new message is received. If no reply message is expected, the + * transaction is automatically ended when the connection event handler returns. + * If a reply message is created, the transaction will end when the reply + * message is sent or released. An XPC service may use xpc_transaction_begin() + * and xpc_transaction_end() to inform the XPC runtime about activity that + * occurs outside of this common pattern. + * + * On macOS, when the XPC runtime has determined that the service should exit, + * the event handlers for all active peer connections will receive + * {@link XPC_ERROR_TERMINATION_IMMINENT} as an indication that they should + * unwind their existing transactions. After this error is delivered to a + * connection's event handler, no more messages will be delivered to the + * connection. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +void +xpc_transaction_begin(void); + +/*! + * @function xpc_transaction_end + * Informs the XPC runtime that a transaction has ended. + * + * @discussion + * As described in {@link xpc_transaction_begin()}, this API may be used + * interchangeably with vproc_transaction_end(). + * + * See the discussion for {@link xpc_transaction_begin()} for details regarding + * the XPC runtime's idle-exit policy. + */ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT +void +xpc_transaction_end(void); + +#pragma mark XPC Event Stream +/*! + * @function xpc_set_event_stream_handler + * Sets the event handler to invoke when streamed events are received. + * + * @param stream + * The name of the event stream for which this handler will be invoked. + * + * @param targetq + * The GCD queue to which the event handler block will be submitted. This + * parameter may be NULL, in which case the connection's target queue will be + * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT. + * + * @param handler + * The event handler block. The event which this block receives as its first + * parameter will always be a dictionary which contains the XPC_EVENT_KEY_NAME + * key. The value for this key will be a string whose value is the name assigned + * to the XPC event specified in the launchd.plist. Future keys may be added to + * this dictionary. + * + * @discussion + * Multiple calls to this function for the same event stream will result in + * undefined behavior. + */ +#if __BLOCKS__ +__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0) +XPC_EXPORT XPC_NONNULL1 XPC_NONNULL3 +void +xpc_set_event_stream_handler(const char *stream, + dispatch_queue_t _Nullable targetq, xpc_handler_t handler); +#endif // __BLOCKS__ + +__END_DECLS +XPC_ASSUME_NONNULL_END + +#endif // __XPC_H__