NSXPCListener 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 NSXPCListener class and its delegate are responsible for waiting for new incoming connections, configuring them, and accepting or rejecting them.

Each XPC service, launchd agent, or launchd daemon typically has at least one NSXPCListener object that listens for connections to a specified service name. Each listener must have a delegate that conforms to the NSXPCListenerDelegate protocol. When the listener receives a new connection request, it creates a new NSXPCConnection object, then asks the delegate to inspect, configure, and resume the connection object by calling the delegate's listener:shouldAcceptNewConnection: method.

Tasks

Miscellaneous

Properties

delegate

The delegate for the listener.

@property (assign) id <NSXPCListenerDelegate> delegate;
Discussion

If no delegate is set, all new connections are rejected. See the documentation for NSXPCListenerDelegate for implementation details.

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

Class Methods

anonymousListener

Returns a new anonymous listener connection.

+ (id)anonymousListener;
Discussion

Other processes can connect to this listener by passing this listener object's NSXPCListenerEndpoint to the initWithListenerEndpoint: method of an NSXPCConnection object.

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

serviceListener

Returns the singleton listener used to listen for incoming connections in an XPC service.

+ (id)serviceListener;
Discussion

Calling the resume method on the returned object starts the listener and never returns. This method is typically called at the end of your main function.

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

Instance Methods

endpoint

Returns an endpoint object that may be sent over an existing connection.

- (NSXPCListenerEndpoint *)endpoint;
Discussion

The receiver of the endpoint can use this object to create a new connection to this NSXPCListener object. The resulting NSXPCListenerEndpoint object uniquely names this listener object across connections.

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

initWithMachServiceName:

Initializes a listener in a LaunchAgent or LaunchDaemon which has a name advertised in a launchd.plist file.

- (id)initWithMachServiceName:(NSString *)name;
Discussion

For example, you might use this in an agent launched by launchd with a launchd.plist contained in ~/Library/LaunchAgents, or a daemon launched by launchd with a launchd.plist contained in /Library/LaunchDaemons.

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

invalidate

Invalidates the listener.

- (void)invalidate;
Discussion

After calling this method, no more connections are created. Once a listener is invalidated it may not be resumed or suspended.

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

resume

Starts processing of incoming requests.

- (void)resume;
Discussion

All listeners start suspended and must be resumed before they begin processing incoming requests.

If called on the serviceListener object, this method never returns. Therefore, you should call it as the last step inside the XPC service's main function after setting up any desired initial state and configuring the listener itself.

If called on any other NSXPCListener, the connection is resumed, and the method returns immediately.

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

suspend

Suspends the listener.

- (void)suspend;
Discussion

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

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