diff --git a/include/xpc/activity.h b/include/xpc/activity.h index 5459960..2fb4dd8 100644 --- a/include/xpc/activity.h +++ b/include/xpc/activity.h @@ -1,444 +1,61 @@ +/** + * This file is part of Darling. + * + * Copyright (C) 2023 Darling developers + * + * Darling is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Darling is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Darling. If not, see . + */ + #ifndef __XPC_ACTIVITY_H__ #define __XPC_ACTIVITY_H__ #ifndef __XPC_INDIRECT__ -#error "Please #include instead of this file directly." -// For HeaderDoc. +#error "It's not recommended to directly include , please #include instead." +#endif + #include -#endif // __XPC_INDIRECT__ #ifdef __BLOCKS__ __BEGIN_DECLS -/* - * The following are a collection of keys and values used to set an activity's - * execution criteria. - */ - -/*! - * @constant XPC_ACTIVITY_INTERVAL - * An integer property indicating the desired time interval (in seconds) of the - * activity. The activity will not be run more than once per time interval. - * Due to the nature of XPC Activity finding an opportune time to run - * the activity, any two occurrences may be more or less than 'interval' - * seconds apart, but on average will be 'interval' seconds apart. - * The presence of this key implies the following, unless overridden: - * - XPC_ACTIVITY_REPEATING with a value of true - * - XPC_ACTIVITY_DELAY with a value of half the 'interval' - * The delay enforces a minimum distance between any two occurrences. - * - XPC_ACTIVITY_GRACE_PERIOD with a value of half the 'interval'. - * The grace period is the amount of time allowed to pass after the end of - * the interval before more aggressive scheduling occurs. The grace period - * does not increase the size of the interval. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_INTERVAL; - -/*! - * @constant XPC_ACTIVITY_REPEATING - * A boolean property indicating whether this is a repeating activity. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_REPEATING; - -/*! - * @constant XPC_ACTIVITY_DELAY - * An integer property indicating the number of seconds to delay before - * beginning the activity. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_DELAY; - -/*! - * @constant XPC_ACTIVITY_GRACE_PERIOD - * An integer property indicating the number of seconds to allow as a grace - * period before the scheduling of the activity becomes more aggressive. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_GRACE_PERIOD; - - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_1_MIN; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_5_MIN; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_15_MIN; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_30_MIN; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_1_HOUR; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_4_HOURS; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_8_HOURS; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_1_DAY; - -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const int64_t XPC_ACTIVITY_INTERVAL_7_DAYS; - -/*! - * @constant XPC_ACTIVITY_PRIORITY - * A string property indicating the priority of the activity. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_PRIORITY; - -/*! - * @constant XPC_ACTIVITY_PRIORITY_MAINTENANCE - * A string indicating activity is maintenance priority. - * Maintenance priority is intended for user-invisible maintenance tasks - * such as garbage collection or optimization. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_PRIORITY_MAINTENANCE; - -/*! - * @constant XPC_ACTIVITY_PRIORITY_UTILITY - * A string indicating activity is utility priority. - * Utility priority is intended for user-visible tasks such as fetching data - * from the network, copying files, or importing data. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_PRIORITY_UTILITY; - -/*! - * @constant XPC_ACTIVITY_ALLOW_BATTERY - * A Boolean value indicating whether the activity should be allowed to run - * while the computer is on battery power. The default value is false for - * maintenance priority activity and true for utility priority activity. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_ALLOW_BATTERY; - -/*! - * @constant XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP - * A Boolean value indicating whether the activity should only be performed - * while the primary screen is in sleep mode. Defaults to false. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_REQUIRE_SCREEN_SLEEP; // bool - -/*! - * @constant XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL - * An integer percentage of minimum battery charge required to allow the - * activity to run. A default minimum battery level is determined by the - * system. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_REQUIRE_BATTERY_LEVEL; // int (%) - -/*! - * @constant XPC_ACTIVITY_REQUIRE_HDD_SPINNING - * A Boolean value indicating whether the activity should only be performed - * while the hard disk drive (HDD) is spinning. Computers with flash storage - * are considered to be equivalent to HDD spinning. Defaults to false. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const char *XPC_ACTIVITY_REQUIRE_HDD_SPINNING; // bool - -XPC_EXPORT -const char *XPC_ACTIVITY_REQUIRE_NETWORK_CONNECTIVITY; // bool - -XPC_EXPORT -const char *XPC_ACTIVITY_REQUIRE_INEXPENSIVE_NETWORK_CONNECTIVITY; // bool - -XPC_EXPORT -const char *XPC_ACTIVITY_NETWORK_TRANSFER_DIRECTION; // char* - -XPC_EXPORT -const char* XPC_ACTIVITY_NETWORK_TRANSFER_DIRECTION_DOWNLOAD; - -XPC_EXPORT -const char* XPC_ACTIVITY_NETWORK_TRANSFER_DIRECTION_UPLOAD; - -/*! - * @define XPC_TYPE_ACTIVITY - * A type representing a connection to a named service. This connection is - * bidirectional and can be used to both send and receive messages. A - * connection carries the credentials of the remote service provider. - */ -#define XPC_TYPE_ACTIVITY (&_xpc_type_activity) -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -XPC_TYPE(_xpc_type_activity); - -/*! - * @typedef xpc_activity_t - * - * @abstract - * An XPC activity object. - * - * @discussion - * This object represents a set of execution criteria and a current execution - * state for background activity on the system. Once an activity is registered, - * the system will evaluate its criteria to determine whether the activity is - * eligible to run under current system conditions. When an activity becomes - * eligible to run, its execution state will be updated and an invocation of - * its handler block will be made. - */ -XPC_IGNORE_DUPLICATE_PROTOCOL_PUSH; XPC_DECL(xpc_activity); -XPC_IGNORE_DUPLICATE_PROTOCOL_POP; +XPC_EXPORT XPC_TYPE(_xpc_type_activity); +#define XPC_TYPE_ACTIVITY (&_xpc_type_activity) -/*! - * @typedef xpc_activity_handler_t - * - * @abstract - * A block that is called when an XPC activity becomes eligible to run. - */ -typedef void (^xpc_activity_handler_t)(xpc_activity_t activity); - -/*! - * @constant XPC_ACTIVITY_CHECK_IN - * This constant may be passed to xpc_activity_register() as the criteria - * dictionary in order to check in with the system for previously registered - * activity using the same identifier (for example, an activity taken from a - * launchd property list). - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -const xpc_object_t XPC_ACTIVITY_CHECK_IN; - -/*! - * @function xpc_activity_register - * - * @abstract - * Registers an activity with the system. - * - * @discussion - * Registers a new activity with the system. The criteria of the activity are - * described by the dictionary passed to this function. If an activity with the - * same identifier already exists, the criteria provided override the existing - * criteria unless the special dictionary XPC_ACTIVITY_CHECK_IN is used. The - * XPC_ACTIVITY_CHECK_IN dictionary instructs the system to first look up an - * existing activity without modifying its criteria. Once the existing activity - * is found (or a new one is created with an empty set of criteria) the handler - * will be called with an activity object in the XPC_ACTIVITY_STATE_CHECK_IN - * state. - * - * @param identifier - * A unique identifier for the activity. Each application has its own namespace. - * 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_object_t -xpc_activity_copy_criteria(xpc_activity_t activity); - -/*! - * @function xpc_activity_set_criteria - * - * @abstract - * Modifies the execution criteria of an activity. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 -void -xpc_activity_set_criteria(xpc_activity_t activity, xpc_object_t criteria); - -/*! - * @enum xpc_activity_state_t - * An activity is defined to be in one of the following states. Applications - * may check the current state of the activity using xpc_activity_get_state() - * in the handler block provided to xpc_activity_register(). - * - * The application can modify the state of the activity by calling - * xpc_activity_set_state() with one of the following: - * - XPC_ACTIVITY_STATE_DEFER - * - XPC_ACTIVITY_STATE_CONTINUE - * - XPC_ACTIVITY_STATE_DONE - * - * @constant XPC_ACTIVITY_STATE_CHECK_IN - * An activity in this state has just completed a checkin with the system after - * XPC_ACTIVITY_CHECK_IN was provided as the criteria dictionary to - * xpc_activity_register. The state gives the application an opportunity to - * inspect and modify the activity's criteria. - * - * @constant XPC_ACTIVITY_STATE_WAIT - * An activity in this state is waiting for an opportunity to run. This value - * is never returned within the activity's handler block, as the block is - * invoked in response to XPC_ACTIVITY_STATE_CHECK_IN or XPC_ACTIVITY_STATE_RUN. - * - * Note: - * A launchd job may idle exit while an activity is in the wait state and be - * relaunched in response to the activity becoming runnable. The launchd job - * simply needs to re-register for the activity on its next launch by passing - * XPC_ACTIVITY_STATE_CHECK_IN to xpc_activity_register(). - * - * @constant XPC_ACTIVITY_STATE_RUN - * An activity in this state is eligible to run based on its criteria. - * - * @constant XPC_ACTIVITY_STATE_DEFER - * An application may pass this value to xpc_activity_set_state() to indicate - * that the activity should be deferred (placed back into the WAIT state) until - * a time when its criteria are met again. Deferring an activity does not reset - * any of its time-based criteria (in other words, it will remain past due). - * - * 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, + XPC_ACTIVITY_STATE_RUN = 2 }; 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); +typedef void (^xpc_activity_handler_t)(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); +XPC_EXPORT const char * XPC_ACTIVITY_ALLOW_BATTERY; +XPC_EXPORT const xpc_object_t XPC_ACTIVITY_CHECK_IN; +XPC_EXPORT const char * XPC_ACTIVITY_DELAY; +XPC_EXPORT const char * XPC_ACTIVITY_GRACE_PERIOD; +XPC_EXPORT const char * XPC_ACTIVITY_PRIORITY; +XPC_EXPORT const char * XPC_ACTIVITY_PRIORITY_MAINTENANCE; +XPC_EXPORT const char * XPC_ACTIVITY_REPEATING; -/*! - * @function xpc_activity_should_defer - * - * @abstract - * Test whether an activity should be deferred. - * - * @discussion - * This function may be used to test whether the criteria of a long-running - * activity are still satisfied. If not, the system indicates that the - * application should defer the activity. The application may acknowledge the - * deferral by calling xpc_activity_set_state() with XPC_ACTIVITY_STATE_DEFER. - * Once deferred, the system will place the activity back into the WAIT state - * and re-invoke the handler block at the earliest opportunity when the criteria - * are once again satisfied. - * - * @return - * Returns true if the activity should be deferred. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT -bool -xpc_activity_should_defer(xpc_activity_t activity); - -/*! - * @function xpc_activity_unregister - * - * @abstract - * Unregisters an activity found by its identifier. - * - * @discussion - * A dynamically registered activity will be deleted in response to this call. - * Statically registered activity (from a launchd property list) will be - * reverted to its original criteria if any modifications were made. - * - * Unregistering an activity has no effect on any outstanding xpc_activity_t - * objects or any currently executing xpc_activity_handler_t blocks; however, - * no new handler block invocations will be made after it is unregistered. - * - * @param identifier - * The identifier of the activity to unregister. - */ -__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0) -XPC_EXPORT XPC_NONNULL1 -void -xpc_activity_unregister(const char *identifier); +xpc_activity_state_t xpc_activity_get_state(xpc_activity_t activity); +void xpc_activity_register(const char *identifier, xpc_object_t criteria, xpc_activity_handler_t handler); +void xpc_activity_unregister(const char *identifier); __END_DECLS -#endif // __BLOCKS__ +#endif #endif // __XPC_ACTIVITY_H__ diff --git a/include/xpc/connection.h b/include/xpc/connection.h index 0fa4d3e..63f67da 100644 --- a/include/xpc/connection.h +++ b/include/xpc/connection.h @@ -1,722 +1,66 @@ +/** + * This file is part of Darling. + * + * Copyright (C) 2023 Darling developers + * + * Darling is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Darling is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Darling. If not, see . + */ + + #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__ +#error "It's not recommended to directly include , please #include instead." +#endif -#ifndef __BLOCKS__ -#error "XPC connections require Blocks support." -#endif // __BLOCKS__ +#include __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 - * 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. - */ +XPC_EXPORT const struct _xpc_dictionary_s _xpc_error_connection_interrupted; +XPC_EXPORT const struct _xpc_dictionary_s _xpc_error_connection_invalid; +XPC_EXPORT const struct _xpc_dictionary_s _xpc_error_termination_imminent; + +#define XPC_ERROR_CONNECTION_INTERRUPTED XPC_GLOBAL_OBJECT(_xpc_error_connection_interrupted) +#define XPC_ERROR_CONNECTION_INVALID XPC_GLOBAL_OBJECT(_xpc_error_connection_invalid) +#define XPC_ERROR_TERMINATION_IMMINENT XPC_GLOBAL_OBJECT(_xpc_error_termination_imminent) + typedef void (*xpc_finalizer_t)(void *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 first call to xpc_connection_resume(). - * - * XPC connections, like dispatch sources, are returned in a suspended state, so - * you must call {@link xpc_connection_resume()} in order to begin receiving - * events from the connection. Also like dispatch sources, connections must be - * resumed in order to be safely released. It is a programming error to release - * a 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 *name, dispatch_queue_t 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 - * first call to {@link xpc_connection_resume()}. - */ -__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 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 resuming 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 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 resume 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_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. Connections start in a suspended state, so you must - * call xpc_connection_resume() on a connection before it will send or receive - * any messages. - * - * @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() after the initial call to xpc_connection_resume(). - * After the initial resume of the connection, calling xpc_connection_resume() - * more times than xpc_connection_suspend() has been called is 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 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 * -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 *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 * -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 finalizer); - -void -xpc_connection_set_legacy(xpc_connection_t connection); - -void -xpc_connection_set_privileged(xpc_connection_t connection); - -void -xpc_connection_activate(xpc_connection_t connection); +void xpc_connection_activate(xpc_connection_t connection); +void xpc_connection_cancel(xpc_connection_t connection); +xpc_connection_t xpc_connection_create(const char *name, dispatch_queue_t targetq); +xpc_connection_t xpc_connection_create_from_endpoint(xpc_endpoint_t endpoint); +xpc_connection_t xpc_connection_create_mach_service(const char *name, dispatch_queue_t targetq, uint64_t flags); +au_asid_t xpc_connection_get_asid(xpc_connection_t connection); +gid_t xpc_connection_get_egid(xpc_connection_t connection); +uid_t xpc_connection_get_euid(xpc_connection_t connection); +const char * xpc_connection_get_name(xpc_connection_t connection); +pid_t xpc_connection_get_pid(xpc_connection_t connection); +void xpc_connection_resume(xpc_connection_t connection); +void xpc_connection_send_message(xpc_connection_t connection, xpc_object_t message); +void xpc_connection_send_message_with_reply(xpc_connection_t connection, xpc_object_t message, dispatch_queue_t replyq, xpc_handler_t handler); +xpc_object_t xpc_connection_send_message_with_reply_sync(xpc_connection_t connection, xpc_object_t message); +void xpc_connection_set_context(xpc_connection_t connection, void *context); +void xpc_connection_set_event_handler(xpc_connection_t connection, xpc_handler_t handler); +void xpc_connection_set_finalizer_f(xpc_connection_t connection, xpc_finalizer_t finalizer); +void xpc_connection_set_target_queue(xpc_connection_t connection, dispatch_queue_t targetq); +void xpc_connection_suspend(xpc_connection_t connection); __END_DECLS diff --git a/include/xpc/debug.h b/include/xpc/debug.h index b50361c..bba2954 100644 --- a/include/xpc/debug.h +++ b/include/xpc/debug.h @@ -1,23 +1,25 @@ +/** + * This file is part of Darling. + * + * Copyright (C) 2023 Darling developers + * + * Darling is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Darling is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Darling. If not, see . + */ + #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); +const char * xpc_debugger_api_misuse_info(void); #endif // __XPC_DEBUG_H__ diff --git a/include/xpc/endpoint.h b/include/xpc/endpoint.h index b4bac81..edc68b3 100644 --- a/include/xpc/endpoint.h +++ b/include/xpc/endpoint.h @@ -1,22 +1,25 @@ +/** + * This file is part of Darling. + * + * Copyright (C) 2023 Darling developers + * + * Darling is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Darling is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Darling. If not, see . + */ + #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 -xpc_endpoint_create(xpc_connection_t connection); +xpc_endpoint_t xpc_endpoint_create(xpc_connection_t connection); #endif // __XPC_ENDPOINT_H__ diff --git a/include/xpc/xpc.h b/include/xpc/xpc.h index b79e364..96bc1c0 100644 --- a/include/xpc/xpc.h +++ b/include/xpc/xpc.h @@ -1,2575 +1,201 @@ -// Copyright (c) 2009-2011 Apple Inc. All rights reserved. +/** + * This file is part of Darling. + * + * Copyright (C) 2023 Darling developers + * + * Darling is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Darling is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Darling. If not, see . + */ #ifndef __XPC_H__ #define __XPC_H__ -#include #include +#include -#include -#include #include -#include #include #include -#include #include +#include #include -#include -#include +#include + +#define __XPC_INDIRECT__ +#include __BEGIN_DECLS -#ifndef __OSX_AVAILABLE_STARTING -#define __OSX_AVAILABLE_STARTING(x, y) -#endif // __OSX_AVAILABLE_STARTING - -#ifndef __XPC_INDIRECT__ -#define __XPC_INDIRECT__ -#endif // __XPC_INDIRECT__ - -#include - -#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. - */ -XPC_IGNORE_DUPLICATE_PROTOCOL_PUSH; -OS_OBJECT_DECL(xpc_object); -XPC_IGNORE_DUPLICATE_PROTOCOL_POP; -#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; -#undef XPC_DECL -#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; - -#define XPC_TYPE_POINTER (&_xpc_type_pointer) -XPC_EXPORT -XPC_TYPE(_xpc_type_pointer); - -#ifndef __XPC_BUILDING_XPC__ -#include -#include -#if __BLOCKS__ -#include -#include -#endif // __BLOCKS__ -#undef __XPC_INDIRECT__ -#include -#endif // __XPC_BUILDING_XPC__ - -#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 -#define xpc_release_safe(object) do { \ - if (object) { \ - xpc_release(object); \ - object = NULL; \ - } \ - } while (0); - -/*! - * @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 -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 *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 * -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 * -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_object_t -xpc_uuid_create(const uuid_t 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 * -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 -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 **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 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 *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_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); +typedef const struct _xpc_type_s *xpc_type_t; +#ifndef __XPC_BUILDING_XPC__ +#define XPC_TYPE(type) const struct _xpc_type_s type +#endif -/*! - * @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); +#if OS_OBJECT_USE_OBJC +OS_OBJECT_DECL(xpc_object); +#ifndef XPC_DECL +#define XPC_DECL(name) typedef xpc_object_t name##_t +#endif +#define XPC_GLOBAL_OBJECT(object) ((OS_OBJECT_BRIDGE xpc_object_t)&(object)) +#define XPC_RETURNS_RETAINED +#else +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 -/*! - * @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 -void -xpc_array_set_uuid(xpc_object_t xarray, size_t index, const uuid_t 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 -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 * -xpc_array_get_data(xpc_object_t xarray, size_t index, size_t *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 * -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 * -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 -xpc_array_create_connection(xpc_object_t xarray, size_t index); - -XPC_EXPORT -void* _Nullable -xpc_array_get_pointer(xpc_object_t xarray, size_t index); - -XPC_EXPORT -void -xpc_array_set_pointer(xpc_object_t xarray, size_t index, void* value); - -#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_array_applier_t)(size_t index, xpc_object_t _Nonnull value); +typedef void (^xpc_handler_t)(xpc_object_t object); typedef bool (^xpc_dictionary_applier_t)(const char *key, xpc_object_t 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. - * If any element of this array is NULL, the behavior is undefined. - * - * @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 * const *keys, const xpc_object_t *values, - size_t count); +XPC_EXPORT XPC_TYPE(_xpc_type_array); +XPC_EXPORT XPC_TYPE(_xpc_type_bool); +XPC_EXPORT XPC_TYPE(_xpc_type_connection); +XPC_EXPORT XPC_TYPE(_xpc_type_data); +XPC_EXPORT XPC_TYPE(_xpc_type_date); +XPC_EXPORT XPC_TYPE(_xpc_type_dictionary); +XPC_EXPORT XPC_TYPE(_xpc_type_double); +XPC_EXPORT XPC_TYPE(_xpc_type_endpoint); +XPC_EXPORT XPC_TYPE(_xpc_type_error); +XPC_EXPORT XPC_TYPE(_xpc_type_fd); +XPC_EXPORT XPC_TYPE(_xpc_type_int64); +XPC_EXPORT XPC_TYPE(_xpc_type_null); +XPC_EXPORT XPC_TYPE(_xpc_type_pointer); +XPC_EXPORT XPC_TYPE(_xpc_type_shmem); +XPC_EXPORT XPC_TYPE(_xpc_type_string); +XPC_EXPORT XPC_TYPE(_xpc_type_uint64); +XPC_EXPORT XPC_TYPE(_xpc_type_uuid); -/*! - * @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 -xpc_dictionary_create_reply(xpc_object_t original); +XPC_DECL(xpc_connection); +XPC_DECL(xpc_endpoint); -/*! - * @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 value); +#define XPC_TYPE_ARRAY (&_xpc_type_array) +#define XPC_TYPE_BOOL (&_xpc_type_bool) +#define XPC_TYPE_CONNECTION (&_xpc_type_connection) +#define XPC_TYPE_DATA (&_xpc_type_data) +#define XPC_TYPE_DATE (&_xpc_type_date) +#define XPC_TYPE_DICTIONARY (&_xpc_type_dictionary) +#define XPC_TYPE_DOUBLE (&_xpc_type_double) +#define XPC_TYPE_ENDPOINT (&_xpc_type_endpoint) +#define XPC_TYPE_ERROR (&_xpc_type_error) +#define XPC_TYPE_FD (&_xpc_type_fd) +#define XPC_TYPE_INT64 (&_xpc_type_int64) +#define XPC_TYPE_NULL (&_xpc_type_null) +#define XPC_TYPE_POINTER (&_xpc_type_pointer) +#define XPC_TYPE_SHMEM (&_xpc_type_shmem) +#define XPC_TYPE_STRING (&_xpc_type_string) +#define XPC_TYPE_UINT64 (&_xpc_type_uint64) +#define XPC_TYPE_UUID (&_xpc_type_uuid) -/*! - * @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 -xpc_dictionary_get_value(xpc_object_t xdict, const char *key); +#define XPC_BOOL_TRUE XPC_GLOBAL_OBJECT(_xpc_bool_true) +#define XPC_ERROR_KEY_DESCRIPTION _xpc_error_key_description -/*! - * @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); +XPC_EXPORT const struct _xpc_bool_s _xpc_bool_true; +XPC_EXPORT const char * const _xpc_error_key_description; -/*! - * @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_dictionary_applier_t applier); -#endif // __BLOCKS__ +typedef void (*xpc_connection_handler_t)(xpc_connection_t connection); -/*! - * @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 -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 -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 -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 -void -xpc_dictionary_set_uuid(xpc_object_t xdict, const char *key, const uuid_t 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 -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 * -xpc_dictionary_get_data(xpc_object_t xdict, const char *key, size_t *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 * -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 * -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 -xpc_dictionary_create_connection(xpc_object_t xdict, const char *key); - -__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 xdict, const char *key); - -XPC_EXPORT -void* _Nullable -xpc_dictionary_get_pointer(xpc_object_t xdict, const char* key); - -XPC_EXPORT -void -xpc_dictionary_set_pointer(xpc_object_t xdict, const char* key, void* value); - -#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. - * - * 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 !defined(__XPC_BUILDING_XPC__) || !__XPC_BUILDING_XPC__ +#include #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 targetq, - xpc_handler_t handler); -#endif // __BLOCKS__ +#include +#include +#endif +#undef __XPC_INDIRECT__ +#include +#endif -#pragma mark XPC Pointer +xpc_object_t xpc_array_create(xpc_object_t _Nonnull const *objects, size_t count); +xpc_object_t xpc_bool_create(bool value); +xpc_object_t xpc_data_create(const void *bytes, size_t length); +xpc_object_t xpc_date_create(int64_t interval); +xpc_object_t xpc_dictionary_create(const char *const _Nonnull *keys, xpc_object_t _Nullable const *values, size_t count); +xpc_object_t xpc_double_create(double value); +xpc_object_t xpc_fd_create(int fd); +xpc_object_t xpc_int64_create(int64_t value); +xpc_object_t xpc_null_create(void); +xpc_object_t xpc_pointer_create(void* value); +xpc_object_t xpc_string_create(const char *string); +xpc_object_t xpc_string_create_with_format_and_arguments(const char *fmt, va_list ap); +xpc_object_t xpc_uint64_create(uint64_t value); +xpc_object_t xpc_uuid_create(const unsigned char *uuid); -XPC_EXPORT -xpc_object_t -xpc_pointer_create(void* value); +int64_t xpc_date_get_value(xpc_object_t xdate); +bool xpc_bool_get_value(xpc_object_t xbool); +double xpc_double_get_value(xpc_object_t xdouble); +int64_t xpc_int64_get_value(xpc_object_t xint); +void* _Nullable xpc_pointer_get_value(xpc_object_t xptr); +const char * xpc_string_get_string_ptr(xpc_object_t xstring); +uint64_t xpc_uint64_get_value(xpc_object_t xuint); +const uint8_t * xpc_uuid_get_bytes(xpc_object_t xuuid); -XPC_EXPORT -void* _Nullable -xpc_pointer_get_value(xpc_object_t xptr); +xpc_object_t xpc_data_create_with_dispatch_data(dispatch_data_t ddata); +size_t xpc_data_get_bytes(xpc_object_t xdata, void *buffer, size_t off, size_t length); +const void * xpc_data_get_bytes_ptr(xpc_object_t xdata); +size_t xpc_data_get_length(xpc_object_t xdata); + +void xpc_array_append_value(xpc_object_t xarray, xpc_object_t value); +bool xpc_array_apply(xpc_object_t xarray, xpc_array_applier_t applier); +size_t xpc_array_get_count(xpc_object_t xarray); +const void * xpc_array_get_data(xpc_object_t xarray, size_t index, size_t *length); +void* _Nullable xpc_array_get_pointer(xpc_object_t xarray, size_t index); +const char * xpc_array_get_string(xpc_object_t xarray, size_t index); +uint64_t xpc_array_get_uint64(xpc_object_t xarray, size_t index); +const uint8_t * xpc_array_get_uuid(xpc_object_t xarray, size_t index); +xpc_object_t xpc_array_get_value(xpc_object_t xarray, size_t index); +void xpc_array_set_data(xpc_object_t xarray, size_t index, const void *bytes, size_t length); +void xpc_array_set_pointer(xpc_object_t xarray, size_t index, void* value); +void xpc_array_set_string(xpc_object_t xarray, size_t index, const char *string); +void xpc_array_set_uint64(xpc_object_t xarray, size_t index, uint64_t value); +void xpc_array_set_value(xpc_object_t xarray, size_t index, xpc_object_t value); + +bool xpc_dictionary_apply(xpc_object_t xdict, xpc_dictionary_applier_t applier); +xpc_object_t xpc_dictionary_create_reply(xpc_object_t original); +int xpc_dictionary_dup_fd(xpc_object_t xdict, const char *key); +bool xpc_dictionary_get_bool(xpc_object_t xdict, const char *key); +size_t xpc_dictionary_get_count(xpc_object_t xdict); +const void * xpc_dictionary_get_data(xpc_object_t xdict, const char *key, size_t *length); +xpc_object_t xpc_dictionary_get_dictionary(xpc_object_t xdict, const char *key); +double xpc_dictionary_get_double(xpc_object_t xdict, const char *key); +int64_t xpc_dictionary_get_int64(xpc_object_t xdict, const char *key); +xpc_connection_t xpc_dictionary_get_remote_connection(xpc_object_t xdict); +const char * xpc_dictionary_get_string(xpc_object_t xdict, const char *key); +uint64_t xpc_dictionary_get_uint64(xpc_object_t xdict, const char *key); +const uint8_t * xpc_dictionary_get_uuid(xpc_object_t xdict, const char *key); +xpc_object_t xpc_dictionary_get_value(xpc_object_t xdict, const char *key); +void xpc_dictionary_set_bool(xpc_object_t xdict, const char *key, bool value); +void xpc_dictionary_set_data(xpc_object_t xdict, const char *key, const void *bytes, size_t length); +void xpc_dictionary_set_double(xpc_object_t xdict, const char *key, double value); +void xpc_dictionary_set_fd(xpc_object_t xdict, const char *key, int fd); +void xpc_dictionary_set_int64(xpc_object_t xdict, const char *key, int64_t value); +void xpc_dictionary_set_string(xpc_object_t xdict, const char *key, const char *string); +void xpc_dictionary_set_uint64(xpc_object_t xdict, const char *key, uint64_t value); +void xpc_dictionary_set_uuid(xpc_object_t xdict, const char *key, const unsigned char *uuid); +void xpc_dictionary_set_value(xpc_object_t xdict, const char *key, xpc_object_t value); + +char * xpc_copy_description(xpc_object_t object); +bool xpc_equal(xpc_object_t object1, xpc_object_t object2); +int xpc_fd_dup(xpc_object_t xfd); +xpc_type_t xpc_get_type(xpc_object_t object); +size_t xpc_hash(xpc_object_t object); +void xpc_main(xpc_connection_handler_t handler); +void xpc_release(xpc_object_t object); +xpc_object_t xpc_retain(xpc_object_t object); +void xpc_transaction_begin(void); +void xpc_transaction_end(void); __END_DECLS