← XPC

XPCSession

XPC Dokümantasyonu

A type that sends messages to a server process.

class XPCSession

XPC sessions are stateful connections you use to send structured messages to a separate process. Once established, a session remains active until one side of the connection cancels it, at which point the system invalidates the connection.

Creating a session

  • init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-407h2) convenience init<Message>(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((Message) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to an XPC service with the name and decodable message handler you specify.
  • init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-9f4u0) convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCReceivedMessage) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to an XPC service with the name and received message handler you specify.
  • init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-bel3) convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCDictionary) -> XPCDictionary?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to an XPC service with the name and dictionary message handler you specify.
  • init(xpcService:targetQueue:options:cancellationHandler:)) convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to an XPC service with the name you specify.
  • init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-l3rz) convenience init<Message>(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((Message) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to a launch agent or launch daemon with the name and decodable message handler you specify.
  • init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-2xuyi) convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCReceivedMessage) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to a launch agent or launch daemon with the name and received message handler you specify.
  • init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-6jz7y) convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCDictionary) -> XPCDictionary?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to a launch agent or launch daemon with the name and dictionary message handler you specify.
  • init(machService:targetQueue:options:cancellationHandler:)) convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, cancellationHandler: ((XPCRichError) -> Void)?) throws — Establishes a connection to a launch agent or launch daemon with the name you specify.
  • XPCSession.InitializationOptions struct InitializationOptions — Options that control the session’s configuration.
  • setTargetQueue(_:)) func setTargetQueue(DispatchQueue) — Sets the target dispatch queue on an inactive session for processing messages.

Managing the life cycle

  • activate()) func activate() throws — Activates a session so you can send messages.
  • setIncomingMessageHandler(_:)-2ukdh) func setIncomingMessageHandler<Message>((Message) -> (any Encodable)?) — Sets a closure to receive incoming decodable messages for a session.
  • setIncomingMessageHandler(_:)-5lu26) func setIncomingMessageHandler((XPCReceivedMessage) -> (any Encodable)?) — Sets a closure to receive incoming received messages for a session.
  • setIncomingMessageHandler(_:)-75ou9) func setIncomingMessageHandler((XPCDictionary) -> XPCDictionary?) — Sets a closure to receive incoming dictionary messages for a session.
  • cancel(reason:)) func cancel(reason: String) — Cancels a session, discarding any unsent messages.
  • setCancellationHandler(_:)) func setCancellationHandler((XPCRichError) -> Void) — Sets a closure the session calls when it’s canceled.

Sending messages

  • send(_:)) func send<Message>(Message) throws — Sends an encodable message over the session to the destination service.
  • send(_:replyHandler:)-3wjln) func send<Message>(Message, replyHandler: (Result<XPCReceivedMessage, XPCRichError>) -> Void) throws — Sends an encodable message over the session to the destination service, using the closure you specify to handle a reply and rich error.
  • send(_:replyHandler:)-9an0u) func send<Message, Reply>(Message, replyHandler: (Result<Reply, any Error>) -> Void) throws — Sends an encodable message over the session to the destination service, using the closure you specify to handle a reply.
  • send(message:)) func send(message: XPCDictionary) throws — Sends a dictionary message over the session to the destination service.
  • send(message:replyHandler:)) func send(message: XPCDictionary, replyHandler: (Result<XPCDictionary, XPCRichError>) -> Void) — Sends a message asynchronously over the session to the destination service, calling a closure after receiving a reply.
  • sendSync(_:)-8a284) func sendSync<Message>(Message) throws -> XPCReceivedMessage — Sends an encodable message over the session to the destination service, blocking the caller until receiving a reply message.
  • sendSync(_:)-88u0s) func sendSync<Message, Reply>(Message) throws -> Reply — Sends an encodable message over the session to the destination service, blocking the caller until receiving an encodable reply message.
  • sendSync(message:)) func sendSync(message: XPCDictionary) throws -> XPCDictionary — Sends a dictionary message over the session to the destination service, blocking the caller until receiving a reply.

Initializers

Instance Methods

  • setPeerRequirement(_:)) func setPeerRequirement(XPCPeerRequirement) — Requires that the session peer has the specified requirement

Relationships

Conforms To

See Also

Interprocess communication

activate()

Instance Method | XPC

Activates a session so you can send messages.

func activate() throws

Important: Don’t call activate()) on a session that’s already active.

If you create an inactive session using the inactive initialization option, you must activate the session before deinitialization. Deinitializing an inactive session causes the process to crash.

If activation fails, this method automatically cancels the session and throws a XPCRichError that describes the reason activation failed.

See Also

Managing the life cycle

cancel(reason:)

Instance Method | XPC

Cancels a session, discarding any unsent messages.

func cancel(reason: String)

When you cancel a session, it discards any unsent messages and invalidates its connection. If there are messages awaiting replies, the session calls the reply handlers with an appropriate XPCRichError.

Parameters

  • reason: A description that explains why cancellation occured.

See Also

Managing the life cycle

init(endpoint:targetQueue:options:cancellationHandler:)

Initializer | XPC

Creates a new session object representing a connection to the xpc endpoint.

@preconcurrency convenience init(endpoint: XPCEndpoint, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

Returns a new session object. The returned session is activated by default and can be used to send messages.

Parameters

  • endpoint: The endpoint to create a session with.
  • targetQueue: The GCD queue onto which session events will be submitted. This may be a concurrent queue. This parameter is optional, if the target queue is not specified the target queue will be libdispatch’s default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Additional attributes which which to create the session.
  • cancellationHandler: The cancellation handler block that will be executed when this session is cancelled. This parameter is optional. See setCancellationHandler()

init(endpoint:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Creates a new session object representing a connection to the xpc endpoint.

@preconcurrency convenience init(endpoint: XPCEndpoint, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (XPCDictionary) -> XPCDictionary?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

Returns a new session object. The returned session is activated by default and can be used to send messages.

Parameters

  • endpoint: The endpoint to create a session with.
  • targetQueue: The GCD queue onto which session events will be submitted. This may be a concurrent queue. This parameter is optional, if the target queue is not specified the target queue will be libdispatch’s default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Additional attributes which which to create the session.
  • incomingMessageHandler: The handler block to be called when a message originated by the peer is received through the provided session. This parameter is optional. See setIncomingMessageHandler()
  • cancellationHandler: The cancellation handler block that will be executed when this session is cancelled. This parameter is optional. See setCancellationHandler()

init(endpoint:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Creates a new session object representing a connection to the xpc endpoint.

@preconcurrency convenience init(endpoint: XPCEndpoint, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (XPCReceivedMessage) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

Returns a new session object. The returned session is activated by default and can be used to send messages.

Parameters

  • endpoint: The endpoint to create a session with.
  • targetQueue: The GCD queue onto which session events will be submitted. This may be a concurrent queue. This parameter is optional, if the target queue is not specified the target queue will be libdispatch’s default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Additional attributes which which to create the session.
  • incomingMessageHandler: The handler block to be called when a message originated by the peer is received through the provided session. This parameter is optional. See setIncomingMessageHandler()
  • cancellationHandler: The cancellation handler block that will be executed when this session is cancelled. This parameter is optional. See setCancellationHandler()

init(endpoint:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Creates a new session object representing a connection to the xpc endpoint.

@preconcurrency convenience init<Message>(endpoint: XPCEndpoint, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (Message) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws where Message : Decodable

Returns a new session object. The returned session is activated by default and can be used to send messages.

Parameters

  • endpoint: The endpoint to create a session with.
  • targetQueue: The GCD queue onto which session events will be submitted. This may be a concurrent queue. This parameter is optional, if the target queue is not specified the target queue will be libdispatch’s default target queue, defined as DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Additional attributes which which to create the session.
  • incomingMessageHandler: The handler block to be called when a message originated by the peer is received through the provided session. This parameter is optional. See setIncomingMessageHandler()
  • cancellationHandler: The cancellation handler block that will be executed when this session is cancelled. This parameter is optional. See setCancellationHandler()

init(machService:targetQueue:options:cancellationHandler:)

Initializer | XPC

Establishes a connection to a launch agent or launch daemon with the name you specify.

@preconcurrency convenience init(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

If the service isn’t found or is unavailable, the connection fails and this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • machService: The name of the Mach service to connect to. The service name must exist in the Mach bootstrap accessible to the process and advertised in a launchd.plist.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Establishes a connection to a launch agent or launch daemon with the name and received message handler you specify.

@preconcurrency convenience init(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (XPCReceivedMessage) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

If the service isn’t found or is unavailable, the connection fails and this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • machService: The name of the Mach service to connect to. The service name must exist in the Mach bootstrap accessible to the process and advertised in a launchd.plist.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • incomingMessageHandler: A closure the system calls when a client initiates a connection to the server.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Establishes a connection to a launch agent or launch daemon with the name and dictionary message handler you specify.

@preconcurrency convenience init(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (XPCDictionary) -> XPCDictionary?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

If the service isn’t found or is unavailable, the connection fails and this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • machService: The name of the Mach service to connect to. The service name must exist in the Mach bootstrap accessible to the process and advertised in a launchd.plist.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • incomingMessageHandler: A closure the system calls when a client initiates a connection to the server.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Establishes a connection to a launch agent or launch daemon with the name and decodable message handler you specify.

@preconcurrency convenience init<Message>(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (Message) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws where Message : Decodable

If the service isn’t found or is unavailable, the connection fails and this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • machService: The name of the Mach service to connect to. The service name must exist in the Mach bootstrap accessible to the process and advertised in a launchd.plist.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • incomingMessageHandler: A closure the system calls when a client initiates a connection to the server.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(machService:targetQueue:options:requirement:cancellationHandler:)

Initializer | XPC

@preconcurrency convenience init(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

init(machService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

@preconcurrency convenience init<Message>(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, incomingMessageHandler: (@Sendable (Message) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws where Message : Decodable

init(machService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

@preconcurrency convenience init(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, incomingMessageHandler: (@Sendable (XPCReceivedMessage) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

init(machService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

@preconcurrency convenience init(machService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, incomingMessageHandler: (@Sendable (XPCDictionary) -> XPCDictionary?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Establishes a connection to an XPC service with the name and decodable message handler you specify.

@preconcurrency convenience init<Message>(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (Message) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws where Message : Decodable

If the service isn’t found or is unavailable, the connection fails and this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • xpcService: The name of the XPC service to connect to.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • incomingMessageHandler: A closure the system calls when a client initiates a connection to the server.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(xpcService:targetQueue:options:cancellationHandler:)

Initializer | XPC

Establishes a connection to an XPC service with the name you specify.

@preconcurrency convenience init(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

If the service isn’t found or is unavailable, the connection fails and this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • xpcService: The name of the XPC service to connect to.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Establishes a connection to an XPC service with the name and received message handler you specify.

@preconcurrency convenience init(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (XPCReceivedMessage) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

If the service isn’t found or is unavailable the connection fails, this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • xpcService: The name of the XPC service to connect to.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • incomingMessageHandler: A closure the system calls when a client initiates a connection to the server.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

Establishes a connection to an XPC service with the name and dictionary message handler you specify.

@preconcurrency convenience init(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, incomingMessageHandler: (@Sendable (XPCDictionary) -> XPCDictionary?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

If the service isn’t found or is unavailable, the connection fails and this method throws an error.

By default, this method activates the session it creates and the session is ready to accept messages. To create an inactive session, specify inactive in the options parameter.

Parameters

  • xpcService: The name of the XPC service to connect to.
  • targetQueue: The dispatch queue to use for session events. You can specify a concurrent dispatch queue. If you specify nil, the session uses DISPATCH_TARGET_QUEUE_DEFAULT.
  • options: Attributes the session uses when establishing the connection.
  • incomingMessageHandler: A closure the system calls when a client initiates a connection to the server.
  • cancellationHandler: A closure the system calls when it cancels a session.

See Also

Creating a session

init(xpcService:targetQueue:options:requirement:cancellationHandler:)

Initializer | XPC

Creates a new session object representing a connection to the named service, and requires that the session peer has the specified requirement.

@preconcurrency convenience init(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws
  • requirement: The requirement the peer must have

Note: All messages received on this session will be checked to ensure that they come from a peer who satisfies the requirement. When a reply is expected on the session and the peer does not satisfy the requirement, the session will be canceled and user’s cancelation handler will be invoked with XPCRichError describing the code signing error.

init(xpcService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

@preconcurrency convenience init(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, incomingMessageHandler: (@Sendable (XPCReceivedMessage) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

init(xpcService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

@preconcurrency convenience init(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, incomingMessageHandler: (@Sendable (XPCDictionary) -> XPCDictionary?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws

init(xpcService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)

Initializer | XPC

@preconcurrency convenience init<Message>(xpcService: String, targetQueue: DispatchQueue? = nil, options: XPCSession.InitializationOptions = .none, requirement: XPCPeerRequirement, incomingMessageHandler: (@Sendable (Message) -> (any Encodable)?)? = nil, cancellationHandler: (@Sendable (XPCRichError) -> Void)? = nil) throws where Message : Decodable

XPCSession.InitializationOptions

Structure | XPC

Options that control the session’s configuration.

struct InitializationOptions

Session creation options

  • inactive static let inactive: XPCSession.InitializationOptions — Indicates that the session isn’t activated during its creation.
  • privileged static let privileged: XPCSession.InitializationOptions — Indicates that the Mach service is in the priviledged Mach bootstrap.
  • none static let none: XPCSession.InitializationOptions — Indicates that the listener uses a default configuration during creation.

Relationships

Conforms To

See Also

Creating a session

send(_:)

Instance Method | XPC

Sends an encodable message over the session to the destination service.

func send<Message>(_ message: Message) throws where Message : Encodable

Sessions send messages serially in a first-in, first-out (FIFO) order. This method is safe to call from multiple dispatch queues. The session can’t indicate whether the message *delivery* is successful or not. While the session may successfully enqueue the message at the remote end of the connection, there’s no guarantee about when the destination dequeues the message and invokes the receiving session’s handler.

If the session fails to send the message, this method throws an error that contains details about the failure.

Important: If you create an inactive session, you must activate it before sending messages. Calling this method with an inactive session crashes.

Parameters

  • message: An encodable object that contains the message to send.

See Also

Sending messages

send(_:replyHandler:)

Instance Method | XPC

Sends an encodable message over the session to the destination service, using the closure you specify to handle a reply and rich error.

@preconcurrency func send<Message>(_ message: Message, replyHandler: @escaping @Sendable (Result<XPCReceivedMessage, XPCRichError>) -> Void) throws where Message : Encodable

Sessions send messages serially in a first-in, first-out (FIFO) order. This method is safe to call from multiple dispatch queues. The session can’t indicate whether the message *delivery* is successful or not. While the session may successfully enqueue the message at the remote end of the connection, there’s no guarantee about when the destination dequeues the message and invokes the receiving session’s handler.

If the session fails to send the message, this method throws an error that contains details about the failure.

If the system tears down the session’s connection before receiving a reply, it invokes replyHandler with a result containing an XPCRichError describing the failure. For example, the remote service exits prematurely before sending a reply.

Important: If you create an inactive session, you must activate it before sending messages. Calling this method with an inactive session crashes.

Parameters

  • message: An encodable object that contains the message to send.
  • replyHandler: A closure that receives a reply, and error if one occurs, that the service sends back.

See Also

Sending messages

send(message:replyHandler:)

Instance Method | XPC

Sends a message asynchronously over the session to the destination service, calling a closure after receiving a reply.

@preconcurrency func send(message: XPCDictionary, replyHandler: @escaping @Sendable (Result<XPCDictionary, XPCRichError>) -> Void)

Sessions send messages serially in a first-in, first-out (FIFO) order. This method is safe to call from multiple dispatch queues. The session can’t indicate whether the message *delivery* is successful or not. While the session may successfully enqueue the message at the remote end of the connection, there’s no guarantee about when the destination dequeues the message and invokes the receiving session’s handler.

If the session fails to send the message, this method throws an error that contains details about the failure.

If the system tears down the session’s connection before receiving a reply, it invokes replyHandler with a result containing an XPCRichError describing the failure. For example, the remote service exits prematurely before sending a reply.

Important: If you create an inactive session, you must activate it before sending messages. Calling this method with an inactive session crashes.

Parameters

  • message: A dictionary object that contains the message to send.
  • replyHandler: A closure the session invokes when it receives a reply. The closure takes a result parameter that contains either the reply that the destination sent back or an error describing a failure.

See Also

Sending messages

send(_:replyHandler:)

Instance Method | XPC

Sends an encodable message over the session to the destination service, using the closure you specify to handle a reply.

@preconcurrency func send<Message, Reply>(_ message: Message, replyHandler: @escaping @Sendable (Result<Reply, any Error>) -> Void) throws where Message : Encodable, Reply : Decodable

Sessions send messages serially in a first-in, first-out (FIFO) order. This method is safe to call from multiple dispatch queues. The session can’t indicate whether the message *delivery* is successful or not. While the session may successfully enqueue the message at the remote end of the connection, there’s no guarantee about when the destination dequeues the message and invokes the receiving session’s handler.

If the session fails to send the message, this method throws an error that contains details about the failure.

If the system tears down the session’s connection before receiving a reply, it invokes replyHandler with a result containing an XPCRichError describing the failure. For example, the remote service exits prematurely before sending a reply.

Important: If you create an inactive session, you must activate it before sending messages. Calling this method with an inactive session crashes.

Parameters

  • message: An encodable object that contains the message to send.
  • replyHandler: A closure that receives a reply, and error if one occurs, that the service sends back.

See Also

Sending messages

send(message:)

Instance Method | XPC

Sends a dictionary message over the session to the destination service.

func send(message: XPCDictionary) throws

Sessions send messages serially in a first-in, first-out (FIFO) order. This method is safe to call from multiple dispatch queues. The session can’t indicate whether the message *delivery* is successful or not. While the session may successfully enqueue the message at the remote end of the connection, there’s no guarantee about when the destination dequeues the message and invokes the receiving session’s handler.

If the session fails to send the message, this method throws an error that contains details about the failure.

Important: If you create an inactive session, you must activate it before sending messages. Calling this method with an inactive session crashes.

Parameters

  • message: A dictionary object that contains the message to send.

See Also

Sending messages

sendSync(_:)

Instance Method | XPC

Sends an encodable message over the session to the destination service, blocking the caller until receiving an encodable reply message.

func sendSync<Message, Reply>(_ message: Message) throws -> Reply where Message : Encodable, Reply : Decodable

If successful, the response to the message; otherwise this method throws an error.

Parameters

  • message: An encodable object that contains the message to send.

See Also

Sending messages

sendSync(_:)

Instance Method | XPC

Sends an encodable message over the session to the destination service, blocking the caller until receiving a reply message.

func sendSync<Message>(_ message: Message) throws -> XPCReceivedMessage where Message : Encodable

If successful, the response to the message; otherwise this method throws an error.

Parameters

  • message: An encodable object that contains the message to send.

See Also

Sending messages

sendSync(message:)

Instance Method | XPC

Sends a dictionary message over the session to the destination service, blocking the caller until receiving a reply.

func sendSync(message: XPCDictionary) throws -> XPCDictionary

If successful, the response to the message; otherwise this method throws an error.

Parameters

  • message: A dictionary object that contains the message to send.

See Also

Sending messages

setCancellationHandler(_:)

Instance Method | XPC

Sets a closure the session calls when it’s canceled.

@preconcurrency func setCancellationHandler(_ cancellationHandler: @escaping @Sendable (XPCRichError) -> Void)

Important: Only call this method on an inactive session.

Parameters

  • cancellationHandler: A closure that receives an error indicating why the session was canceled.

See Also

Managing the life cycle

setIncomingMessageHandler(_:)

Instance Method | XPC

Sets a closure to receive incoming decodable messages for a session.

@preconcurrency func setIncomingMessageHandler<Message>(_ incomingMessageHandler: @escaping @Sendable (Message) -> (any Encodable)?) where Message : Decodable

Important: Only call this method on an inactive session.

Parameters

  • incomingMessageHandler: A closure that the session invokes when it receives messages. The closure has a parameter that contains the message from the client, and optionally returns an encodable reply message to returns to the client. If the closure returns nil, you can use send(message:)) to reply asynchronously after the closure completes.

See Also

Managing the life cycle

setIncomingMessageHandler(_:)

Instance Method | XPC

Sets a closure to receive incoming received messages for a session.

@preconcurrency func setIncomingMessageHandler(_ incomingMessageHandler: @escaping @Sendable (XPCReceivedMessage) -> (any Encodable)?)

Important: Only call this method on an inactive session.

Parameters

  • incomingMessageHandler: A closure that the session invokes when it receives messages. The closure has a parameter that contains the message from the client, and optionally returns an encodable reply message to returns to the client. If the closure returns nil, you can use send(message:)) to reply asynchronously after the closure completes.

See Also

Managing the life cycle

setIncomingMessageHandler(_:)

Instance Method | XPC

Sets a closure to receive incoming dictionary messages for a session.

@preconcurrency func setIncomingMessageHandler(_ incomingMessageHandler: @escaping @Sendable (XPCDictionary) -> XPCDictionary?)

Important: Only call this method on an inactive session.

Parameters

  • incomingMessageHandler: A closure that the session invokes when it receives messages. The closure has a parameter that contains the message from the client, and optionally returns a dictionary reply message to returns to the client. If the closure returns nil, you can use send(message:)) to reply asynchronously after the closure completes.

See Also

Managing the life cycle

setPeerRequirement(_:)

Instance Method | XPC

Requires that the session peer has the specified requirement

func setPeerRequirement(_ requirement: XPCPeerRequirement)
  • requirement: The requirement the peer must have

Note: The session must be inactive to set a peer requirement. It is a programming error to call multiple of the setPeerRequirement method on the same session.

Note: All messages received on this session will be checked to ensure that they come from a peer who satisfies the requirement. When a reply is expected on the session and the peer does not satisfy the requirement, the session will be canceled and user’s cancelation handler will be invoked with XPCRichError describing the code signing error.

setTargetQueue(_:)

Instance Method | XPC

Sets the target dispatch queue on an inactive session for processing messages.

func setTargetQueue(_ targetQueue: DispatchQueue)

Parameters

  • targetQueue: The dispatch queue where the session processes messages. The target queue can be a concurrent queue.

See Also

Creating a session

none

Type Property | XPC

Indicates that the listener uses a default configuration during creation.

static let none: XPCSession.InitializationOptions

See Also

Session creation options

inactive

Type Property | XPC

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

static let inactive: XPCSession.InitializationOptions

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

See Also

Session creation options

privileged

Type Property | XPC

Indicates that the Mach service is in the priviledged Mach bootstrap.

static let privileged: XPCSession.InitializationOptions

The Mach service typically accomplishes this by placing its launchd.plist in the LaunchDaemons directory.

See Also

Session creation options