Socket Name Server Utilities Reference

Framework	CoreFoundation/CoreFoundation.h
Declared in	CFSocket.h

Overview

Name server functionality is currently inoperable in OS X.

Functions

CFSocketCopyRegisteredSocketSignature

Returns a socket signature registered with a CFSocket name server.

CFSocketError CFSocketCopyRegisteredSocketSignature (
   const CFSocketSignature *nameServerSignature,
   CFTimeInterval timeout,
   CFStringRef name,
   CFSocketSignature *signature,
   CFDataRef *nameServerAddress
);

Parameters

nameServerSignature: The socket signature for the name server. If NULL, this function contacts the default server, which is assumed to be a local process using TCP/IP to listen on the port number returned from CFSocketGetDefaultNameRegistryPortNumber. If nameServerSignature is incomplete, the missing values are replaced with the default server’s values, if appropriate.
timeout: The time to wait for the server to accept a connection and to reply to the registration request.
name: The name of the registered socket signature to retrieve.
signature: A pointer to a CFSocketSignature structure into which the retrieved socket signature is copied.
nameServerAddress: A pointer to a CFData object into which the name server’s address is copied. Pass NULL if you do not want the server’s address.

Return Value

An error code indicating success or failure.

Discussion

Once you have the socket signature, you can open a connection to that socket with CFSocketCreateConnectedToSocketSignature.

Availability

Available in iOS 2.0 and later.

Declared In

CFSocket.h

CFSocketCopyRegisteredValue

Returns a value registered with a CFSocket name server.

CFSocketError CFSocketCopyRegisteredValue (
   const CFSocketSignature *nameServerSignature,
   CFTimeInterval timeout,
   CFStringRef name,
   CFPropertyListRef *value,
   CFDataRef *nameServerAddress
);

Parameters

nameServerSignature: The socket signature for the name server. If NULL, this function contacts the default server, which is assumed to be a local process using TCP/IP to listen on the port number returned from CFSocketGetDefaultNameRegistryPortNumber. If nameServerSignature is incomplete, the missing values are replaced with the default server’s values, if appropriate.
timeout: The time to wait for the server to accept a connection and to reply to the registration request.
name: The name of the registered value to return.
value: A pointer to the property list object into which the retrieved value should be copied.
nameServerAddress: A pointer to a CFData object into which the name server’s address is copied. Pass NULL if you do not want the server’s address.

Return Value

An error code indicating success or failure.

Availability

Available in iOS 2.0 and later.

Declared In

CFSocket.h

CFSocketGetDefaultNameRegistryPortNumber

Returns the default port number with which to connect to a CFSocket name server.

UInt16 CFSocketGetDefaultNameRegistryPortNumber (
   void
);

Return Value

The default port number with which to connect to a CFSocket name server.

Discussion

If you do not provide a name server signature or leave out the socket address in the signature when calling one of the name registry functions, such as CFSocketRegisterSocketSignature, the returned port number is used for the connection.

Availability

Available in iOS 2.0 and later.

Declared In

CFSocket.h

CFSocketRegisterSocketSignature

Registers a socket signature with a CFSocket name server.

CFSocketError CFSocketRegisterSocketSignature (
   const CFSocketSignature *nameServerSignature,
   CFTimeInterval timeout,
   CFStringRef name,
   const CFSocketSignature *signature
);

Parameters

nameServerSignature: The socket signature for the name server. If NULL, this function contacts the default server, which is assumed to be a local process using TCP/IP to listen on the port number returned from CFSocketGetDefaultNameRegistryPortNumber. If nameServerSignature is incomplete, the missing values are replaced with the default server’s values, if appropriate.
timeout: The time to wait for the server to accept a connection and to reply to the registration request.
name: The name with which to register signature.
signature: The socket signature to register.

Return Value

An error code indicating success or failure.

Discussion

Once a socket signature is registered, other processes can retrieve it with CFSocketCopyRegisteredSocketSignature and then open a connection to your socket using CFSocketCreateConnectedToSocketSignature.

To remove a registered socket signature from the name server, use CFSocketUnregister.

Availability

Available in iOS 2.0 and later.

Declared In

CFSocket.h

CFSocketRegisterValue

Registers a property-list value with a CFSocket name server.

CFSocketError CFSocketRegisterValue (
   const CFSocketSignature *nameServerSignature,
   CFTimeInterval timeout,
   CFStringRef name,
   CFPropertyListRef value
);

Parameters

nameServerSignature: The socket signature for the name server. If NULL, this function contacts the default server, which is assumed to be a local process using TCP/IP to listen on the port number returned from CFSocketGetDefaultNameRegistryPortNumber. If nameServerSignature is incomplete, the missing values are replaced with the default server’s values, if appropriate.
timeout: The time to wait for the server to accept a connection and to reply to the registration request.
name: The name with which to register value.
value: The property-list value to register.

Return Value

An error code indicating success or failure.

Discussion

To remove a registered value from the name server, use CFSocketUnregister.

Availability

Available in iOS 2.0 and later.

Declared In

CFSocket.h

CFSocketSetDefaultNameRegistryPortNumber

Sets the default port number with which to connect to a CFSocket name server.

void CFSocketSetDefaultNameRegistryPortNumber (
   UInt16 port
);

Parameters

port: The port number to use to connect to the CFSocket name server.

Discussion

Availability

Available in iOS 2.0 and later.

Declared In

CFSocket.h

CFSocketUnregister

Unregisters a value or socket signature with a CFSocket name server.

CFSocketError CFSocketUnregister (
   const CFSocketSignature *nameServerSignature,
   CFTimeInterval timeout,
   CFStringRef name
);

Parameters

nameServerSignature: The socket signature for the name server. If NULL, this function contacts the default server, which is assumed to be a local process using TCP/IP to listen on the port number returned from CFSocketGetDefaultNameRegistryPortNumber. If nameServerSignature is incomplete, the missing values are replaced with the default server’s values, if appropriate.
timeout: The time to wait for the server to accept a connection and to reply to the registration request.
name: The name of the property-list value or socket signature to unregister.

Return Value

An error code indicating success or failure.

Discussion

The value being unregistered was previously registered with CFSocketRegisterValue or CFSocketRegisterSocketSignature.

Availability

Available in iOS 2.0 and later.

Declared In

CFSocket.h

Constants

CFSocket Name Server Keys

Not used.

const CFStringRef kCFSocketCommandKey;
const CFStringRef kCFSocketNameKey;
const CFStringRef kCFSocketValueKey;
const CFStringRef kCFSocketResultKey;
const CFStringRef kCFSocketErrorKey;
const CFStringRef kCFSocketRegisterCommand;
const CFStringRef kCFSocketRetrieveCommand;