iOS Developer Library

Developer

CoreServices Framework Reference CFHost Reference

Options
Deployment Target:

On This Page
Language:

CFHost Reference

Inherits From


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CFNetwork

Objective-C

@import CFNetwork;

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

  • Creates a new host object by copying.

    Declaration

    Swift

    func CFHostCreateCopy(_ alloc: CFAllocator!, _ addr: CFHost!) -> Unmanaged<CFHost>!

    Objective-C

    CFHostRef CFHostCreateCopy ( CFAllocatorRef alloc, CFHostRef host );

    Parameters

    alloc

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    addr

    The host to copy. This value must not be NULL.

    Return Value

    A valid CFHost object or NULL if the copy could not be created. The new host contains a copy of all previously resolved data from the original host. Ownership follows the Create Rule.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    func CFHostCreateWithAddress(_ alloc: CFAllocator!, _ addr: CFData!) -> Unmanaged<CFHost>!

    Objective-C

    CFHostRef CFHostCreateWithAddress ( CFAllocatorRef allocator, CFDataRef addr );

    Parameters

    alloc

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    addr

    A CFDataRef object containing a sockaddr structure for the address of the host. This value must not be NULL.

    Return Value

    A valid CFHostRef object that can be resolved, or NULL if the host could not be created. Ownership follows the Create Rule.

    Discussion

    Call CFHostStartInfoResolution to resolve the return object’s name and reachability information.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    func CFHostCreateWithName(_ alloc: CFAllocator!, _ hostname: CFString!) -> Unmanaged<CFHost>!

    Objective-C

    CFHostRef CFHostCreateWithName ( CFAllocatorRef allocator, CFStringRef hostname );

    Parameters

    alloc

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    hostname

    A string representing the name of the host. This value must not be NULL.

    Return Value

    A valid CFHostRef object that can be resolved, or NULL if the host could not be created. Ownership follows the Create Rule.

    Discussion

    Call CFHostStartInfoResolution to resolve the object’s addresses and reachability information.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Cancels the resolution of a host.

    Declaration

    Swift

    func CFHostCancelInfoResolution(_ theHost: CFHost!, _ info: CFHostInfoType)

    Objective-C

    void CFHostCancelInfoResolution ( CFHostRef theHost, CFHostInfoType info );

    Parameters

    theHost

    The host for which a resolution is to be cancelled. This value must not be NULL.

    info

    A value of type CFHostInfoType specifying the type of resolution that is to be cancelled. See CFHostInfoType Constants for possible values.

    Discussion

    This function cancels the asynchronous or synchronous resolution specified by info for the host specified by theHost.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Gets the addresses from a host.

    Declaration

    Swift

    func CFHostGetAddressing(_ theHost: CFHost!, _ hasBeenResolved: UnsafeMutablePointer<Boolean>) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef CFHostGetAddressing ( CFHostRef theHost, Boolean *hasBeenResolved );

    Parameters

    theHost

    The CFHost whose addresses are to be obtained. This value must not be NULL.

    hasBeenResolved

    On return, a pointer to a Boolean that is TRUE if addresses were available and FALSE if addresses were not available. This parameter can be null.

    function result

    A CFArray of addresses where address is a sockaddr structure wrapped by a CFDataRef, or null if no addresses were available.

    Discussion

    This function gets the addresses from a CFHost. The CFHost must have been previously resolved. To resolve a CFHost, call CFHostStartInfoResolution.

    Special Considerations

    This function gets the addresses in a thread-safe way, but the resulting data is not thread-safe. The data is returned as a “get” as opposed to a copy, so the data is not safe if the CFHost is altered from another thread.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Gets the names from a CFHost.

    Declaration

    Swift

    func CFHostGetNames(_ theHost: CFHost!, _ hasBeenResolved: UnsafeMutablePointer<Boolean>) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef CFHostGetNames ( CFHostRef theHost, Boolean *hasBeenResolved );

    Parameters

    theHost

    The host to examine. The host must have been previously resolved. (To resolve a host, call CFHostStartInfoResolution.) This value must not be NULL.

    hasBeenResolved

    On return, contains TRUE if names were available, otherwise FALSE. This value may be NULL.

    Return Value

    An array containing the of names of theHost, or NULL if no names were available.

    Special Considerations

    This function gets the names in a thread-safe way, but the resulting data is not thread-safe. The data is returned as a “get” as opposed to a copy, so the data is not safe if the CFHost is altered from another thread.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Gets reachability information from a host.

    Declaration

    Swift

    func CFHostGetReachability(_ theHost: CFHost!, _ hasBeenResolved: UnsafeMutablePointer<Boolean>) -> Unmanaged<CFData>!

    Objective-C

    CFDataRef CFHostGetReachability ( CFHostRef theHost, Boolean *hasBeenResolved );

    Parameters

    theHost

    The host whose reachability is to be obtained. The host must have been previously resolved. (To resolve a host, call CFHostStartInfoResolution.) This value must not be NULL.

    hasBeenResolved

    On return, contains TRUE if the reachability was available, otherwise FALSE. This value may be NULL.

    Return Value

    A CFData object that wraps the reachability flags (SCNetworkConnectionFlags) defined in SystemConfiguration/SCNetwork.h, or NULL if reachability information was not available.

    Special Considerations

    This function gets reachability information in a thread-safe way, but the resulting data is not thread-safe. The data is returned as a “get” as opposed to a copy, so the data is not safe if the CFHost is altered from another thread.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Starts resolution for a host object.

    Declaration

    Swift

    func CFHostStartInfoResolution(_ theHost: CFHost!, _ info: CFHostInfoType, _ error: UnsafeMutablePointer<CFStreamError>) -> Boolean

    Objective-C

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

    Parameters

    theHost

    The host, obtained by previously calling CFHostCreateCopy, CFHostCreateWithAddress, or CFHostCreateWithName, that is to be resolved. This value must not be NULL.

    info

    A value of type CFHostInfoType specifying the type of information that is to be retrieved. See CFHostInfoType Constants for possible values.

    error

    A pointer to a CFStreamError structure, that, if an error occurs, is set to the error and the error’s domain. In synchronous mode, the error indicates why resolution failed, and in asynchronous mode, the error indicates why resolution failed to start.

    Return Value

    TRUE if the resolution was started (asynchronous mode); FALSE if another resolution is already in progress for theHost or if an error occurred.

    Discussion

    This function retrieves the information specified by info and stores it in the host.

    In synchronous mode, this function blocks until the resolution has completed, in which case this function returns TRUE, until the resolution is stopped by calling CFHostCancelInfoResolution from another thread, in which case this function returns FALSE, or until an error occurs.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    func CFHostSetClient(_ theHost: CFHost!, _ clientCB: CFHostClientCallBack, _ clientContext: UnsafeMutablePointer<CFHostClientContext>) -> Boolean

    Objective-C

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

    Parameters

    theHost

    The host to modify. The value must not be NULL.

    clientCB

    The callback function to associate with theHost. The callback function will be called when a resolution completes or is cancelled. If you are calling this function to disassociate a client context and callback from theHost, pclientCBass NULL.

    clientContext

    A CFHostClientContext structure whose info field will be passed to the callback function specified by clientCB when clientCB is called. This value must not be NULL when setting an association.

    Pass NULL when disassociating a client context and a callback from a host.

    Return Value

    TRUE if the association could be set or unset, otherwise FALSE.

    Discussion

    The callback function specified by clientCB will be called when a resolution completes or is cancelled.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Schedules a CFHost on a run loop.

    Declaration

    Swift

    func CFHostScheduleWithRunLoop(_ theHost: CFHost!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!)

    Objective-C

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

    Parameters

    theHost

    The host to be schedule on a run loop. This value must not be NULL.

    runLoop

    The run loop on which to schedule theHost. This value must not be NULL.

    runLoopMode

    The mode on which to schedule theHost. This value must not be NULL.

    Discussion

    Schedules theHost on a run loop, which causes resolutions of the host to be performed asynchronously. The caller is responsible for ensuring that at least one of the run loops on which the host is scheduled is being run.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Unschedules a CFHost from a run loop.

    Declaration

    Swift

    func CFHostUnscheduleFromRunLoop(_ theService: CFHost!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!)

    Objective-C

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

    Parameters

    theService

    The host to unschedule. This value must not be NULL.

    runLoop

    The run loop. This value must not be NULL.

    runLoopMode

    The mode from which the service is to be unscheduled. This value must not be NULL.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    func CFHostGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFHostGetTypeID ( void );

    Return Value

    The Core Foundation type identifier for the CFHost opaque type.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

Callbacks

  • 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.

    Declaration

    Swift

    typealias CFHostClientCallBack = CFunctionPointer<((CFHost!, CFHostInfoType, UnsafePointer<CFStreamError>, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

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

    Parameters

    theHost

    The host for which an asynchronous resolution has been completed.

    typeInfo

    Value of type CFHostInfoType representing the type of information (addresses, names, or reachability information) obtained by the completed resolution. See CFHostInfoType Constants for possible values.

    error

    If the resolution failed, contains a CFStreamError structure whose error field contains an error code.

    info

    User-defined context information. The value pointed to by info is the same as the value pointed to by the info field of the CFHostClientContext structure that was provided when the host was associated with this callback function.

    Discussion

    The callback function for a CFHost object is called one or more times when an asynchronous resolution completes for the specified host, when an asynchronous resolution is cancelled, or when an error occurs during an asynchronous resolution.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

Data Types

  • An opaque reference representing an CFHost object.

    Declaration

    Swift

    typealias CFHostRef = CFHost

    Objective-C

    typedef struct __CFHost* CFHostRef;

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Swift

    struct CFHostClientContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFAllocatorRetainCallBack var release: CFAllocatorReleaseCallBack var copyDescription: CFAllocatorCopyDescriptionCallBack init() init(version version: CFIndex, info info: UnsafeMutablePointer<Void>, retain retain: CFAllocatorRetainCallBack, release release: CFAllocatorReleaseCallBack, copyDescription copyDescription: CFAllocatorCopyDescriptionCallBack) }

    Objective-C

    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.

    Availability

    Available in iOS 2.0 and later

Constants

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

    Declaration

    Swift

    enum CFHostInfoType : Int32 { case Addresses case Names case Reachability }

    Objective-C

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

    Constants

    • Addresses

      kCFHostAddresses

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

      Available in iOS 2.0 and later

    • Names

      kCFHostNames

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

      Available in iOS 2.0 and later

    • Reachability

      kCFHostReachability

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

      Available in iOS 2.0 and later

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Error domains specific to CFHost calls.

    Declaration

    Swift

    let kCFStreamErrorDomainNetDB: Int32 let kCFStreamErrorDomainSystemConfiguration: Int32

    Objective-C

    extern const SInt32 kCFStreamErrorDomainNetDB; extern const SInt32 kCFStreamErrorDomainSystemConfiguration;

    Constants

    • kCFStreamErrorDomainNetDB

      kCFStreamErrorDomainNetDB

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

      Available in iOS 2.0 and later

    • kCFStreamErrorDomainSystemConfiguration

      kCFStreamErrorDomainSystemConfiguration

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

      Available in iOS 2.0 and later

    Discussion

    To determine the source of an error, examine the userInfo dictionary included in the CFError object returned by a function call or call CFErrorGetDomain and pass in the CFError object and the domain whose value you want to read.