← XPC

XPC connections

XPC Dokümantasyonu

API Collection | XPC

Create and manage connections to services using connection-based APIs.

Use these APIs to work with XPC connections and related types — for example, when a framework function that you call returns an xpc_connection_t.

But, in most situations, the listener- and session-based APIs are a better choice for designing XPC communication protocols. For more information, see Creating XPC services.

Creation

  • xpc_connection_t typealias xpc_connection_t — A type that represents a connection to a named service.
  • xpc_connection_create(_:_:)) func xpc_connection_create(UnsafePointer<CChar>?, dispatch_queue_t?) -> xpc_connection_t — Creates a new connection object.
  • xpc_connection_create_from_endpoint(_:)) func xpc_connection_create_from_endpoint(xpc_endpoint_t) -> xpc_connection_t — Creates a new connection from the specified endpoint.
  • xpc_connection_create_mach_service(_:_:_:)) func xpc_connection_create_mach_service(UnsafePointer<CChar>, dispatch_queue_t?, UInt64) -> xpc_connection_t — Creates a new connection object that represents a Mach service.
  • xpc_connection_set_target_queue(_:_:)) func xpc_connection_set_target_queue(xpc_connection_t, dispatch_queue_t?) — Sets the target queue of the connection.
  • XPC_CONNECTION_MACH_SERVICE_LISTENER var XPC_CONNECTION_MACH_SERVICE_LISTENER: Int32 — A flag that indicates the caller is the listener for the named service.
  • XPC_CONNECTION_MACH_SERVICE_PRIVILEGED var XPC_CONNECTION_MACH_SERVICE_PRIVILEGED: Int32 — A flag that indicates the job advertising the service name belongs to a launch daemon rather than a launch agent.

Event handling

  • xpc_connection_set_event_handler(_:_:)) func xpc_connection_set_event_handler(xpc_connection_t, (xpc_object_t) -> Void) — Sets the event handler block for the connection.
  • xpc_handler_t typealias xpc_handler_t — The type of block that the XPC connection APIs accept.
  • xpc_connection_handler_t typealias xpc_connection_handler_t — The type of the function to invoke for a bundled XPC service when there’s a new connection on the service.

Life cycle

  • xpc_main(_:)) func xpc_main(xpc_connection_handler_t) -> Never — Starts listening for incoming connections and processes them with the specified event handler.
  • xpc_connection_activate(_:)) func xpc_connection_activate(xpc_connection_t) — Activates a new connection.
  • xpc_connection_suspend(_:)) func xpc_connection_suspend(xpc_connection_t) — Suspends the connection so the event handler block doesn’t fire and the connection doesn’t attempt to send any messages it has in its queue.
  • xpc_connection_resume(_:)) func xpc_connection_resume(xpc_connection_t) — Resumes a suspended connection.
  • xpc_connection_cancel(_:)) func xpc_connection_cancel(xpc_connection_t) — Cancels the connection and ensures that its event handler doesn’t fire again.
  • xpc_transaction_begin()) func xpc_transaction_begin() — Informs the XPC runtime when a transaction begins, indicating that the service isn’t idle.
  • xpc_transaction_end()) func xpc_transaction_end() — Informs the XPC runtime when a transaction ends.
  • xpc_connection_copy_invalidation_reason(_:)) func xpc_connection_copy_invalidation_reason(xpc_connection_t) -> UnsafeMutablePointer<CChar>? —

Messages

  • xpc_connection_send_message(_:_:)) func xpc_connection_send_message(xpc_connection_t, xpc_object_t) — Sends a message over the connection to the destination service.
  • xpc_connection_send_barrier(_:_:)) func xpc_connection_send_barrier(xpc_connection_t, () -> Void) — Issues a barrier against the connection’s message-send activity.
  • xpc_connection_send_message_with_reply(_:_:_:_:)) func xpc_connection_send_message_with_reply(xpc_connection_t, xpc_object_t, dispatch_queue_t?, (xpc_object_t) -> Void) — Sends a message over the connection to the destination service and associates a handler to invoke when the remote service sends a reply message.
  • xpc_connection_send_message_with_reply_sync(_:_:)) func xpc_connection_send_message_with_reply_sync(xpc_connection_t, xpc_object_t) -> xpc_object_t — Sends a message over the connection and blocks the caller until it receives a reply.
  • xpc_main(_:)) func xpc_main(xpc_connection_handler_t) -> Never — Starts listening for incoming connections and processes them with the specified event handler.

Remote peer information

Context

  • xpc_connection_set_context(_:_:)) func xpc_connection_set_context(xpc_connection_t, UnsafeMutableRawPointer?) — Sets a context on the connection.
  • xpc_connection_get_context(_:)) func xpc_connection_get_context(xpc_connection_t) -> UnsafeMutableRawPointer? — Returns the context for the connection.
  • xpc_connection_set_finalizer_f(_:_:)) func xpc_connection_set_finalizer_f(xpc_connection_t, xpc_finalizer_t?) — Sets the finalizer for the connection.
  • xpc_finalizer_t typealias xpc_finalizer_t — A function to invoke when tearing down a connection and freeing its context.

Endpoints

  • xpc_endpoint_create(_:)) func xpc_endpoint_create(xpc_connection_t) -> xpc_endpoint_t — Creates a new endpoint from a connection that is suitable for embedding into messages.
  • xpc_endpoint_t typealias xpc_endpoint_t — A type that represents a connection in serialized form.

Errors

  • XPC_ERROR_CONNECTION_INVALID var XPC_ERROR_CONNECTION_INVALID: xpc_object_t — An error that sends to the connection’s event handler to indicate that the connection is no longer usable.
  • XPC_ERROR_CONNECTION_INTERRUPTED var XPC_ERROR_CONNECTION_INTERRUPTED: xpc_object_t — An error that sends to the connection’s event handler when the remote service exits.
  • XPC_ERROR_TERMINATION_IMMINENT var XPC_ERROR_TERMINATION_IMMINENT: xpc_object_t — An error that sends to a peer connection’s event handler when the XPC runtime determines that the program needs to exit and that all outstanding transactions must wind down.

See Also

Additional Types

xpc_connection_activate(_:)

Function | XPC

Activates a new connection.

func xpc_connection_activate(_ connection: xpc_connection_t)

Connections start in an inactive state, so you must call xpc_connection_activate(_:)) on a connection before it will send or receive any messages.

Calling xpc_connection_activate(_:)) on an active connection has no effect. Releasing the last reference on an inactive connection that was created with a call to one of the xpc_connection_create functions is undefined.

For backward compatibility reasons, xpc_connection_resume(_:)) on an inactive and not otherwise suspended XPC connection has the same effect as calling xpc_connection_activate(_:)). For new code, using xpc_connection_activate(_:)) is preferred.

See Also

Life cycle

xpc_connection_cancel(_:)

Function | XPC

Cancels the connection and ensures that its event handler doesn’t fire again.

func xpc_connection_cancel(_ connection: xpc_connection_t)

After this call, any messages that have not yet been sent will be discarded, and the connection will be unwound. If there are messages that are awaiting replies, they will have their reply handlers invoked with the XPC_ERROR_CONNECTION_INVALID error.

Cancellation is asynchronous and non-preemptive and therefore this method will not interrupt the execution of an already-running event handler block. If the event handler is executing at the time of this call, it will finish, and then the connection will be canceled, causing a final invocation of the event handler to be scheduled with the XPC_ERROR_CONNECTION_INVALID error. After that invocation, there will be no further invocations of the event handler.

The XPC runtime guarantees this non-preemptiveness even for concurrent target queues.

Parameters

  • connection: The connection object which is to be manipulated.

See Also

Life cycle

xpc_connection_copy_invalidation_reason(_:)

Function | XPC

func xpc_connection_copy_invalidation_reason(_ connection: xpc_connection_t) -> UnsafeMutablePointer<CChar>?

See Also

Life cycle

xpc_connection_create(_:_:)

Function | XPC

Creates a new connection object.

func xpc_connection_create(_ name: UnsafePointer<CChar>?, _ targetq: dispatch_queue_t?) -> xpc_connection_t

A new connection object. The caller is responsible for disposing of the returned object with xpc_release when it is no longer needed.

Parameters

  • name: If non-NULL, the name of the service with which to connect. The returned connection will be a peer.

If NULL, an anonymous listener connection will be created. You can embed the ability to create new peer connections in an endpoint, which can be inserted into a message and sent to another process .

  • targetq: The GCD queue to which the event handler block will be submitted. This parameter may be NULL, in which case the connection’s target queue will be the default target queue of libdispatch, defined as DISPATCH_TARGET_QUEUE_DEFAULT. The target queue may be changed later with a call to xpc_connection_set_target_queue(_:_:)).

See Also

Creation

xpc_connection_create_from_endpoint(_:)

Function | XPC

Creates a new connection from the specified endpoint.

func xpc_connection_create_from_endpoint(_ endpoint: xpc_endpoint_t) -> xpc_connection_t

A new peer connection to the listener represented by the given endpoint.

Parameters

  • endpoint: The endpoint from which to create the new connection.

See Also

Creation

xpc_connection_get_asid(_:)

Function | XPC

Returns the audit session identifier of the remote peer.

func xpc_connection_get_asid(_ connection: xpc_connection_t) -> au_asid_t

The audit session ID of the remote peer at the time the connection was made.

Parameters

  • connection: The connection object which is to be examined.

See Also

Remote peer information

xpc_connection_create_mach_service(_:_:_:)

Function | XPC

Creates a new connection object that represents a Mach service.

func xpc_connection_create_mach_service(_ name: UnsafePointer<CChar>, _ targetq: dispatch_queue_t?, _ flags: UInt64) -> xpc_connection_t

A new connection object.

Parameters

  • name: The name of the remote service with which to connect. The service name must exist in a Mach bootstrap that is accessible to the process and be advertised in a launchd.plist.
  • targetq: The GCD queue to which the event handler block will be submitted. This parameter may be NULL, in which case the connection’s target queue will be the default target queue of libdispatch, defined as DISPATCH_TARGET_QUEUE_DEFAULT. The target queue may be changed later with a call to xpc_connection_set_target_queue(_:_:)).
  • flags: Additional attributes with which to create the connection.

See Also

Creation

xpc_connection_get_egid(_:)

Function | XPC

Returns the EGID of the remote peer.

func xpc_connection_get_egid(_ connection: xpc_connection_t) -> gid_t

The EGID of the remote peer at the time the connection was made.

Parameters

  • connection: The connection object which is to be examined.

See Also

Remote peer information

xpc_connection_get_context(_:)

Function | XPC

Returns the context for the connection.

func xpc_connection_get_context(_ connection: xpc_connection_t) -> UnsafeMutableRawPointer?

The context associated with the connection. NULL if there has been no context associated with the object.

Parameters

  • connection: The connection which is to be examined.

See Also

Context

xpc_connection_get_euid(_:)

Function | XPC

Returns the EUID of the remote peer.

func xpc_connection_get_euid(_ connection: xpc_connection_t) -> uid_t

The EUID of the remote peer at the time the connection was made.

Parameters

  • connection: The connection object which is to be examined.

See Also

Remote peer information

xpc_connection_get_name(_:)

Function | XPC

Returns the name of the remote service that creates the connection.

func xpc_connection_get_name(_ connection: xpc_connection_t) -> UnsafePointer<CChar>?

The name of the remote service. If you obtained the connection through an invocation of another connection’s event handler, NULL is returned.

Parameters

  • connection: The connection object which is to be examined.

See Also

Remote peer information

xpc_connection_get_pid(_:)

Function | XPC

Returns the PID of the remote peer.

func xpc_connection_get_pid(_ connection: xpc_connection_t) -> pid_t

The PID of the remote peer.

Parameters

  • connection: The connection object which is to be examined.

See Also

Remote peer information

xpc_connection_handler_t

Type Alias | XPC

The type of the function to invoke for a bundled XPC service when there’s a new connection on the service.

typealias xpc_connection_handler_t = (xpc_connection_t) -> Void

Parameters

  • connection: A new connection that is equivalent to one received by a listener connection. See the documentation for xpc_connection_set_event_handler(_:_:)) for the semantics associated with the received connection.

See Also

Event handling

XPC_CONNECTION_MACH_SERVICE_LISTENER

Global Variable | XPC

A flag that indicates the caller is the listener for the named service.

var XPC_CONNECTION_MACH_SERVICE_LISTENER: Int32 { get }

Pass this to xpc_connection_create_mach_service(_:_:_:)). This flag indicates that the caller is the listener for the named service. Only pass this flag for services in the process’s launchd.plist. You may not use this flag to dynamically add services to the Mach bootstrap namespace.

See Also

Creation

XPC_CONNECTION_MACH_SERVICE_PRIVILEGED

Global Variable | XPC

A flag that indicates the job advertising the service name belongs to a launch daemon rather than a launch agent.

var XPC_CONNECTION_MACH_SERVICE_PRIVILEGED: Int32 { get }

Pass this to xpc_connection_create_mach_service(_:_:_:)). This flag indicates that the job advertising the service name in its launchd.plist needs to be in the privileged Mach bootstrap. Do this by placing your launchd.plist in /Library/LaunchDaemons.

If you specify this alongside the XPC_CONNECTION_MACH_SERVICE_LISTENER flag, this flag is a no-op.

See Also

Creation

xpc_connection_resume(_:)

Function | XPC

Resumes a suspended connection.

func xpc_connection_resume(_ connection: xpc_connection_t)

In order for a connection to become live, every call to xpc_connection_suspend(_:)) must be balanced with a call to xpc_connection_resume(_:)) after the initial call to xpc_connection_resume(_:)). After the initial resume of the connection, calling xpc_connection_resume(_:)) more times than xpc_connection_suspend(_:)) has been called is considered an error.

Parameters

  • connection: The connection object which is to be manipulated.

See Also

Life cycle

xpc_connection_send_message(_:_:)

Function | XPC

Sends a message over the connection to the destination service.

func xpc_connection_send_message(_ connection: xpc_connection_t, _ message: xpc_object_t)

Messages are delivered in FIFO order. This API is safe to call from multiple GCD queues. There is no indication that a message was delivered successfully. This is because even once the message has been successfully enqueued on the remote end, there are no guarantees about when the runtime will dequeue the message and invoke the other connection’s event handler block.

If this API is used to send a message that is in reply to another message, there is no guarantee of ordering between the invocations of the connection’s event handler and the reply handler for that message, even if they are targeted to the same queue.

After extensive study, we have found that clients who are interested in the state of the message on the server end are typically holding open transactions related to that message. And the only reliable way to track the lifetime of that transaction is at the protocol layer. So the server should send a reply message, which upon receiving, will cause the client to close its transaction.

Parameters

  • connection: The connection over which the message shall be sent.
  • message: The message to send. This must be a dictionary object. This dictionary is logically copied by the connection, so it is safe to modify the dictionary after this call.

See Also

Messages

xpc_connection_send_barrier(_:_:)

Function | XPC

Issues a barrier against the connection’s message-send activity.

func xpc_connection_send_barrier(_ connection: xpc_connection_t, _ barrier: @escaping () -> Void)

XPC guarantees that, even if the connection’s target queue is a concurrent queue, there are no other messages being sent concurrently while the barrier block is executing. XPC does not guarantee that the receipt of messages (either through the connection’s event handler or through reply handlers) will be suspended while the barrier is executing.

A barrier is issued relative to the message-send queue. So, if you call xpc_connection_send_message(_:_:)) five times and then call xpc_connection_send_barrier(_:_:)), the barrier will be invoked after the fifth message has been sent and its memory disposed of. You may safely cancel a connection from within a barrier block.

If a barrier is issued after sending a message which expects a reply, the behavior is the same as described above. The receipt of a reply message will not influence when the barrier runs.

A barrier block can be useful for throttling resource consumption on the connected side of a connection. For example, if your connection sends many large messages, you can use a barrier to limit the number of messages that are inflight at any given time. This can be particularly useful for messages that contain kernel resources (like file descriptors) which have a systemwide limit.

If a barrier is issued on a canceled connection, it will be invoked immediately. If a connection has been canceled and still has outstanding barriers, those barriers will be invoked as part of the connection’s unwinding process.

It is important to note that a barrier block’s execution order is not guaranteed with respect to other blocks that have been scheduled on the target queue of the connection. Or said differently, xpc_connection_send_barrier(_:_:)) is not equivalent to dispatch_async.

Parameters

  • connection: The connection against which the barrier is to be issued.
  • barrier: The barrier block to issue. This barrier prevents concurrent message-send activity on the connection. No messages will be sent while the barrier block is executing.

See Also

Messages

xpc_connection_send_message_with_reply(_:_:_:_:)

Function | XPC

Sends a message over the connection to the destination service and associates a handler to invoke when the remote service sends a reply message.

func xpc_connection_send_message_with_reply(_ connection: xpc_connection_t, _ message: xpc_object_t, _ replyq: dispatch_queue_t?, _ handler: @escaping @Sendable (xpc_object_t) -> Void)

If the given GCD queue is a concurrent queue, XPC cannot guarantee that there will not be multiple reply handlers being invoked concurrently. XPC does not guarantee any ordering for the invocation of reply handers. So if multiple messages are waiting for replies and the connection goes invalid, there is no guarantee that the reply handlers will be invoked in FIFO order. Similarly, XPC does not guarantee that reply handlers will not run concurrently with the connection’s event handler in the case that the reply queue and the connection’s target queue are the same concurrent queue.

Parameters

  • connection: The connection over which the message shall be sent.
  • message: The message to send. This must be a dictionary object.
  • replyq: The GCD queue to which the reply handler will be submitted. This may be a concurrent queue.
  • handler: The handler block to invoke when a reply to the message is received from the connection. If the remote service exits prematurely before the reply was received, the XPC_ERROR_CONNECTION_INTERRUPTED error will be returned. If the connection went invalid before the message could be sent, the XPC_ERROR_CONNECTION_INVALID error will be returned.

See Also

Messages

xpc_connection_set_context(_:_:)

Function | XPC

Sets a context on the connection.

func xpc_connection_set_context(_ connection: xpc_connection_t, _ context: UnsafeMutableRawPointer?)

If you must manage the memory of the context object, you must set a finalizer to dispose of it. If this method is called on a connection which already has context associated with it, the finalizer will NOT be invoked. The finalizer is only invoked when the connection is being deallocated.

It is recommended that, instead of changing the actual context pointer associated with the object, you instead change the state of the context object itself.

Parameters

  • connection: The connection which is to be manipulated.
  • context: The context to associate with the connection.

See Also

Context

xpc_connection_send_message_with_reply_sync(_:_:)

Function | XPC

Sends a message over the connection and blocks the caller until it receives a reply.

func xpc_connection_send_message_with_reply_sync(_ connection: xpc_connection_t, _ message: xpc_object_t) -> xpc_object_t

The message that the remote service sends in reply to the original message. If the remote service exits prematurely before receiving the reply, the XPC_ERROR_CONNECTION_INTERRUPTED error returns. If the connection becomes invalid before the remote service sends the message, the XPC_ERROR_CONNECTION_INVALID error returns.

Parameters

  • connection: The connection for sending the message.
  • message: The message to send. This must be a dictionary object.

See Also

Messages

xpc_connection_set_event_handler(_:_:)

Function | XPC

Sets the event handler block for the connection.

func xpc_connection_set_event_handler(_ connection: xpc_connection_t, _ handler: @escaping @Sendable (xpc_object_t) -> Void)

Setting the event handler is asynchronous and non-preemptive, and therefore this method will not interrupt the execution of an already-running event handler block. If the event handler is executing at the time of this call, it will finish, and then the connection’s event handler will be changed before the next invocation of the event handler. The XPC runtime guarantees this non-preemptiveness even for concurrent target queues.

Connection event handlers are non-reentrant, so it is safe to call xpc_connection_set_event_handler(_:_:)) from within the event handler block.

The event handler’s execution should be treated as a barrier to all connection activity. When it is executing, the connection will not attempt to send or receive messages, including reply messages. So, it is not safe to call xpc_connection_send_message_with_reply_sync(_:_:)) on the connection from within the event handler.

You do not hold a reference on the object received as the event handler’s only argument. Regardless of the type of object received, it is safe to call xpc_retain on the object to obtain a reference to it.

A connection may receive different events depending upon whether it is a listener or not. Any connection may receive an error in its event handler. But while normal connections may receive messages in addition to errors, listener connections will receive connections and and not messages.

Connections received by listeners are equivalent to those returned by xpc_connection_create(_:_:)) with a non-NULL name argument and a NULL targetq argument with the exception that you do not hold a reference on them. You must set an event handler and resume the connection. If you do not wish to accept the connection, you may simply call xpc_connection_cancel(_:)) on it and return. The runtime will dispose of it for you.

If there is an error in the connection, this handler will be invoked with the error dictionary as its argument. This dictionary will be one of the well-known XPC_ERROR dictionaries.

Regardless of the type of event, ownership of the event object is NOT implicitly transferred. So, the object will be released and deallocated at some point in the future after the event handler returns. If you wish the event’s lifetime to persist, you must retain it with xpc_retain.

Connections received through the event handler will be released and deallocated after the connection has gone invalid and delivered that event to its event handler.

Parameters

  • connection: The connection object which is to be manipulated.
  • handler: The event handler block.

See Also

Event handling

xpc_connection_set_peer_code_signing_requirement(_:_:)

Function | XPC

func xpc_connection_set_peer_code_signing_requirement(_ connection: xpc_connection_t, _ requirement: UnsafePointer<CChar>) -> Int32

See Also

Remote peer information

xpc_connection_set_finalizer_f(_:_:)

Function | XPC

Sets the finalizer for the connection.

func xpc_connection_set_finalizer_f(_ connection: xpc_connection_t, _ finalizer: xpc_finalizer_t?)

For many uses of context objects, this API allows for a convenient shorthand for freeing them. For example, for a context object allocated with malloc(3):

xpc_connection_set_finalizer_f(object, free);

Parameters

  • connection: The connection on which to set the finalizer.
  • finalizer: The function that will be invoked when the connection’s retain count has dropped to zero and is being torn down.

See Also

Context

xpc_connection_set_peer_entitlement_exists_requirement(_:_:)

Function | XPC

Sets a requirement that the executable for the peer process has a valid code signature that contains an entitlement.

func xpc_connection_set_peer_entitlement_exists_requirement(_ connection: xpc_connection_t, _ entitlement: UnsafePointer<CChar>) -> Int32

On success, 0. Otherwise, a value from Errors.

Parameters

  • connection: The XPC connection.
  • entitlement: The name of the entitlement to check.

See Also

Remote peer information

xpc_connection_set_peer_entitlement_matches_value_requirement(_:_:_:)

Function | XPC

Sets a requirement that the executable for the peer process has a valid code signature that contains an entitlement with a specific value.

func xpc_connection_set_peer_entitlement_matches_value_requirement(_ connection: xpc_connection_t, _ entitlement: UnsafePointer<CChar>, _ value: xpc_object_t) -> Int32

On success, 0. Otherwise, a value from Errors.

Parameters

  • connection: The XPC connection.
  • entitlement: The name of the entitlement to check.
  • value: The expected value for the entitlement.

See Also

Remote peer information

xpc_connection_set_peer_platform_identity_requirement(_:_:)

Function | XPC

Sets a requirement that the executable for the peer process has a valid code signature that identifies it as an Apple-signed binary with the given signing identifier.

func xpc_connection_set_peer_platform_identity_requirement(_ connection: xpc_connection_t, _ signing_identifier: UnsafePointer<CChar>?) -> Int32

On success, 0. Otherwise, a value from Errors.

Parameters

  • connection: The XPC connection.
  • signing_identifier: The code-signing identifier for the peer process’s executable. This value is typically a Bundle ID for apps and extensions. Pass NULL to indicate that any Apple-signed binary is acceptable.

See Also

Remote peer information

xpc_connection_set_peer_lightweight_code_requirement(_:_:)

Function | XPC

Sets a requirement that the executable for the peer process has a valid code signature that matches the lightweight code requirement.

func xpc_connection_set_peer_lightweight_code_requirement(_ connection: xpc_connection_t, _ lwcr: xpc_object_t) -> Int32

On success, 0. Otherwise, a value from Errors.

Parameters

See Also

Remote peer information

xpc_connection_set_peer_team_identity_requirement(_:_:)

Function | XPC

Sets a requirement that the executable for the peer process has a valid code signature and is signed by the same team identifier as the calling process.

func xpc_connection_set_peer_team_identity_requirement(_ connection: xpc_connection_t, _ signing_identifier: UnsafePointer<CChar>?) -> Int32

On success, 0. Otherwise, a value from Errors.

Parameters

  • connection: The XPC connection.
  • signing_identifier: The code-signing identifier for the peer process’s executable. This value is typically a Bundle ID for apps and extensions. Pass NULL to indicate that any binary signed by the same team as this process is acceptable.

See Also

Remote peer information

xpc_connection_set_target_queue(_:_:)

Function | XPC

Sets the target queue of the connection.

func xpc_connection_set_target_queue(_ connection: xpc_connection_t, _ targetq: dispatch_queue_t?)

Setting the target queue is asynchronous and non-preemptive and therefore this method will not interrupt the execution of an already-running event handler block. Setting the target queue may be likened to issuing a barrier to the connection which does the actual work of changing the target queue.

The XPC runtime guarantees this non-preemptiveness even for concurrent target queues. If the target queue is a concurrent queue, then XPC still guarantees that there will never be more than one invocation of the connection’s event handler block executing concurrently. If you wish to process events concurrently, you can dispatch_async to a concurrent queue from within the event handler.

Important: When called from within the event handler block, dispatch_get_current_queue()) is NOT guaranteed to return a pointer to the queue set with this method.

Despite this seeming inconsistency, the XPC runtime guarantees that, when the target queue is a serial queue, the event handler block will execute synchonously with respect to other blocks submitted to that same queue. When the target queue is a concurrent queue, the event handler block may run concurrently with other blocks submitted to that queue, but it will never run concurrently with other invocations of itself for the same connection, as discussed previously.

Parameters

  • connection: The connection object which is to be manipulated.
  • targetq: The GCD queue to which the event handler block will be submitted. This parameter may be NULL, in which case the connection’s target queue will be the default target queue of libdispatch, defined as DISPATCH_TARGET_QUEUE_DEFAULT.

See Also

Creation

xpc_connection_suspend(_:)

Function | XPC

Suspends the connection so the event handler block doesn’t fire and the connection doesn’t attempt to send any messages it has in its queue.

func xpc_connection_suspend(_ connection: xpc_connection_t)

All calls to xpc_connection_suspend(_:)) must be balanced with calls to xpc_connection_resume(_:)) before releasing the last reference to the connection.

Suspension is asynchronous and non-preemptive, and therefore this method will not interrupt the execution of an already-running event handler block. If the event handler is executing at the time of this call, it will finish, and then the connection will be suspended before the next scheduled invocation of the event handler. The XPC runtime guarantees this non-preemptiveness even for concurrent target queues.

Connection event handlers are non-reentrant, so it is safe to call xpc_connection_suspend(_:)) from within the event handler block.

Parameters

  • connection: The connection object which is to be manipulated.

See Also

Life cycle

xpc_connection_t

Type Alias | XPC

A type that represents a connection to a named service.

typealias xpc_connection_t = xpc_object_t

See Also

Creation

xpc_endpoint_create(_:)

Function | XPC

Creates a new endpoint from a connection that is suitable for embedding into messages.

func xpc_endpoint_create(_ connection: xpc_connection_t) -> xpc_endpoint_t

A new endpoint object.

Parameters

  • connection: Only connections obtained through calls to one of the xpc_connection_create functions may be given to this API. Passing any other type of connection is not supported and will result in undefined behavior.

See Also

Endpoints

xpc_endpoint_t

Type Alias | XPC

A type that represents a connection in serialized form.

typealias xpc_endpoint_t = xpc_object_t

Unlike a connection, an endpoint is an inert object that doesn’t have any associated runtime activity. So, it is safe to pass an endpoint in a message. Upon receiving an endpoint, the recipient can use xpc_connection_create_from_endpoint(_:)) to create as many distinct connections as necessary.

See Also

Endpoints

XPC_ERROR_CONNECTION_INTERRUPTED

Global Variable | XPC

An error that sends to the connection’s event handler when the remote service exits.

var XPC_ERROR_CONNECTION_INTERRUPTED: xpc_object_t { get }

Will be delivered to the connection’s event handler if the remote service exited. The connection is still live even in this case, and resending a message will cause the service to be launched on-demand. This error serves as a client’s indication that it should resynchronize any state that it had given the service.

Any messages in the queue to be sent will be unwound and canceled when this error occurs. In the case where a message waiting to be sent has a reply handler, that handler will be invoked with this error. In the context of the reply handler, this error indicates that a reply to the message will never arrive.

Messages that do not have reply handlers associated with them will be silently disposed of. This error will only be given to peer connections.

See Also

Errors

XPC_ERROR_CONNECTION_INVALID

Global Variable | XPC

An error that sends to the connection’s event handler to indicate that the connection is no longer usable.

var XPC_ERROR_CONNECTION_INVALID: xpc_object_t { get }

Will be delivered to the connection’s event handler if the named service provided to xpc_connection_create(_:_:)) could not be found in the XPC service namespace. The connection is useless and should be disposed of.

Any messages in the queue to be sent will be unwound and canceled when this error occurs, similarly to the behavior when XPC_ERROR_CONNECTION_INTERRUPTED occurs. The only difference is that the XPC_ERROR_CONNECTION_INVALID will be given to outstanding reply handlers and the connection’s event handler.

This error may be given to any type of connection.

See Also

Errors

XPC_ERROR_TERMINATION_IMMINENT

Global Variable | XPC

An error that sends to a peer connection’s event handler when the XPC runtime determines that the program needs to exit and that all outstanding transactions must wind down.

var XPC_ERROR_TERMINATION_IMMINENT: xpc_object_t { get }

This error will be delivered to a peer connection’s event handler when the XPC runtime has determined that the program should exit and that all outstanding transactions must be wound down, and no new transactions can be opened.

After this error has been delivered to the event handler, no more messages will be received by the connection. The runtime will still attempt to deliver outgoing messages, but this error should be treated as an indication that the program will exit very soon, and any outstanding business over the connection should be wrapped up as quickly as possible and the connection canceled shortly thereafter.

This error will only be delivered to peer connections received through a listener or the xpc_main(_:)) event handler.

See Also

Errors

xpc_finalizer_t

Type Alias | XPC

A function to invoke when tearing down a connection and freeing its context.

typealias xpc_finalizer_t = (UnsafeMutableRawPointer?) -> Void

It is not safe to reference the connection from within this function.

Parameters

  • value: The context object that is to be disposed of.

See Also

Context

xpc_handler_t

Type Alias | XPC

The type of block that the XPC connection APIs accept.

typealias xpc_handler_t = (xpc_object_t) -> Void

You aren’t responsible for releasing the event object.

See Also

Event handling

xpc_main(_:)

Function | XPC

Starts listening for incoming connections and processes them with the specified event handler.

func xpc_main(_ handler: xpc_connection_handler_t) -> Never

This is the springboard into the XPC service runtime. This function sets up your service bundle’s listener connection and manages it automatically. After this initial setup, this function calls dispatchMain()). You may override this behavior by setting the RunLoopType key in your XPC service bundle’s Info.plist under the XPCService dictionary.

Parameters

  • handler: The handler to accept new connections with.

See Also

Life cycle

xpc_transaction_begin()

Function | XPC

Informs the XPC runtime when a transaction begins, indicating that the service isn’t idle.

func xpc_transaction_begin()

A service with no outstanding transactions may automatically exit due to inactivity as determined by the system.

This function may be used to manually manage transactions in cases where their automatic management (as described below) does not meet the needs of an XPC service. This function also updates the transaction count used for sudden termination, i.e. vproc_transaction_begin(), and these two interfaces may be used in combination.

The XPC runtime will automatically begin a transaction on behalf of a service when a new message is received. If no reply message is expected, the transaction is automatically ended when the connection event handler returns. If a reply message is created, the transaction will end when the reply message is sent or released. An XPC service may use xpc_transaction_begin()) and xpc_transaction_end()) to inform the XPC runtime about activity that occurs outside of this common pattern.

When the XPC runtime has determined that the service should exit, the event handlers for all active listening and peer connections will receive XPC_ERROR_TERMINATION_IMMINENT as an indication that they should unwind their existing transactions. After this error is delivered to a connection’s event handler, no more messages will be delivered to the connection.

See Also

Life cycle

xpc_transaction_end()

Function | XPC

Informs the XPC runtime when a transaction ends.

func xpc_transaction_end()

As described in xpc_transaction_begin()), this API may be used interchangeably with vproc_transaction_end().

See the discussion for xpc_transaction_begin()) for details regarding the XPC runtime’s idle-exit policy.

See Also

Life cycle