CFHost Reference

Overview

The CFHost API allows you to create instances of the CFHost object that you can use to acquire host information, including names, addresses, and reachability information.

The process of acquiring information about a host is known as resolution. Begin by calling CFHostCreateWithAddress or CFHostCreateWithName to create an instance of a CFHost using an address or a name, respectively. If you want to resolve the host asynchronously. call CFHostSetClient to associate your client context and user-defined callback function with the host. Then call CFHostScheduleWithRunLoop to schedule the host on a run loop.

To start resolution, call CFHostStartInfoResolution. If you set up for asynchronous resolution, CFHostStartInfoResolution returns immediately. Your callback function will be called when resolution is complete. If you didn’t set up for asynchronous resolution, CFHostStartInfoResolution blocks until resolution is complete, an error occurs, or the resolution is cancelled.

When resolution is complete, call CFHostGetAddressing or CFHostGetNames to get an array of known addresses or known names, respectively, for the host. Call CFHostGetReachability to get flags, declared in SystemConfiguration/SCNetwork.h, that describe the reachability of the host.

When you no longer need a CFHost object, call CFHostUnscheduleFromRunLoop and CFHostSetClient to disassociate the host from your user-defined client context and callback function (if it was set up for asynchronous resolution). Then dispose of it.

Functions by Task

Creating a host

• CFHostCreateCopy
• CFHostCreateWithAddress
• CFHostCreateWithName

CFHost Functions

• CFHostCancelInfoResolution
• CFHostGetAddressing
• CFHostGetNames
• CFHostGetReachability
• CFHostStartInfoResolution
• CFHostSetClient
• CFHostScheduleWithRunLoop
• CFHostUnscheduleFromRunLoop

Getting the CFHost Type ID

• CFHostGetTypeID

Functions

CFHostCancelInfoResolution

Cancels the resolution of a host.

void CFHostCancelInfoResolution (
   CFHostRef theHost,
   CFHostInfoType info
);

CFHostCreateCopy

Creates a new host object by copying.

CFHostRef CFHostCreateCopy (
   CFAllocatorRef alloc,
   CFHostRef host
);

CFHostCreateWithAddress

Uses an address to create an instance of a host object.

CFHostRef CFHostCreateWithAddress (
   CFAllocatorRef allocator,
   CFDataRef addr
);

CFHostCreateWithName

Uses a name to create an instance of a host object.

CFHostRef CFHostCreateWithName (
   CFAllocatorRef allocator,
   CFStringRef hostname
);

CFHostGetAddressing

Gets the addresses from a host.

CFArrayRef CFHostGetAddressing (
   CFHostRef theHost,
   Boolean *hasBeenResolved
);

CFHostGetNames

Gets the names from a CFHost.

CFArrayRef CFHostGetNames (
   CFHostRef theHost,
   Boolean *hasBeenResolved
);

CFHostGetReachability

Gets reachability information from a host.

CFDataRef CFHostGetReachability (
   CFHostRef theHost,
   Boolean *hasBeenResolved
);

CFHostGetTypeID

Gets the Core Foundation type identifier for the CFHost opaque type.

CFTypeID CFHostGetTypeID ();

CFHostScheduleWithRunLoop

Schedules a CFHost on a run loop.

void CFHostScheduleWithRunLoop (
   CFHostRef theHost,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode
);

CFHostSetClient

Associates a client context and a callback function with a CFHost object or disassociates a client context and callback function that were previously set.

Boolean CFHostSetClient (
   CFHostRef theHost,
   CFHostClientCallBack clientCB,
   CFHostClientContext *clientContext
);

CFHostStartInfoResolution

Starts resolution for a host object.

Boolean CFHostStartInfoResolution (
   CFHostRef theHost,
   CFHostInfoType info,
   CFStreamError *error
);

CFHostUnscheduleFromRunLoop

Unschedules a CFHost from a run loop.

void CFHostUnscheduleFromRunLoop (
   CFHostRef theHost,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode
);

Callbacks

CFHostClientCallBack

Defines a pointer to the callback function that is called when an asynchronous resolution of a CFHost completes or an error occurs for an asynchronous CFHost resolution.

typedef void (CFHostClientCallBack) (
   CFHostRef theHost,
   CFHostInfoType typeInfo,
   const CFStreamError *error,
   void *info);

If you name your callback MyHostClientCallBack, you would declare it like this:

void MyHostClientCallBack (
   CFHostRef theHost,
   CFHostInfoType typeInfo,
   const CFStreamError *error,
   void *info
);

Data Types

CFHostRef

An opaque reference representing an CFHost object.

typedef struct __CFHost* CFHostRef;

CFHostClientContext

A structure containing user-defined data and callbacks for CFHost objects.

struct CFHostClientContext {
   CFIndex version;
   void *info;
   CFAllocatorRetainCallBack retain;
   CFAllocatorReleaseCallBack release;
   CFAllocatorCopyDescriptionCallBack copyDescription;
} CFHostClientContext;
typedef struct CFHostClientContext CFHostClientContext;

Fields

version

The version number of the structure type passed as a parameter to the host client function. The only valid version number is 0.

info

An arbitrary pointer to allocated memory containing user-defined data that can be associated with the host and that is passed to the callbacks.

retain

The callback used to add a retain for the host on the info pointer for the life of the host, and may be used for temporary references the host needs to take. This callback returns the actual info pointer to store in the host, almost always just the pointer passed as the parameter.

release

The callback used to remove a retain previously added for the host on the info pointer.

copyDescription

The callback used to create a descriptive string representation of the info pointer (or the data pointed to by the info pointer) for debugging purposes. This callback is called by the CFCopyDescription function.

Constants

CFHostInfoType Constants

Values indicating the type of data that is to be resolved or the type of data that was resolved.

enum CFHostInfoType {
   kCFHostAddresses = 0,
   kCFHostNames = 1,
   kCFHostReachability = 2
};
typedef enum CFHostInfoType CFHostInfoType;

Constants

kCFHostAddresses

Specifies that addresses are to be resolved or that addresses were resolved.

Available in OS X v10.3 and later.

Declared in CFHost.h.

kCFHostNames

Specifies that names are to be resolved or that names were resolved.

Available in OS X v10.3 and later.

Declared in CFHost.h.

kCFHostReachability

Specifies that reachability information is to be resolved or that reachability information was resolved.

Available in OS X v10.3 and later.

Declared in CFHost.h.

Error Domains

Error domains specific to CFHost calls.

extern const SInt32 kCFStreamErrorDomainNetDB;
extern const SInt32 kCFStreamErrorDomainSystemConfiguration;

Constants

kCFStreamErrorDomainNetDB

The error domain that returns errors from the network database (DNS resolver) layer (described in /usr/include/netdb.h).

Available in OS X version 10.5 and later.

Declared in CFHost.h.

kCFStreamErrorDomainSystemConfiguration

The error domain that returns errors from the system configuration layer (described in System Configuration Framework Reference).

Available in OS X version 10.5 and later.

Declared in CFHost.h.