<!--
{
  "availability" : [
    "iOS: 17.0.0 -",
    "iPadOS: 17.0.0 -",
    "macCatalyst: -",
    "macOS: 14.0.0 -",
    "tvOS: 17.0.0 -",
    "visionOS: -",
    "watchOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "XPC",
  "identifier" : "/documentation/XPC/XPCSession",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "XPC"
    ],
    "preciseIdentifier" : "s:3XPC10XPCSessionC"
  },
  "title" : "XPCSession"
}
-->

# XPCSession

A type that sends messages to a server process.

```
class XPCSession
```

## Overview

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.

## Topics

### Creating a session

[`convenience init<Message>(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((Message) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-407h2)

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

[`convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCReceivedMessage) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-9f4u0)

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

[`convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCDictionary) -> XPCDictionary?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-bel3)

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

[`convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:cancellationHandler:))

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

[`convenience init<Message>(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((Message) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-l3rz)

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

[`convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCReceivedMessage) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-2xuyi)

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

[`convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCDictionary) -> XPCDictionary?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:incomingMessageHandler:cancellationHandler:)-6jz7y)

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

[`convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:cancellationHandler:))

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

[`struct InitializationOptions`](/documentation/XPC/XPCSession/InitializationOptions)

Options that control the session’s configuration.

[`func setTargetQueue(DispatchQueue)`](/documentation/XPC/XPCSession/setTargetQueue(_:))

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

### Managing the life cycle

[`func activate() throws`](/documentation/XPC/XPCSession/activate())

Activates a session so you can send messages.

[`func setIncomingMessageHandler<Message>((Message) -> (any Encodable)?)`](/documentation/XPC/XPCSession/setIncomingMessageHandler(_:)-2ukdh)

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

[`func setIncomingMessageHandler((XPCReceivedMessage) -> (any Encodable)?)`](/documentation/XPC/XPCSession/setIncomingMessageHandler(_:)-5lu26)

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

[`func setIncomingMessageHandler((XPCDictionary) -> XPCDictionary?)`](/documentation/XPC/XPCSession/setIncomingMessageHandler(_:)-75ou9)

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

[`func cancel(reason: String)`](/documentation/XPC/XPCSession/cancel(reason:))

Cancels a session, discarding any unsent messages.

[`func setCancellationHandler((XPCRichError) -> Void)`](/documentation/XPC/XPCSession/setCancellationHandler(_:))

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

### Sending messages

[`func send<Message>(Message) throws`](/documentation/XPC/XPCSession/send(_:))

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

[`func send<Message>(Message, replyHandler: (Result<XPCReceivedMessage, XPCRichError>) -> Void) throws`](/documentation/XPC/XPCSession/send(_:replyHandler:)-3wjln)

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

[`func send<Message, Reply>(Message, replyHandler: (Result<Reply, any Error>) -> Void) throws`](/documentation/XPC/XPCSession/send(_:replyHandler:)-9an0u)

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

[`func send(message: XPCDictionary) throws`](/documentation/XPC/XPCSession/send(message:))

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

[`func send(message: XPCDictionary, replyHandler: (Result<XPCDictionary, XPCRichError>) -> Void)`](/documentation/XPC/XPCSession/send(message:replyHandler:))

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

[`func sendSync<Message>(Message) throws -> XPCReceivedMessage`](/documentation/XPC/XPCSession/sendSync(_:)-8a284)

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

[`func sendSync<Message, Reply>(Message) throws -> Reply`](/documentation/XPC/XPCSession/sendSync(_:)-88u0s)

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

[`func sendSync(message: XPCDictionary) throws -> XPCDictionary`](/documentation/XPC/XPCSession/sendSync(message:))

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

### Initializers

[`convenience init(endpoint: XPCEndpoint, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(endpoint:targetQueue:options:cancellationHandler:))

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

[`convenience init(endpoint: XPCEndpoint, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCDictionary) -> XPCDictionary?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(endpoint:targetQueue:options:incomingMessageHandler:cancellationHandler:)-2jmkk)

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

[`convenience init(endpoint: XPCEndpoint, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((XPCReceivedMessage) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(endpoint:targetQueue:options:incomingMessageHandler:cancellationHandler:)-546jo)

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

[`convenience init<Message>(endpoint: XPCEndpoint, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, incomingMessageHandler: ((Message) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(endpoint:targetQueue:options:incomingMessageHandler:cancellationHandler:)-6zd1x)

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

[`convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:requirement:cancellationHandler:))

[`convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, incomingMessageHandler: ((XPCDictionary) -> XPCDictionary?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)-5pk9g)

[`convenience init<Message>(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, incomingMessageHandler: ((Message) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)-7o5oq)

[`convenience init(machService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, incomingMessageHandler: ((XPCReceivedMessage) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(machService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)-84ll1)

[`convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:requirement:cancellationHandler:))

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

[`convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, incomingMessageHandler: ((XPCDictionary) -> XPCDictionary?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)-3p0jf)

[`convenience init(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, incomingMessageHandler: ((XPCReceivedMessage) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)-6jxdc)

[`convenience init<Message>(xpcService: String, targetQueue: DispatchQueue?, options: XPCSession.InitializationOptions, requirement: XPCPeerRequirement, incomingMessageHandler: ((Message) -> (any Encodable)?)?, cancellationHandler: ((XPCRichError) -> Void)?) throws`](/documentation/XPC/XPCSession/init(xpcService:targetQueue:options:requirement:incomingMessageHandler:cancellationHandler:)-osu4)

### Instance Methods

[`func setPeerRequirement(XPCPeerRequirement)`](/documentation/XPC/XPCSession/setPeerRequirement(_:))

Requires that the session peer has the specified requirement

## Relationships

### Conforms To

[`Sendable`](/documentation/Swift/Sendable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Copyable`](/documentation/Swift/Copyable)

[`Escapable`](/documentation/Swift/Escapable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)