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)
 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)
 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)
 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))
 832API_UNAVAILABLE(tvos, watchos)
 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))
 870API_UNAVAILABLE(tvos, watchos)
 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))
 907API_UNAVAILABLE(tvos, watchos)
 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))
 942API_UNAVAILABLE(tvos, watchos)
 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))
 990API_UNAVAILABLE(tvos, watchos)
 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))
1016API_UNAVAILABLE(tvos, watchos)
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__