← XPC

XPCListener

XPC Dokümantasyonu

A type that performs tasks for clients across process boundaries.

class XPCListener

To implement an XPC service, create a listener and respond to incoming session requests.

Creating a listener

  • init(service:targetQueue:options:incomingSessionHandler:)) init(service: String, targetQueue: DispatchQueue?, options: XPCListener.InitializationOptions, incomingSessionHandler: (XPCListener.IncomingSessionRequest) -> XPCListener.IncomingSessionRequest.Decision) throws — Creates the server side of an XPC service using the specified service name.
  • XPCListener.InitializationOptions struct InitializationOptions — Options that control the listener’s configuration, such as if it’s inactive at creation.
  • XPCListener.IncomingSessionRequest class IncomingSessionRequest — A session request from a client that you accept or reject.

Managing the life cycle

  • activate()) func activate() throws — Activates an inactive listener.
  • cancel()) func cancel() — Cancels a listener.

Handling incoming messages

  • XPCPeerHandler protocol XPCPeerHandler — A type that handles incoming messages from a client and session cancellation.

Initializers

  • init(service:targetQueue:options:requirement:incomingSessionHandler:)) convenience init(service: String, targetQueue: DispatchQueue?, options: XPCListener.InitializationOptions, requirement: XPCPeerRequirement, incomingSessionHandler: (XPCListener.IncomingSessionRequest) -> XPCListener.IncomingSessionRequest.Decision) throws — Creates a listener with the service defined by the provided name, and requires that the session peer has the specified requirement.
  • init(targetQueue:options:incomingSessionHandler:)) init(targetQueue: DispatchQueue?, options: XPCListener.InitializationOptions, incomingSessionHandler: (XPCListener.IncomingSessionRequest) -> XPCListener.IncomingSessionRequest.Decision) — Creates an anonymous listener

Instance Properties

  • endpoint var endpoint: XPCEndpoint — Creates an endpoint from the listener.

Relationships

Conforms To

See Also

Interprocess communication

activate()

Instance Method | XPC

Activates an inactive listener.

func activate() throws

If you create an inactive listener using the inactive flag, be sure to activate it before releasing the last reference to the listener. Releasing the last reference to an inactive listener crashes.

If activation fails, the system automatically cancels the listener.

See Also

Managing the life cycle

XPCListener.IncomingSessionRequest

Class | XPC

A session request from a client that you accept or reject.

class IncomingSessionRequest

When a client initiates a connection to a listener, the system passes the incoming session request to the listener. In response, the listener calls one of the accept methods to complete the connection with the client, or it rejects the request.

Responding to client sessions requests

  • accept(_:)-73k8w) func accept<Handler>((XPCSession) -> Handler) -> XPCListener.IncomingSessionRequest.Decision — Accepts an incoming session request from a client, delegating incoming encodable messages to a separate object.
  • accept(_:)-35eh9) func accept<Handler>((XPCSession) -> Handler) -> XPCListener.IncomingSessionRequest.Decision — Accepts an incoming session request from a client, delegating incoming received messages to a separate object.
  • accept(_:)-tkrp) func accept<Handler>((XPCSession) -> Handler) -> XPCListener.IncomingSessionRequest.Decision — Accepts an incoming session request from a client, delegating incoming dictionary messages to a separate object.
  • accept(incomingMessageHandler:cancellationHandler:)-56fch) func accept<Message>(incomingMessageHandler: (Message) -> (any Encodable)?, cancellationHandler: ((XPCRichError) -> Void)?) -> XPCListener.IncomingSessionRequest.Decision — Accepts an incoming session request from a client using closures to handle encodable messages or cancellation, and returns the inactive session.
  • accept(incomingMessageHandler:cancellationHandler:)-9oa3z) func accept(incomingMessageHandler: (XPCReceivedMessage) -> (any Encodable)?, cancellationHandler: ((XPCRichError) -> Void)?) -> XPCListener.IncomingSessionRequest.Decision — Accepts an incoming session request from a client using closures to handle received messages or cancellation, and returns the inactive session.
  • accept(incomingMessageHandler:cancellationHandler:)-8rodk) func accept(incomingMessageHandler: (XPCDictionary) -> XPCDictionary?, cancellationHandler: ((XPCRichError) -> Void)?) -> XPCListener.IncomingSessionRequest.Decision — Accepts an incoming session request from a client using closures to handle dictionary messages or cancellation, and returns the inactive session.
  • accept(incomingMessageHandler:cancellationHandler:)-50tzb) func accept<Message>(incomingMessageHandler: (Message) -> (any Encodable)?, cancellationHandler: ((XPCRichError) -> Void)?) -> (XPCListener.IncomingSessionRequest.Decision, XPCSession) — Accepts an incoming session request from a client using a closure to handle encodable messages, and returns the inactive session.
  • accept(incomingMessageHandler:cancellationHandler:)-6oelg) func accept(incomingMessageHandler: (XPCReceivedMessage) -> (any Encodable)?, cancellationHandler: ((XPCRichError) -> Void)?) -> (XPCListener.IncomingSessionRequest.Decision, XPCSession) — Accepts an incoming session request from a client using a closure to handle received messages, and returns the inactive session.
  • accept(incomingMessageHandler:cancellationHandler:)-48c3k) func accept(incomingMessageHandler: (XPCDictionary) -> XPCDictionary?, cancellationHandler: ((XPCRichError) -> Void)?) -> (XPCListener.IncomingSessionRequest.Decision, XPCSession) — Accepts an incoming session request from a client using a closure to handle dictionary messages, and returns the inactive session.
  • reject(reason:)) func reject(reason: String) -> XPCListener.IncomingSessionRequest.Decision — Rejects an incoming client session request.
  • XPCListener.IncomingSessionRequest.Decision struct Decision — An opaque type that indicates whether a listener accepts or rejects an incoming session request.

See Also

Creating a listener

endpoint

Instance Property | XPC

Creates an endpoint from the listener.

var endpoint: XPCEndpoint { get }

This returns a new endpoint struct that can be used to establish a connection with this listener.

cancel()

Instance Method | XPC

Cancels a listener.

func cancel()

Typically you don’t need to explicitly cancel a listener. When the server process exits, the system automatically cancels the listener. In rare circumstances, such as part of a testing infrastructure, you may want to cancel a listener to ensure it doesn’t receive any new messages. Be aware that canceling a listener causes peers attempting to connect to the service to hang.

See Also

Managing the life cycle

init(service:targetQueue:options:incomingSessionHandler:)

Initializer | XPC

Creates the server side of an XPC service using the specified service name.

@preconcurrency init(service: String, targetQueue: DispatchQueue? = nil, options: XPCListener.InitializationOptions = .none, incomingSessionHandler: @escaping @Sendable (XPCListener.IncomingSessionRequest) -> XPCListener.IncomingSessionRequest.Decision) throws

Listener creation fails if the XPC service isn’t found or is unavailable.

When a client connects to your service, the system invokes the incomingSessionHandler with a request that you must either accept or reject. To accept the incoming request, choose one of the following two approaches:

When the incomingSessionHandler returns, the system automatically activates the peer session unless you explicitly reject it or pass the inactive initialzation option.

Parameters

  • service: The Mach service or XPC service name that clients use to connect to the service.
  • targetQueue: The dispatch queue that events arrive on. This may be a concurrent queue. If nil, the listeners uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Configuration options for the listener, such as creating it in an inactive state.
  • incomingSessionHandler: A handler that the system calls when a client connects to the XPC service.

See Also

Creating a listener

init(service:targetQueue:options:requirement:incomingSessionHandler:)

Initializer | XPC

Creates a listener with the service defined by the provided name, and requires that the session peer has the specified requirement.

@preconcurrency convenience init(service: String, targetQueue: DispatchQueue? = nil, options: XPCListener.InitializationOptions = .none, requirement: XPCPeerRequirement, incomingSessionHandler: @escaping @Sendable (XPCListener.IncomingSessionRequest) -> XPCListener.IncomingSessionRequest.Decision) throws
  • service: The Mach service or XPC Service name to create the listener with.
  • requirement: The requirement the peer must have

Note: For a listener, requests that do not satisfy the requirement are dropped.

init(targetQueue:options:incomingSessionHandler:)

Initializer | XPC

Creates an anonymous listener

@preconcurrency init(targetQueue: DispatchQueue? = nil, options: XPCListener.InitializationOptions = .none, incomingSessionHandler: @escaping @Sendable (XPCListener.IncomingSessionRequest) -> XPCListener.IncomingSessionRequest.Decision)

Returns a new listener object. The returned listener is activated by default and will begin receiving incoming session requests

XPCListener.InitializationOptions

Structure | XPC

Options that control the listener’s configuration, such as if it’s inactive at creation.

struct InitializationOptions

Listener creation options

  • inactive static let inactive: XPCListener.InitializationOptions — Indicates that the listener isn’t activated during its creation.
  • none static let none: XPCListener.InitializationOptions — Indicates that the listener uses a default configuration during creation.

Relationships

Conforms To

See Also

Creating a listener

XPCPeerHandler

Protocol | XPC

A type that handles incoming messages from a client and session cancellation.

@preconcurrency protocol XPCPeerHandler : Sendable

Receiving client messages

  • handleIncomingRequest(_:)) func handleIncomingRequest(Self.Input) -> Self.Output? — A closure that receives a message from a client and optionally provides a reply.
  • Input associatedtype Input — A type that represents a message from a client.
  • Output associatedtype Output — A type that represents a response to an incoming request.

Responding to session cancellation

  • handleCancellation(error:)) func handleCancellation(error: XPCRichError) — A closure the system invokes when it cancels a session with a client.

Relationships

Inherits From

accept(_:)

Instance Method | XPC

Accepts an incoming session request from a client, delegating incoming encodable messages to a separate object.

func accept<Handler>(_ inactiveSessionHandler: (XPCSession) -> Handler) -> XPCListener.IncomingSessionRequest.Decision where Handler : XPCPeerHandler, Handler.Input : Decodable, Handler.Output == any Encodable

A decision that indicates whether the listener accepts or rejects the incoming session.

Parameters

  • inactiveSessionHandler: A closure that receives an inactive incoming session and returns an object to handle messages in the session.

See Also

Responding to client sessions requests

accept(_:)

Instance Method | XPC

Accepts an incoming session request from a client, delegating incoming dictionary messages to a separate object.

func accept<Handler>(_ inactiveSessionHandler: (XPCSession) -> Handler) -> XPCListener.IncomingSessionRequest.Decision where Handler : XPCPeerHandler, Handler.Input == XPCDictionary, Handler.Output == XPCDictionary

A decision that indicates whether the listener accepts or rejects the incoming session.

Parameters

  • inactiveSessionHandler: A closure that receives an inactive incoming session and returns an object to handle messages in the session.

See Also

Responding to client sessions requests

accept(_:)

Instance Method | XPC

Accepts an incoming session request from a client, delegating incoming received messages to a separate object.

func accept<Handler>(_ inactiveSessionHandler: (XPCSession) -> Handler) -> XPCListener.IncomingSessionRequest.Decision where Handler : XPCPeerHandler, Handler.Input == XPCReceivedMessage, Handler.Output == any Encodable

A decision that indicates whether the listener accepts or rejects the incoming session.

Parameters

  • inactiveSessionHandler: A closure that receives an inactive incoming session and returns an object to handle messages in the session.

See Also

Responding to client sessions requests

accept(incomingMessageHandler:cancellationHandler:)

Instance Method | XPC

Accepts an incoming session request from a client using a closure to handle encodable messages, and returns the inactive session.

@preconcurrency func accept<Message>(incomingMessageHandler: @escaping @Sendable (Message) -> (any Encodable)?, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) -> (XPCListener.IncomingSessionRequest.Decision, XPCSession) where Message : Decodable

A tuple that indicates whether the listener accepts or rejects the incoming session, and includes the inactive session.

Parameters

  • incomingMessageHandler: A closure that receives incoming messages from a client.
  • cancellationHandler: An optional closure that the system invokes when it cancels the session.

See Also

Responding to client sessions requests

accept(incomingMessageHandler:cancellationHandler:)

Instance Method | XPC

Accepts an incoming session request from a client using a closure to handle dictionary messages, and returns the inactive session.

@preconcurrency func accept(incomingMessageHandler: @escaping @Sendable (XPCDictionary) -> XPCDictionary?, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) -> (XPCListener.IncomingSessionRequest.Decision, XPCSession)

A tuple that indicates whether the listener accepts or rejects the incoming session, and includes the inactive session.

Parameters

  • incomingMessageHandler: A closure that receives incoming messages from a client.
  • cancellationHandler: An optional closure that the system invokes when it cancels the session.

See Also

Responding to client sessions requests

accept(incomingMessageHandler:cancellationHandler:)

Instance Method | XPC

Accepts an incoming session request from a client using closures to handle encodable messages or cancellation, and returns the inactive session.

@preconcurrency func accept<Message>(incomingMessageHandler: @escaping @Sendable (Message) -> (any Encodable)?, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) -> XPCListener.IncomingSessionRequest.Decision where Message : Decodable

A decision that indicates whether the listener accepts or rejects the incoming session.

Parameters

  • incomingMessageHandler: A closure that receives incoming messages from a client.
  • cancellationHandler: An optional closure that the system invokes when it cancels the session.

See Also

Responding to client sessions requests

accept(incomingMessageHandler:cancellationHandler:)

Instance Method | XPC

Accepts an incoming session request from a client using a closure to handle received messages, and returns the inactive session.

@preconcurrency func accept(incomingMessageHandler: @escaping @Sendable (XPCReceivedMessage) -> (any Encodable)?, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) -> (XPCListener.IncomingSessionRequest.Decision, XPCSession)

A tuple that indicates whether the listener accepts or rejects the incoming session, and includes the inactive session.

Parameters

  • incomingMessageHandler: A closure that receives incoming messages from a client.
  • cancellationHandler: An optional closure that the system invokes when it cancels the session.

See Also

Responding to client sessions requests

accept(incomingMessageHandler:cancellationHandler:)

Instance Method | XPC

Accepts an incoming session request from a client using closures to handle dictionary messages or cancellation, and returns the inactive session.

@preconcurrency func accept(incomingMessageHandler: @escaping @Sendable (XPCDictionary) -> XPCDictionary?, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) -> XPCListener.IncomingSessionRequest.Decision

A decision that indicates whether the listener accepts or rejects the incoming session.

Parameters

  • incomingMessageHandler: A closure that receives incoming messages from a client.
  • cancellationHandler: An optional closure that the system invokes when it cancels the session.

See Also

Responding to client sessions requests

XPCListener.IncomingSessionRequest.Decision

Structure | XPC

An opaque type that indicates whether a listener accepts or rejects an incoming session request.

struct Decision

When you create an XPCListener, you specify a closure that receives an XPCListener.IncomingSessionRequest. In that closure, you receive a Decision from the call to the request’s accept or reject methods. You don’t have to do anything with the decision other than return it from the closure.

See Also

Responding to client sessions requests

reject(reason:)

Instance Method | XPC

Rejects an incoming client session request.

func reject(reason: String) -> XPCListener.IncomingSessionRequest.Decision

A decision that indicates that the request was canceled.

Parameters

  • reason: A description of why the listener rejected the request.

See Also

Responding to client sessions requests

accept(incomingMessageHandler:cancellationHandler:)

Instance Method | XPC

Accepts an incoming session request from a client using closures to handle received messages or cancellation, and returns the inactive session.

@preconcurrency func accept(incomingMessageHandler: @escaping @Sendable (XPCReceivedMessage) -> (any Encodable)?, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) -> XPCListener.IncomingSessionRequest.Decision

A decision that indicates whether the listener accepts or rejects the incoming session.

Parameters

  • incomingMessageHandler: A closure that receives incoming messages from a client.
  • cancellationHandler: An optional closure that the system invokes when it cancels the session.

See Also

Responding to client sessions requests

none

Type Property | XPC

Indicates that the listener uses a default configuration during creation.

static let none: XPCListener.InitializationOptions

See Also

Listener creation options

handleCancellation(error:)

Instance Method | XPC

A closure the system invokes when it cancels a session with a client.

func handleCancellation(error: XPCRichError)

Parameters

  • error: A description of the reason for the session’s cancellation.

Default Implementations

XPCPeerHandler Implementations

inactive

Type Property | XPC

Indicates that the listener isn’t activated during its creation.

static let inactive: XPCListener.InitializationOptions

Important: If you create a listener with this option, you must manually activate it by calling activate()).

See Also

Listener creation options

handleIncomingRequest(_:)

Instance Method | XPC

A closure that receives a message from a client and optionally provides a reply.

func handleIncomingRequest(_: Self.Input) -> Self.Output?

A response message, if any, to send back to the client; otherwise nil.

See Also

Receiving client messages

Output

Associated Type | XPC

A type that represents a response to an incoming request.

associatedtype Output

See Also

Receiving client messages

Input

Associated Type | XPC

A type that represents a message from a client.

associatedtype Input

See Also

Receiving client messages

handleCancellation(error:)

Instance Method | XPC

A closure the system invokes when it cancels a session with a client.

func handleCancellation(error: XPCRichError)
Parameters
  • error: A description of the reason for the session’s cancellation.