NSSocketPortNameServer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSPortNameServer.h

Overview

This port name server takes and returns instances of NSSocketPort.

Port removal functionality is supported by the removePortForName: method and should be used to remove invalid socket ports.

Unlike the other port name servers, NSSocketPortNameServer can operate over a network. By registering your socket ports, you make them available to other computers on the local network without hard-coding the TCP port numbers. Clients just need to know the name of the port.

NSPortNameServer is implemented using NSNetService and registers ports in the local network domain. The registered name of a port must be unique within the local domain, not just the local host. The name server only supports TCP/IP (either IPv4 or IPv6) sockets.

Tasks

Getting the Server Object

Looking Up Ports

Registering and Removing Ports

Configuring the Default Port Number

Class Methods

sharedInstance

Returns the shared socket port name server.

+ (id)sharedInstance
Return Value

The single instance of NSSocketPortNameServer with which you register and look up NSSocketPort objects.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h

Instance Methods

defaultNameServerPortNumber

Returns the port number used to contact the name server.

- (uint16_t)defaultNameServerPortNumber
Return Value

The port number used to contact the name server. This value is currently ignored.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h

portForName:

Looks up and returns the port registered under the specified name on the local host.

- (NSPort *)portForName:(NSString *)portName
Parameters
portName

The name of the desired port.

Return Value

The port associated with portName on the local host. Returns nil if no such port exists.

Discussion

Invokes portForName:host:nameServerPortNumber: with nil as the host name and 0 as the name server port number.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h

portForName:host:

Looks up and returns the port registered under the specified name on a specified host.

- (NSPort *)portForName:(NSString *)portName host:(NSString *)hostName
Parameters
portName

The name of the desired port.

hostName

The name of the host. hostName is an Internet domain name (for example, “sales.anycorp.com”). If hostName is nil or empty, the local host is checked.

Return Value

The port associated with portName on the host hostName. Returns nil if no such port exists.

Discussion

Invokes portForName:host:nameServerPortNumber: with 0 as the name server port number.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h

portForName:host:nameServerPortNumber:

Looks up and returns the port registered under the specified name on a specified host.

- (NSPort *)portForName:(NSString *)portName host:(NSString *)hostName nameServerPortNumber:(uint16_t)portNumber
Parameters
portName

The name of the desired port.

hostName

The name of the host. hostName is an Internet domain name (for example, “sales.anycorp.com”) or IP address (IPv4 or IPv6). If hostName is nil or empty, the local host is checked. If hostName is @"*", all hosts on the local network are checked.

portNumber

The portNumber parameter is ignored.

Return Value

The port associated with portName on the host hostName. Returns nil if no such port exists.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h

registerPort:name:

Registers a given port as a network service with the specified name in the local domain.

- (BOOL)registerPort:(NSPort *)port name:(NSString *)portName
Parameters
port

The port to make available.

portName

The name for the port.

Return Value

YES if successful, NO otherwise.

Discussion

Invokes registerPort:name:nameServerPortNumber: with 0 as the name server port number.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSPortNameServer.h

registerPort:name:nameServerPortNumber:

Registers a given port as a network service with the specified name in the local domain.

- (BOOL)registerPort:(NSPort *)port name:(NSString *)portName nameServerPortNumber:(uint16_t)portNumber
Parameters
port

The port to make available.

portName

The name for the port.

portNumber

The portNumber parameter is ignored.

Return Value

YES if successful, NO otherwise.

Special Considerations

If your application has already registered a port under the name portName, this method replaces it with port.

If the local domain already has a port named portName registered, this method could return YES before the name collision is detected. To detect a potential name collision, you can invoke portForName:host: with a host argument of @"*" to test if portName is already taken. This, however, leaves a race condition wherein another process can register a port under portName after portForName:host: returns but before you register port. If this is an unacceptable risk for your application, you can also invoke portForName:host: some finite time after registering your port to test if you get the same port back.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h

removePortForName:

Unregisters the port for a given name on the local host.

- (BOOL)removePortForName:(NSString *)portName
Parameters
portName

The name of the port to unregister.

Return Value

YES if successful, otherwise NO.

Discussion

If the operation is successful, the port can no longer be looked up using the name portName. Other applications that already have a reference to the port can continue to use it until it becomes invalid.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h

setDefaultNameServerPortNumber:

Sets the default port number used to contact the name server.

- (void)setDefaultNameServerPortNumber:(uint16_t)portNumber
Parameters
portNumber

The new port number used to contact the name server. This value is currently ignored.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSPortNameServer.h