NSXPCConnection Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.8 and later.
Declared in
NSXPCConnection.h
Related sample code

Overview

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

This class is the primary means of creating and configuring the communication mechanism between two processes. Each process has one instance of this class to represent the endpoint in the communication channel.

Tasks

Creating Connections

Miscellaneous

Properties

auditSessionIdentifier

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

@property(readonly) au_asid_t auditSessionIdentifier
Discussion

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

effectiveGroupIdentifier

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

@property(readonly) gid_t effectiveGroupIdentifier
Discussion

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

effectiveUserIdentifier

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

@property(readonly) uid_t effectiveUserIdentifier
Discussion

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

endpoint

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

@property(readonly) NSXPCListenerEndpoint *endpoint
Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

exportedInterface

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

@property(retain) NSXPCInterface *exportedInterface
Discussion

This value is required if a exported object is set.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

exportedObject

An exported object for the connection.

@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.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

interruptionHandler

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

@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).

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

invalidationHandler

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

@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.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

processIdentifier

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

@property(readonly) pid_t processIdentifier
Discussion

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

remoteObjectInterface

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

@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.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

serviceName

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

@property(readonly) NSString *serviceName
Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

Instance Methods

initWithListenerEndpoint:

Initializes an NSXPCConnection object to connect to an NSXPCListener object in another process, identified by an NSXPCListenerEndpoint object.

- (id)initWithListenerEndpoint:(NSXPCListenerEndpoint *)endpoint
Parameters
endpoint

The desired listener endpoint for the service.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

initWithMachServiceName:options:

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

- (id)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.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

initWithServiceName:

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

- (id)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.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

invalidate

Invalidates the connection.

- (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.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

remoteObjectProxy

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

- (id)remoteObjectProxy
Discussion

See descriptions in NSXPCProxyCreating for more details.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

remoteObjectProxyWithErrorHandler:

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

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

See descriptions in NSXPCProxyCreating for more details.

Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSXPCConnection.h

resume

Starts or resumes handling of messages on a connection.

- (void)resume
Discussion

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

suspend

Suspends the connection.

- (void)suspend
Discussion

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSXPCConnection.h

Constants

NSXPCConnectionOptions

Options that you can pass to a connection.

enum {
NSXPCConnectionPrivileged = (1 << 12UL)
};
typedef NSUInteger NSXPCConnectionOptions;
Constants
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.

Declared in NSXPCConnection.h.