NSXPCConnection Class Reference

Inherits from	NSObject
Conforms to	NSXPCProxyCreating NSObject (NSObject)
Framework	/System/Library/Frameworks/Foundation.framework
Availability	Available in OS X v10.8 and later.
Declared in	NSXPCConnection.h
Related sample code	AppSandboxLoginItemXPCDemo Sandboxing with NSXPCConnection

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.

Related Sample Code

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.

Related Sample Code

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.

Related Sample Code

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.

Related Sample Code

Sandboxing with NSXPCConnection

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.

Related Sample Code

Sandboxing with NSXPCConnection

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.

Related Sample Code

Sandboxing with NSXPCConnection

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

AppSandboxLoginItemXPCDemo

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.

Related Sample Code

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.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.