1#ifndef __XPC_CONNECTION_H__
2#define __XPC_CONNECTION_H__
3
4#ifndef __XPC_INDIRECT__
5#error "Please #include <xpc/xpc.h> instead of this file directly."
6// For HeaderDoc.
7#include <xpc/base.h>
8#endif // __XPC_INDIRECT__
9
10#ifndef __BLOCKS__
11#error "XPC connections require Blocks support."
12#endif // __BLOCKS__
13
14XPC_ASSUME_NONNULL_BEGIN
15__BEGIN_DECLS
16
17/*!
18 * @constant XPC_ERROR_CONNECTION_INTERRUPTED
19 * Will be delivered to the connection's event handler if the remote service
20 * exited. The connection is still live even in this case, and resending a
21 * message will cause the service to be launched on-demand. This error serves
22 * as a client's indication that it should resynchronize any state that it had
23 * given the service.
24 *
25 * Any messages in the queue to be sent will be unwound and canceled when this
26 * error occurs. In the case where a message waiting to be sent has a reply
27 * handler, that handler will be invoked with this error. In the context of the
28 * reply handler, this error indicates that a reply to the message will never
29 * arrive.
30 *
31 * Messages that do not have reply handlers associated with them will be
32 * silently disposed of. This error will only be given to peer connections.
33 */
34#define XPC_ERROR_CONNECTION_INTERRUPTED \
35 XPC_GLOBAL_OBJECT(_xpc_error_connection_interrupted)
36__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
37XPC_EXPORT
38const struct _xpc_dictionary_s _xpc_error_connection_interrupted;
39
40/*!
41 * @constant XPC_ERROR_CONNECTION_INVALID
42 * Will be delivered to the connection's event handler if the named service
43 * provided to xpc_connection_create() could not be found in the XPC service
44 * namespace. The connection is useless and should be disposed of.
45 *
46 * Any messages in the queue to be sent will be unwound and canceled when this
47 * error occurs, similarly to the behavior when XPC_ERROR_CONNECTION_INTERRUPTED
48 * occurs. The only difference is that the XPC_ERROR_CONNECTION_INVALID will be
49 * given to outstanding reply handlers and the connection's event handler.
50 *
51 * This error may be given to any type of connection.
52 */
53#define XPC_ERROR_CONNECTION_INVALID \
54 XPC_GLOBAL_OBJECT(_xpc_error_connection_invalid)
55__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
56XPC_EXPORT
57const struct _xpc_dictionary_s _xpc_error_connection_invalid;
58
59/*!
60 * @constant XPC_ERROR_TERMINATION_IMMINENT
61 * On macOS, this error will be delivered to a peer connection's event handler
62 * when the XPC runtime has determined that the program should exit and that
63 * all outstanding transactions must be wound down, and no new transactions can
64 * be opened.
65 *
66 * After this error has been delivered to the event handler, no more messages
67 * will be received by the connection. The runtime will still attempt to deliver
68 * outgoing messages, but this error should be treated as an indication that
69 * the program will exit very soon, and any outstanding business over the
70 * connection should be wrapped up as quickly as possible and the connection
71 * canceled shortly thereafter.
72 *
73 * This error will only be delivered to peer connections received through a
74 * listener or the xpc_main() event handler.
75 */
76#define XPC_ERROR_TERMINATION_IMMINENT \
77 XPC_GLOBAL_OBJECT(_xpc_error_termination_imminent)
78__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
79XPC_EXPORT
80const struct _xpc_dictionary_s _xpc_error_termination_imminent;
81
82/*!
83 * @constant XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT
84 * On macOS, this error will be delivered to a peer connection's event handler
85 * when the XPC runtime has detected that a peer connection does not
86 * satisfy the code signing requirement specified for the connection.
87 *
88 * See {@link xpc_connection_set_peer_code_signing_requirement}
89 */
90#define XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT \
91 XPC_GLOBAL_OBJECT(_xpc_error_peer_code_signing_requirement)
92__API_AVAILABLE(macos(12.0), macCatalyst(15.0))
93XPC_EXPORT
94const struct _xpc_dictionary_s _xpc_error_peer_code_signing_requirement;
95
96/*!
97 * @constant XPC_CONNECTION_MACH_SERVICE_LISTENER
98 * Passed to xpc_connection_create_mach_service(). This flag indicates that the
99 * caller is the listener for the named service. This flag may only be passed
100 * for services which are advertised in the process' launchd.plist(5). You may
101 * not use this flag to dynamically add services to the Mach bootstrap
102 * namespace.
103 */
104#define XPC_CONNECTION_MACH_SERVICE_LISTENER (1 << 0)
105
106/*!
107 * @constant XPC_CONNECTION_MACH_SERVICE_PRIVILEGED
108 * Passed to xpc_connection_create_mach_service(). This flag indicates that the
109 * job advertising the service name in its launchd.plist(5) should be in the
110 * privileged Mach bootstrap. This is typically accomplished by placing your
111 * launchd.plist(5) in /Library/LaunchDaemons. If specified alongside the
112 * XPC_CONNECTION_MACH_SERVICE_LISTENER flag, this flag is a no-op.
113 */
114#define XPC_CONNECTION_MACH_SERVICE_PRIVILEGED (1 << 1)
115
116/*!
117 * @typedef xpc_finalizer_f
118 * A function that is invoked when a connection is being torn down and its
119 * context needs to be freed. The sole argument is the value that was given to
120 * {@link xpc_connection_set_context} or NULL if no context has been set. It is
121 * not safe to reference the connection from within this function.
122 *
123 * @param value
124 * The context object that is to be disposed of.
125 */
126typedef void (*xpc_finalizer_t)(void * _Nullable value);
127
128/*!
129 * @function xpc_connection_create
130 * Creates a new connection object.
131 *
132 * @param name
133 * If non-NULL, the name of the service with which to connect. The returned
134 * connection will be a peer.
135 *
136 * If NULL, an anonymous listener connection will be created. You can embed the
137 * ability to create new peer connections in an endpoint, which can be inserted
138 * into a message and sent to another process.
139 *
140 * @param targetq
141 * The GCD queue to which the event handler block will be submitted. This
142 * parameter may be NULL, in which case the connection's target queue will be
143 * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
144 * The target queue may be changed prior to the connection being activated with
145 * a call to xpc_connection_set_target_queue().
146 *
147 * @result
148 * A new connection object. The caller is responsible for disposing of the
149 * returned object with {@link xpc_release} when it is no longer needed.
150 *
151 * @discussion
152 * This method will succeed even if the named service does not exist. This is
153 * because the XPC namespace is not queried for the service name until the
154 * connection has been activated. See {@link xpc_connection_activate()}.
155 *
156 * XPC connections, like dispatch sources, are returned in an inactive state, so
157 * you must call {@link xpc_connection_activate()} in order to begin receiving
158 * events from the connection. Also like dispatch sources, connections must be
159 * activated and not suspended in order to be safely released. It is
160 * a programming error to release an inactive or suspended connection.
161 */
162__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
163XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT
164xpc_connection_t
165xpc_connection_create(const char * _Nullable name,
166 dispatch_queue_t _Nullable targetq);
167
168/*!
169 * @function xpc_connection_create_mach_service
170 * Creates a new connection object representing a Mach service.
171 *
172 * @param name
173 * The name of the remote service with which to connect. The service name must
174 * exist in a Mach bootstrap that is accessible to the process and be advertised
175 * in a launchd.plist.
176 *
177 * @param targetq
178 * The GCD queue to which the event handler block will be submitted. This
179 * parameter may be NULL, in which case the connection's target queue will be
180 * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
181 * The target queue may be changed prior to the connection being activated with
182 * a call to xpc_connection_set_target_queue().
183 *
184 * @param flags
185 * Additional attributes with which to create the connection.
186 *
187 * @result
188 * A new connection object.
189 *
190 * @discussion
191 * If the XPC_CONNECTION_MACH_SERVICE_LISTENER flag is given to this method,
192 * then the connection returned will be a listener connection. Otherwise, a peer
193 * connection will be returned. See the documentation for
194 * {@link xpc_connection_set_event_handler()} for the semantics of listener
195 * connections versus peer connections.
196 *
197 * This method will succeed even if the named service does not exist. This is
198 * because the Mach namespace is not queried for the service name until the
199 * connection has been activated. See {@link xpc_connection_activate()}.
200 */
201API_AVAILABLE(macos(10.7), macCatalyst(5.0))
202API_UNAVAILABLE(ios, tvos, watchos)
203XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL1
204xpc_connection_t
205xpc_connection_create_mach_service(const char *name,
206 dispatch_queue_t _Nullable targetq, uint64_t flags);
207
208/*!
209 * @function xpc_connection_create_from_endpoint
210 * Creates a new connection from the given endpoint.
211 *
212 * @param endpoint
213 * The endpoint from which to create the new connection.
214 *
215 * @result
216 * A new peer connection to the listener represented by the given endpoint.
217 *
218 * The same responsibilities of setting an event handler and activating the
219 * connection after calling xpc_connection_create() apply to the connection
220 * returned by this API. Since the connection yielded by this API is not
221 * associated with a name (and therefore is not rediscoverable), this connection
222 * will receive XPC_ERROR_CONNECTION_INVALID if the listening side crashes,
223 * exits or cancels the listener connection.
224 */
225__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
226XPC_EXPORT XPC_MALLOC XPC_RETURNS_RETAINED XPC_WARN_RESULT XPC_NONNULL_ALL
227xpc_connection_t
228xpc_connection_create_from_endpoint(xpc_endpoint_t endpoint);
229
230/*!
231 * @function xpc_connection_set_target_queue
232 * Sets the target queue of the given connection.
233 *
234 * @param connection
235 * The connection object which is to be manipulated.
236 *
237 * @param targetq
238 * The GCD queue to which the event handler block will be submitted. This
239 * parameter may be NULL, in which case the connection's target queue will be
240 * libdispatch's default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
241 *
242 * @discussion
243 * Once a connection is activated, this method may no longer be called and the
244 * target queue may no longer be updated.
245 *
246 * Even if the target queue is a concurrent queue, XPC still guarantees that
247 * there will never be more than one invocation of the connection's event
248 * handler block executing concurrently. If you wish to process events
249 * concurrently, you can dispatch_async(3) to a concurrent queue from within
250 * the event handler.
251 *
252 * IMPORTANT: When called from within the event handler block,
253 * dispatch_get_current_queue(3) is NOT guaranteed to return a pointer to the
254 * queue set with this method.
255 *
256 * Despite this seeming inconsistency, the XPC runtime guarantees that, when the
257 * target queue is a serial queue, the event handler block will execute
258 * synchronously with respect to other blocks submitted to that same queue. When
259 * the target queue is a concurrent queue, the event handler block may run
260 * concurrently with other blocks submitted to that queue, but it will never run
261 * concurrently with other invocations of itself for the same connection, as
262 * discussed previously.
263 */
264__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
265XPC_EXPORT XPC_NONNULL1
266void
267xpc_connection_set_target_queue(xpc_connection_t connection,
268 dispatch_queue_t _Nullable targetq);
269
270/*!
271 * @function xpc_connection_set_event_handler
272 * Sets the event handler block for the connection.
273 *
274 * @param connection
275 * The connection object which is to be manipulated.
276 *
277 * @param handler
278 * The event handler block.
279 *
280 * @discussion
281 * Setting the event handler is asynchronous and non-preemptive, and therefore
282 * this method will not interrupt the execution of an already-running event
283 * handler block. If the event handler is executing at the time of this call, it
284 * will finish, and then the connection's event handler will be changed before
285 * the next invocation of the event handler. The XPC runtime guarantees this
286 * non-preemptiveness even for concurrent target queues.
287 *
288 * Connection event handlers are non-reentrant, so it is safe to call
289 * xpc_connection_set_event_handler() from within the event handler block.
290 *
291 * The event handler's execution should be treated as a barrier to all
292 * connection activity. When it is executing, the connection will not attempt to
293 * send or receive messages, including reply messages. Thus, it is not safe to
294 * call xpc_connection_send_message_with_reply_sync() on the connection from
295 * within the event handler.
296 *
297 * You do not hold a reference on the object received as the event handler's
298 * only argument. Regardless of the type of object received, it is safe to call
299 * xpc_retain() on the object to obtain a reference to it.
300 *
301 * A connection may receive different events depending upon whether it is a
302 * listener or not. Any connection may receive an error in its event handler.
303 * But while normal connections may receive messages in addition to errors,
304 * listener connections will receive connections and not messages.
305 *
306 * Connections received by listeners are equivalent to those returned by
307 * xpc_connection_create() with a non-NULL name argument and a NULL targetq
308 * argument with the exception that you do not hold a reference on them.
309 * You must set an event handler and activate the connection. If you do not wish
310 * to accept the connection, you may simply call xpc_connection_cancel() on it
311 * and return. The runtime will dispose of it for you.
312 *
313 * IMPORTANT: For peer connections received through a listener connection's
314 * event handler, you MUST either accept the connection by setting an event
315 * handler with xpc_connection_set_event_handler() and calling
316 * xpc_connection_resume(), or reject the connection by calling
317 * xpc_connection_cancel(). Failure to take one of these actions will result
318 * in the connection remaining in an undefined state, potentially causing
319 * resource leaks or preventing proper transaction cleanup. This requirement
320 * applies to all listener connections, including those created with
321 * xpc_connection_create_mach_service() and those managed automatically by
322 * xpc_main().
323 *
324 * If there is an error in the connection, this handler will be invoked with the
325 * error dictionary as its argument. This dictionary will be one of the well-
326 * known XPC_ERROR_* dictionaries.
327 *
328 * Regardless of the type of event, ownership of the event object is NOT
329 * implicitly transferred. Thus, the object will be released and deallocated at
330 * some point in the future after the event handler returns. If you wish the
331 * event's lifetime to persist, you must retain it with xpc_retain().
332 *
333 * Connections received through the event handler will be released and
334 * deallocated after the connection has gone invalid and delivered that event to
335 * its event handler.
336 */
337__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
338XPC_EXPORT XPC_NONNULL_ALL
339void
340xpc_connection_set_event_handler(xpc_connection_t connection,
341 XPC_SWIFT_SENDABLE xpc_handler_t handler);
342
343/*!
344 * @function xpc_connection_activate
345 * Activates the connection. Connections start in an inactive state, so you must
346 * call xpc_connection_activate() on a connection before it will send or receive
347 * any messages.
348 *
349 * @param connection
350 * The connection object which is to be manipulated.
351 *
352 * @discussion
353 * Calling xpc_connection_activate() on an active connection has no effect.
354 * Releasing the last reference on an inactive connection that was created with
355 * an xpc_connection_create*() call is undefined.
356 *
357 * For backward compatibility reasons, xpc_connection_resume() on an inactive
358 * and not otherwise suspended xpc connection has the same effect as calling
359 * xpc_connection_activate(). For new code, using xpc_connection_activate()
360 * is preferred.
361 */
362__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
363__TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
364XPC_EXPORT XPC_NONNULL_ALL
365void
366xpc_connection_activate(xpc_connection_t connection);
367
368/*!
369 * @function xpc_connection_suspend
370 * Suspends the connection so that the event handler block will not fire and
371 * that the connection will not attempt to send any messages it has in its
372 * queue. All calls to xpc_connection_suspend() must be balanced with calls to
373 * xpc_connection_resume() before releasing the last reference to the
374 * connection.
375 *
376 * @param connection
377 * The connection object which is to be manipulated.
378 *
379 * @discussion
380 * Suspension is asynchronous and non-preemptive, and therefore this method will
381 * not interrupt the execution of an already-running event handler block. If
382 * the event handler is executing at the time of this call, it will finish, and
383 * then the connection will be suspended before the next scheduled invocation
384 * of the event handler. The XPC runtime guarantees this non-preemptiveness even
385 * for concurrent target queues.
386 *
387 * Connection event handlers are non-reentrant, so it is safe to call
388 * xpc_connection_suspend() from within the event handler block.
389 */
390__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
391XPC_EXPORT XPC_NONNULL_ALL
392void
393xpc_connection_suspend(xpc_connection_t connection);
394
395/*!
396 * @function xpc_connection_resume
397 * Resumes the connection.
398 *
399 * @param connection
400 * The connection object which is to be manipulated.
401 *
402 * @discussion
403 * In order for a connection to become live, every call to
404 * xpc_connection_suspend() must be balanced with a call to
405 * xpc_connection_resume().
406 *
407 * For backward compatibility reasons, xpc_connection_resume() on an inactive
408 * and not otherwise suspended xpc connection has the same effect as calling
409 * xpc_connection_activate(). For new code, using xpc_connection_activate()
410 * is preferred.
411 *
412 * Calling xpc_connection_resume() more times than xpc_connection_suspend()
413 * has been called is otherwise considered an error.
414 */
415__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
416XPC_EXPORT XPC_NONNULL_ALL
417void
418xpc_connection_resume(xpc_connection_t connection);
419
420/*!
421 * @function xpc_connection_send_message
422 * Sends a message over the connection to the destination service.
423 *
424 * @param connection
425 * The connection over which the message shall be sent.
426 *
427 * @param message
428 * The message to send. This must be a dictionary object. This dictionary is
429 * logically copied by the connection, so it is safe to modify the dictionary
430 * after this call.
431 *
432 * @discussion
433 * Messages are delivered in FIFO order. This API is safe to call from multiple
434 * GCD queues. There is no indication that a message was delivered successfully.
435 * This is because even once the message has been successfully enqueued on the
436 * remote end, there are no guarantees about when the runtime will dequeue the
437 * message and invoke the other connection's event handler block.
438 *
439 * If this API is used to send a message that is in reply to another message,
440 * there is no guarantee of ordering between the invocations of the connection's
441 * event handler and the reply handler for that message, even if they are
442 * targeted to the same queue.
443 *
444 * After extensive study, we have found that clients who are interested in
445 * the state of the message on the server end are typically holding open
446 * transactions related to that message. And the only reliable way to track the
447 * lifetime of that transaction is at the protocol layer. So the server should
448 * send a reply message, which upon receiving, will cause the client to close
449 * its transaction.
450 */
451__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
452XPC_EXPORT XPC_NONNULL_ALL
453void
454xpc_connection_send_message(xpc_connection_t connection, xpc_object_t message);
455
456/*!
457 * @function xpc_connection_send_barrier
458 * Issues a barrier against the connection's message-send activity.
459 *
460 * @param connection
461 * The connection against which the barrier is to be issued.
462 *
463 * @param barrier
464 * The barrier block to issue. This barrier prevents concurrent message-send
465 * activity on the connection. No messages will be sent while the barrier block
466 * is executing.
467 *
468 * @discussion
469 * XPC guarantees that, even if the connection's target queue is a concurrent
470 * queue, there are no other messages being sent concurrently while the barrier
471 * block is executing. XPC does not guarantee that the receipt of messages
472 * (either through the connection's event handler or through reply handlers)
473 * will be suspended while the barrier is executing.
474 *
475 * A barrier is issued relative to the message-send queue. Thus, if you call
476 * xpc_connection_send_message() five times and then call
477 * xpc_connection_send_barrier(), the barrier will be invoked after the fifth
478 * message has been sent and its memory disposed of. You may safely cancel a
479 * connection from within a barrier block.
480 *
481 * If a barrier is issued after sending a message which expects a reply, the
482 * behavior is the same as described above. The receipt of a reply message will
483 * not influence when the barrier runs.
484 *
485 * A barrier block can be useful for throttling resource consumption on the
486 * connected side of a connection. For example, if your connection sends many
487 * large messages, you can use a barrier to limit the number of messages that
488 * are inflight at any given time. This can be particularly useful for messages
489 * that contain kernel resources (like file descriptors) which have a system-
490 * wide limit.
491 *
492 * If a barrier is issued on a canceled connection, it will be invoked
493 * immediately. If a connection has been canceled and still has outstanding
494 * barriers, those barriers will be invoked as part of the connection's
495 * unwinding process.
496 *
497 * It is important to note that a barrier block's execution order is not
498 * guaranteed with respect to other blocks that have been scheduled on the
499 * target queue of the connection. Or said differently,
500 * xpc_connection_send_barrier(3) is not equivalent to dispatch_async(3).
501 */
502__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
503XPC_EXPORT XPC_NONNULL_ALL
504void
505xpc_connection_send_barrier(xpc_connection_t connection,
506 dispatch_block_t barrier);
507
508/*!
509 * @function xpc_connection_send_message_with_reply
510 * Sends a message over the connection to the destination service and associates
511 * a handler to be invoked when the remote service sends a reply message.
512 *
513 * @param connection
514 * The connection over which the message shall be sent.
515 *
516 * @param message
517 * The message to send. This must be a dictionary object.
518 *
519 * @param replyq
520 * The GCD queue to which the reply handler will be submitted. This may be a
521 * concurrent queue.
522 *
523 * @param handler
524 * The handler block to invoke when a reply to the message is received from
525 * the connection. If the remote service exits prematurely before the reply was
526 * received, the XPC_ERROR_CONNECTION_INTERRUPTED error will be returned.
527 * If the connection went invalid before the message could be sent, the
528 * XPC_ERROR_CONNECTION_INVALID error will be returned.
529 *
530 * @discussion
531 * If the given GCD queue is a concurrent queue, XPC cannot guarantee that there
532 * will not be multiple reply handlers being invoked concurrently. XPC does not
533 * guarantee any ordering for the invocation of reply handlers. So if multiple
534 * messages are waiting for replies and the connection goes invalid, there is no
535 * guarantee that the reply handlers will be invoked in FIFO order. Similarly,
536 * XPC does not guarantee that reply handlers will not run concurrently with
537 * the connection's event handler in the case that the reply queue and the
538 * connection's target queue are the same concurrent queue.
539 */
540__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
541XPC_EXPORT XPC_NONNULL1 XPC_NONNULL2 XPC_NONNULL4
542void
543xpc_connection_send_message_with_reply(xpc_connection_t connection,
544 xpc_object_t message, dispatch_queue_t _Nullable replyq,
545 XPC_SWIFT_SENDABLE xpc_handler_t handler);
546
547/*!
548 * @function xpc_connection_send_message_with_reply_sync
549 * Sends a message over the connection and blocks the caller until a reply is
550 * received.
551 *
552 * @param connection
553 * The connection over which the message shall be sent.
554 *
555 * @param message
556 * The message to send. This must be a dictionary object.
557 *
558 * @result
559 * The message that the remote service sent in reply to the original message.
560 * If the remote service exits prematurely before the reply was received, the
561 * XPC_ERROR_CONNECTION_INTERRUPTED error will be returned. If the connection
562 * went invalid before the message could be sent, the
563 * XPC_ERROR_CONNECTION_INVALID error will be returned.
564 *
565 * You are responsible for releasing the returned object.
566 *
567 * @discussion
568 * This API supports priority inversion avoidance, and should be used instead of
569 * combining xpc_connection_send_message_with_reply() with a semaphore.
570 *
571 * Invoking this API from a queue that is a part of the target queue hierarchy
572 * results in deadlocks under certain conditions.
573 *
574 * Be judicious about your use of this API. It can block indefinitely, so if you
575 * are using it to implement an API that can be called from the main thread, you
576 * may wish to consider allowing the API to take a queue and callback block so
577 * that results may be delivered asynchronously if possible.
578 */
579__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
580XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT XPC_RETURNS_RETAINED
581xpc_object_t
582xpc_connection_send_message_with_reply_sync(xpc_connection_t connection,
583 xpc_object_t message);
584
585/*!
586 * @function xpc_connection_cancel
587 * Cancels the connection and ensures that its event handler will not fire
588 * again. After this call, any messages that have not yet been sent will be
589 * discarded, and the connection will be unwound. If there are messages that are
590 * awaiting replies, they will have their reply handlers invoked with the
591 * XPC_ERROR_CONNECTION_INVALID error.
592 *
593 * @param connection
594 * The connection object which is to be manipulated.
595 *
596 * @discussion
597 * Cancellation is asynchronous and non-preemptive and therefore this method
598 * will not interrupt the execution of an already-running event handler block.
599 * If the event handler is executing at the time of this call, it will finish,
600 * and then the connection will be canceled.
601 *
602 * Canceling the connection will cause a final invocation of the event handler
603 * to be scheduled with the XPC_ERROR_CONNECTION_INVALID error. After that
604 * invocation, there will be no further invocations of the event handler.
605 *
606 * The XPC runtime guarantees this non-preemptiveness even for concurrent target
607 * queues.
608 */
609__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
610XPC_EXPORT XPC_NONNULL_ALL
611void
612xpc_connection_cancel(xpc_connection_t connection);
613
614/*!
615 * @function xpc_connection_get_name
616 * Returns the name of the service with which the connection was created.
617 *
618 * @param connection
619 * The connection object which is to be examined.
620 *
621 * @result
622 * The name of the remote service. If you obtained the connection through an
623 * invocation of another connection's event handler, NULL is returned.
624 */
625__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
626XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
627const char * _Nullable
628xpc_connection_get_name(xpc_connection_t connection);
629
630/*!
631 * @function xpc_connection_get_euid
632 * Returns the EUID of the remote peer.
633 *
634 * @param connection
635 * The connection object which is to be examined.
636 *
637 * @result
638 * The EUID of the remote peer at the time the connection was made.
639 */
640__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
641XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
642uid_t
643xpc_connection_get_euid(xpc_connection_t connection);
644
645/*!
646 * @function xpc_connection_get_egid
647 * Returns the EGID of the remote peer.
648 *
649 * @param connection
650 * The connection object which is to be examined.
651 *
652 * @result
653 * The EGID of the remote peer at the time the connection was made.
654 */
655__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
656XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
657gid_t
658xpc_connection_get_egid(xpc_connection_t connection);
659
660/*!
661 * @function xpc_connection_get_pid
662 * Returns the PID of the remote peer.
663 *
664 * @param connection
665 * The connection object which is to be examined.
666 *
667 * @result
668 * The PID of the remote peer.
669 *
670 * @discussion
671 * A given PID is not guaranteed to be unique across an entire boot cycle.
672 * Great care should be taken when dealing with this information, as it can go
673 * stale after the connection is established. OS X recycles PIDs, and therefore
674 * another process could spawn and claim the PID before a message is actually
675 * received from the connection.
676 *
677 * XPC will deliver an error to your event handler if the remote process goes
678 * away, but there are no guarantees as to the timing of this notification's
679 * delivery either at the kernel layer or at the XPC layer.
680 */
681API_AVAILABLE(macos(10.7))
682API_UNAVAILABLE(ios, tvos, watchos)
683XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
684pid_t
685xpc_connection_get_pid(xpc_connection_t connection);
686
687/*!
688 * @function xpc_connection_get_asid
689 * Returns the audit session identifier of the remote peer.
690 *
691 * @param connection
692 * The connection object which is to be examined.
693 *
694 * @result
695 * The audit session ID of the remote peer at the time the connection was made.
696 */
697API_AVAILABLE(macos(10.7))
698API_UNAVAILABLE(ios, tvos, watchos)
699XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
700au_asid_t
701xpc_connection_get_asid(xpc_connection_t connection);
702
703/*!
704 * @function xpc_connection_set_context
705 * Sets context on a connection.
706 *
707 * @param connection
708 * The connection which is to be manipulated.
709 *
710 * @param context
711 * The context to associate with the connection.
712 *
713 * @discussion
714 * If you must manage the memory of the context object, you must set a finalizer
715 * to dispose of it. If this method is called on a connection which already has
716 * context associated with it, the finalizer will NOT be invoked. The finalizer
717 * is only invoked when the connection is being deallocated.
718 *
719 * It is recommended that, instead of changing the actual context pointer
720 * associated with the object, you instead change the state of the context
721 * object itself.
722 */
723__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
724XPC_EXPORT XPC_NONNULL1
725void
726xpc_connection_set_context(xpc_connection_t connection,
727 void * _Nullable context);
728
729/*!
730 * @function xpc_connection_get_context
731 * Returns the context associated with the connection.
732 *
733 * @param connection
734 * The connection which is to be examined.
735 *
736 * @result
737 * The context associated with the connection. NULL if there has been no context
738 * associated with the object.
739 */
740__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
741XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
742void * _Nullable
743xpc_connection_get_context(xpc_connection_t connection);
744
745/*!
746 * @function xpc_connection_set_finalizer_f
747 * Sets the finalizer for the given connection.
748 *
749 * @param connection
750 * The connection on which to set the finalizer.
751 *
752 * @param finalizer
753 * The function that will be invoked when the connection's retain count has
754 * dropped to zero and is being torn down.
755 *
756 * @discussion
757 * This method disposes of the context value associated with a connection, as
758 * set by {@link xpc_connection_set_context}.
759 *
760 * For many uses of context objects, this API allows for a convenient shorthand
761 * for freeing them. For example, for a context object allocated with malloc(3):
762 *
763 * xpc_connection_set_finalizer_f(object, free);
764 */
765__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0)
766XPC_EXPORT XPC_NONNULL1
767void
768xpc_connection_set_finalizer_f(xpc_connection_t connection,
769 xpc_finalizer_t _Nullable finalizer);
770
771/*!
772 * @function xpc_connection_set_peer_code_signing_requirement
773 * Requires that the connection peer satisfies a code signing requirement.
774 *
775 * @param connection
776 * The connection object which is to be modified.
777 *
778 * @param requirement
779 * The code signing requirement to be satisfied by the peer.
780 * It is safe to deallocate the requirement string after calling `xpc_connection_set_peer_code_signing_requirement`.
781 *
782 * @result
783 * 0 on success, non-zero on error
784 *
785 * @discussion
786 * This function will return an error promptly if the code signing requirement string is invalid.
787 *
788 * It is a programming error to call `xpc_connection_set_peer_code_signing_requirement` more than once per connection.
789 *
790 * All messages received on this connection will be checked to ensure they come from a peer who satisfies
791 * the code signing requirement. For a listener connection, requests that do not satisfy the requirement
792 * are dropped. When a reply is expected on the connection and the peer does not satisfy the requirement
793 * `XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT` will be delivered instead of the reply.
794 *
795 * This API is not supported on embedded platforms and will return ENOTSUP.
796 *
797 * @see https://developer.apple.com/documentation/technotes/tn3127-inside-code-signing-requirements
798 */
799__API_AVAILABLE(macos(12.0), macCatalyst(15.0))
800API_UNAVAILABLE(ios, tvos, watchos)
801XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
802int
803xpc_connection_set_peer_code_signing_requirement(xpc_connection_t connection, const char *requirement);
804
805/*!
806 * @function xpc_connection_set_peer_entitlement_exists_requirement
807 * Requires that the connection peer has the specified entitlement.
808 *
809 * @param connection
810 * The connection object which is to be modified.
811 *
812 * @param entitlement
813 * The entitlement the peer must have.
814 * It is safe to deallocate the entitlement string after calling `xpc_connection_set_peer_entitlement_exists_requirement`.
815 *
816 * @result
817 * 0 on success, non-zero on error
818 *
819 * @discussion
820 * This function will return an error promptly if the entitlement requirement is invalid.
821 *
822 * It is a programming error to call multiple of the `xpc_connection_set_peer_*_requirement` family of functions on the same
823 * connection. If more complex combinations of requirements are required, use
824 * `xpc_connection_set_peer_lightweight_code_requirement`.
825 *
826 * All messages received on this connection will be checked to ensure that they come from a peer who satisfies the
827 * requirement. For a listener connection, requests that do not satisfy the requirement are dropped. When a reply
828 * is expected on the connection and the peer does not satisfy the requirement `XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT`
829 * will be delivered instead of the reply.
830 */
831API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), watchos(10.4))
832
833XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
834int
835xpc_connection_set_peer_entitlement_exists_requirement(xpc_connection_t connection, const char *entitlement);
836
837/*!
838 * @function xpc_connection_set_peer_entitlement_matches_value_requirement
839 * Requires that the connection peer has the specified entitlement with the matching value.
840 *
841 * @param connection
842 * The connection object which is to be modified.
843 *
844 * @param entitlement
845 * The entitlement the peer must have.
846 * It is safe to deallocate the entitlement string after calling `xpc_connection_set_peer_entitlement_matches_value_requirement`.
847 *
848 * @param value
849 * The value that the entitlement must match.
850 * It is safe to deallocate the value object after calling
851 * `xpc_connection_set_peer_entitlement_matches_value_requirement`.
852 * Valid xpc types for this object are `XPC_TYPE_BOOL`, `XPC_TYPE_STRING` and `XPC_TYPE_INT64`.
853 *
854 * @result
855 * 0 on success, non-zero on error
856 *
857 * @discussion
858 * This function will return an error promptly if the entitlement requirement is invalid.
859 *
860 * It is a programming error to call multiple of the `xpc_connection_set_peer_*_requirement` family of functions on the same
861 * connection. If more complex combinations of requirements are required, use
862 * `xpc_connection_set_peer_lightweight_code_requirement`.
863 *
864 * All messages received on this connection will be checked to ensure that they come from a peer who satisfies the
865 * requirement. For a listener connection, requests that do not satisfy the requirement are dropped. When a reply
866 * is expected on the connection and the peer does not satisfy the requirement `XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT`
867 * will be delivered instead of the reply.
868 */
869API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), watchos(10.4))
870
871XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
872int
873xpc_connection_set_peer_entitlement_matches_value_requirement(xpc_connection_t connection, const char *entitlement, xpc_object_t value);
874
875/*!
876 * @function xpc_connection_set_peer_team_identity_requirement
877 * Requires that the connection peer has the specified identity and is signed with the same team identifier
878 * as the current process.
879 *
880 * @param connection
881 * The connection object which is to be modified.
882 *
883 * @param signing_identifier
884 * The optional signing identifier the peer must have.
885 * It is safe to deallocate the signing identifier string after calling `xpc_connection_set_peer_identity_requirement`.
886 *
887 * @result
888 * 0 on success, non-zero on error
889 *
890 * @discussion
891 * This function will return an error promptly if the identity requirement is invalid.
892 *
893 * The peer process must be signed as either a Testflight app or an App store app,
894 * or be signed by an Apple-issued development certificate, an enterprise distributed
895 * certificate (embedded only), or a Developer ID certificate (macOS only)
896 *
897 * It is a programming error to call multiple of the `xpc_connection_set_peer_*_requirement` family of functions on the same
898 * connection. If more complex combinations of requirements are required, use
899 * `xpc_connection_set_peer_lightweight_code_requirement`.
900 *
901 * All messages received on this connection will be checked to ensure that they come from a peer who satisfies the
902 * requirement. For a listener connection, requests that do not satisfy the requirement are dropped. When a reply
903 * is expected on the connection and the peer does not satisfy the requirement `XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT`
904 * will be delivered instead of the reply.
905 */
906API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), watchos(10.4))
907
908XPC_EXPORT XPC_NONNULL1 XPC_WARN_RESULT
909int
910xpc_connection_set_peer_team_identity_requirement(xpc_connection_t connection, const char * _Nullable signing_identifier);
911
912/*!
913 * @function xpc_connection_set_peer_platform_identity_requirement
914 * Requires that the connection peer has the specified identity and is signed by Apple.
915 *
916 * @param connection
917 * The connection object which is to be modified.
918 *
919 * @param signing_identifier
920 * The optional signing identifier the peer must have. If not specified, this function ensures that the peer is signed by Apple.
921 * It is safe to deallocate the signing identifier string after calling `xpc_connection_set_peer_identity_requirement`.
922 *
923 * @result
924 * 0 on success, non-zero on error
925 *
926 * @discussion
927 * This function will return an error promptly if the identity requirement is invalid.
928 *
929 * The peer process must be signed by Apple. Use `xpc_connection_set_peer_identity_requirement` if the peer
930 * is not part of the OS.
931 *
932 * It is a programming error to call multiple of the `xpc_connection_set_peer_*_requirement` family of functions on the same
933 * connection. If more complex combinations of requirements are required, use
934 * `xpc_connection_set_peer_lightweight_code_requirement`.
935 *
936 * All messages received on this connection will be checked to ensure that they come from a peer who satisfies the
937 * requirement. For a listener connection, requests that do not satisfy the requirement are dropped. When a reply
938 * is expected on the connection and the peer does not satisfy the requirement `XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT`
939 * will be delivered instead of the reply.
940 */
941API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), watchos(10.4))
942
943XPC_EXPORT XPC_NONNULL1 XPC_WARN_RESULT
944int
945xpc_connection_set_peer_platform_identity_requirement(xpc_connection_t connection, const char * _Nullable signing_identifier);
946
947/*!
948 * @function xpc_connection_set_peer_lightweight_code_requirement
949 * Requires that the connection peer has the specified lightweight code requirement.
950 *
951 * @param connection
952 * The connection object which is to be modified.
953 *
954 * @param lwcr
955 * The lightweight code requirement the peer must have.
956 * It is safe to deallocate the lightweight code requirement object after calling `xpc_connection_set_peer_lightweight_code_requirement`.
957 *
958 * @result
959 * 0 on success, non-zero on error
960 *
961 * @discussion
962 * This function will return an error promptly if the lightweight code requirement is invalid.
963 *
964 * The lightweight code requirement must be an `xpc_dictionary_t` equivalent of an LWCR constraint (see
965 * https://developer.apple.com/documentation/security/defining_launch_environment_and_library_constraints
966 * for details on the contents of the dictionary)
967 *
968 * The lightweight code requirement in the example below uses the $or operator to require that an
969 * executable’s either signed with the Team ID 8XCUU22SN2, or is an operating system executable:
970 * ```c
971 * xpc_object_t or_val = xpc_dictionary_create_empty();
972 * xpc_dictionary_set_string(or_val, "team-identifier", "8XCUU22SN2");
973 * xpc_dictionary_set_int64(or_val, "validation-category", 1);
974 *
975 * xpc_object_t lwcr = xpc_dictionary_create_empty();
976 * xpc_dictionary_set_value(lwcr, "$or", or_val);
977 *
978 * xpc_connection_set_peer_lightweight_code_requirement(connection, lwcr);
979 * ```
980 *
981 * It is a programming error to call multiple of the `xpc_connection_set_peer_*_requirement` family of functions on the same
982 * connection.
983 *
984 * All messages received on this connection will be checked to ensure that they come from a peer who satisfies the
985 * requirement. For a listener connection, requests that do not satisfy the requirement are dropped. When a reply
986 * is expected on the connection and the peer does not satisfy the requirement `XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT`
987 * will be delivered instead of the reply.
988 */
989API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), watchos(10.4))
990
991XPC_EXPORT XPC_NONNULL_ALL XPC_WARN_RESULT
992int
993xpc_connection_set_peer_lightweight_code_requirement(xpc_connection_t connection, xpc_object_t lwcr);
994
995/*!
996 * @function xpc_connection_set_peer_requirement
997 * Requires that the connection peer has the specified requirement.
998 *
999 * @param connection
1000 * The connection object which is to be modified.
1001 *
1002 * @param peer_requirement
1003 * The requirement the peer must have.
1004 * It is safe to deallocate the peer requirement after calling `xpc_connection_set_peer_requirement`.
1005 *
1006 * @discussion
1007 * It is a programming error to call multiple of the `xpc_connection_set_peer_*_requirement` family of functions on the same
1008 * connection. If more complex combinations of requirements are required, use lightweight code requirement.
1009 *
1010 * All messages received on this connection will be checked to ensure that they come from a peer who satisfies the
1011 * requirement. For a listener connection, requests that do not satisfy the requirement are dropped. When a reply
1012 * is expected on the connection and the peer does not satisfy the requirement `XPC_ERROR_PEER_CODE_SIGNING_REQUIREMENT`
1013 * will be delivered instead of the reply.
1014 */
1015API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0))
1016
1017XPC_EXPORT XPC_SWIFT_NOEXPORT XPC_NONNULL_ALL
1018void
1019xpc_connection_set_peer_requirement(xpc_connection_t connection,
1020 xpc_peer_requirement_t peer_requirement);
1021
1022/*!
1023 * @function xpc_connection_copy_invalidation_reason
1024 * Returns a description of why the connection was invalidated.
1025 *
1026 * @param connection
1027 * The connection object to inspect.
1028 *
1029 * @result
1030 * NULL if the connection has not been invalidated, otherwise a description for why the connection was invalidated.
1031 */
1032API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0))
1033XPC_EXPORT XPC_NONNULL1 XPC_WARN_RESULT
1034char * _Nullable
1035xpc_connection_copy_invalidation_reason(xpc_connection_t connection);
1036
1037__END_DECLS
1038XPC_ASSUME_NONNULL_END
1039
1040#endif // __XPC_CONNECTION_H__