Mac Developer Library

Developer

Foundation Framework Reference NSXPCConnection Class Reference

Options
Deployment Target:

On This Page
Language:

NSXPCConnection

The NSXPCConnection class provides a bi-directional communication channel between two processes. More...

Inheritance


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.8 and later.
  • Initializes an NSXPCConnection object to connect to an NSXPCListener object in another process, identified by an NSXPCListenerEndpoint object.

    Declaration

    Swift

    init(listenerEndpoint endpoint: NSXPCListenerEndpoint)

    Objective-C

    - (instancetype)initWithListenerEndpoint:(NSXPCListenerEndpoint *)endpoint

    Parameters

    endpoint

    The desired listener endpoint for the service.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Initializes an NSXPCConnection object to connect to a LaunchAgent or LaunchDaemon with a name advertised in a launchd.plist.

    Declaration

    Swift

    init(machServiceName name: String, options options: NSXPCConnectionOptions)

    Objective-C

    - (instancetype)initWithMachServiceName:(NSString *)name options:(NSXPCConnectionOptions)options

    Discussion

    For example, if an agent is managed with launchd and has a launchd.plist in ~/Library/LaunchAgents, this method would create a connection to that agent. The agent should use NSXPCListener to wait for new connections.

    If the connection is being made to a process that is running in a privileged Mach bootstrap context (for example, a daemon started by a launchd property list in /Library/LaunchDaemons), then pass the NSXPCConnectionPrivileged option.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Initializes an NSXPCConnection object to connect to an NSXPCListener object in an XPC service, identified by a service name.

    Declaration

    Swift

    init(serviceName serviceName: String)

    Objective-C

    - (instancetype)initWithServiceName:(NSString *)serviceName

    Discussion

    XPC services are helper processes that are usually part of your application bundle. The service should use NSXPCListener to wait for new connections.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Invalidates the connection.

    Declaration

    Swift

    func invalidate()

    Objective-C

    - (void)invalidate

    Discussion

    When you call this method, all outstanding reply blocks, error handling blocks, and invalidation blocks are called on the message handling queue. The connection must be invalidated before it is deallocated. After a connection is invalidated, no more messages may be sent or received.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Returns a proxy for the remote object (that is, the exportedObject from the other side of this connection).

    Declaration

    Swift

    var remoteObjectProxy: AnyObject { get }

    Objective-C

    @property(readonly, retain) id remoteObjectProxy

    Discussion

    See descriptions in NSXPCProxyCreating for more details.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Returns a proxy for the remote object (that is, the object exported from the other side of this connection) with the specified error handler.

    Declaration

    Swift

    func remoteObjectProxyWithErrorHandler(_ handler: (NSError!) -> Void) -> AnyObject

    Objective-C

    - (id)remoteObjectProxyWithErrorHandler:(void (^)(NSError *error))handler

    Discussion

    See descriptions in NSXPCProxyCreating for more details.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Starts or resumes handling of messages on a connection.

    Declaration

    Swift

    func resume()

    Objective-C

    - (void)resume

    Discussion

    All connections start suspended. You must resume them before they start processing received messages or sending messages through the remoteObjectProxy object.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Suspends the connection.

    Declaration

    Swift

    func suspend()

    Objective-C

    - (void)suspend

    Discussion

    Suspends and resumes must be balanced before the connection may be invalidated.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The name of the XPC service that this connection was configured to connect to. (read-only)

    Declaration

    Swift

    var serviceName: String? { get }

    Objective-C

    @property(readonly, copy) NSString *serviceName

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Defines the NSXPCInterface object that describes the protocol for the object represented by the remoteObjectProxy.

    Declaration

    Swift

    var remoteObjectInterface: NSXPCInterface?

    Objective-C

    @property(retain) NSXPCInterface *remoteObjectInterface

    Discussion

    The proxy represents the exportedObject on the NSXPCConnection in the other process.

    This value is required if messages are sent over this connection.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The process ID (PID) of the connecting process. (read-only)

    Declaration

    Swift

    var processIdentifier: pid_t { get }

    Objective-C

    @property(readonly) pid_t processIdentifier

    Discussion

    This attribute may be used by the listener delegate to accept or reject connections.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • An invalidation handler that is called if the connection can not be formed or the connection has terminated and may not be re-established.

    Declaration

    Swift

    var invalidationHandler: (() -> Void)?

    Objective-C

    @property(copy) void (^invalidationHandler)(void)

    Discussion

    This handler is invoked on the same queue as reply messages and other handlers, and is always executed last (after the interruption handler, if required). You may not send messages over the connection from within an invalidation handler block.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • An interruption handler that is called if the remote process exits or crashes.

    Declaration

    Swift

    var interruptionHandler: (() -> Void)?

    Objective-C

    @property(copy) void (^interruptionHandler)(void)

    Discussion

    It may be possible to re-establish the connection by simply sending another message. The handler is invoked on the same queue as reply messages and other handlers, and it is always executed after any other messages or reply block handlers (except for the invalidation handler).

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • An exported object for the connection.

    Declaration

    Swift

    var exportedObject: AnyObject?

    Objective-C

    @property(retain) id exportedObject

    Discussion

    Messages sent to the remoteObjectProxy object from the other side of the connection are dispatched to this object. Messages delivered to exported objects are serialized and sent on a non-main queue. The receiver is responsible for handling the messages on a different queue or thread if it is required.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The NSXPCInterface object that describes the protocol for the exported object on this connection.

    Declaration

    Swift

    var exportedInterface: NSXPCInterface?

    Objective-C

    @property(retain) NSXPCInterface *exportedInterface

    Discussion

    This value is required if a exported object is set.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • endpoint endpoint Property

    If the connection was created with an NSXPCListenerEndpoint object, returns the endpoint object used. (read-only)

    Declaration

    Swift

    var endpoint: NSXPCListenerEndpoint { get }

    Objective-C

    @property(readonly, retain) NSXPCListenerEndpoint *endpoint

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The effective user ID (EUID) of the connecting process. (read-only)

    Declaration

    Swift

    var effectiveUserIdentifier: uid_t { get }

    Objective-C

    @property(readonly) uid_t effectiveUserIdentifier

    Discussion

    This attribute may be used by the listener delegate to accept or reject connections.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The effective group ID (EGID) of the connecting process. (read-only)

    Declaration

    Swift

    var effectiveGroupIdentifier: gid_t { get }

    Objective-C

    @property(readonly) gid_t effectiveGroupIdentifier

    Discussion

    This attribute may be used by the listener delegate to accept or reject connections.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • The BSM audit session identifier for the connecting process. (read-only)

    Declaration

    Swift

    var auditSessionIdentifier: au_asid_t { get }

    Objective-C

    @property(readonly) au_asid_t auditSessionIdentifier

    Discussion

    This attribute may be used by the listener delegate to accept or reject connections.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Options that you can pass to a connection.

    Declaration

    Swift

    struct NSXPCConnectionOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Privileged: NSXPCConnectionOptions { get } }

    Objective-C

    enum { NSXPCConnectionPrivileged = (1 << 12UL ) }; typedef NSUInteger NSXPCConnectionOptions;

    Constants

    • Privileged

      NSXPCConnectionPrivileged

      Use this option if connecting to a service in the privileged Mach bootstrap (for example, a daemon with a launchd.plist in /Library/LaunchDaemons).

      Available in OS X v10.8 and later.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.