iOS Developer Library

Developer

SystemConfiguration Framework Reference SCNetworkReachability Reference

Options
Deployment Target:

On This Page
Language:

SCNetworkReachability Reference

The SCNetworkReachability programming interface allows an application to determine the status of a system's current network configuration and the reachability of a target host. A remote host is considered reachable when a data packet, sent by an application into the network stack, can leave the local device. Reachability does not guarantee that the data packet will actually be received by the host.

The SCNetworkReachability programming interface supports a synchronous and an asynchronous model. In the synchronous model, you get the reachability status by calling the SCNetworkReachabilityGetFlags function. In the asynchronous model, you can schedule the SCNetworkReachability object on the run loop of a client object’s thread. The client implements a callback function to receive notifications when the reachability status of a given remote host changes. Note that these functions follow Core Foundation naming conventions. A function that has "Create" or "Copy" in its name returns a reference you must release with the CFRelease function.

For information about detecting and interpreting errors generated by calling these functions, see System Configuration Reference.

Functions

  • Creates a reachability reference to the specified network address.

    Declaration

    Swift

    func SCNetworkReachabilityCreateWithAddress(_ allocator: CFAllocator!, _ address: UnsafePointer<sockaddr>) -> Unmanaged<SCNetworkReachability>!

    Objective-C

    SCNetworkReachabilityRef SCNetworkReachabilityCreateWithAddress ( CFAllocatorRef allocator, const struct sockaddr *address );

    Parameters

    allocator

    The allocator to use. Pass NULL or kCFAllocatorDefault to use the default allocator.

    address

    The address of the desired host. The value of this parameter is copied into the new object.

    Return Value

    A new immutable reachability reference. You must release the returned value.

    Discussion

    You can use the reachability reference returned by this function to monitor the reachability of the target host.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Creates a reachability reference to the specified network address.

    Declaration

    Swift

    func SCNetworkReachabilityCreateWithAddressPair(_ allocator: CFAllocator!, _ localAddress: UnsafePointer<sockaddr>, _ remoteAddress: UnsafePointer<sockaddr>) -> Unmanaged<SCNetworkReachability>!

    Objective-C

    SCNetworkReachabilityRef SCNetworkReachabilityCreateWithAddressPair ( CFAllocatorRef allocator, const struct sockaddr *localAddress, const struct sockaddr *remoteAddress );

    Parameters

    allocator

    The allocator to use. Pass NULL or kCFAllocatorDefault to use the default allocator.

    localAddress

    The local address associated with a network connection. If NULL, only the remote address is of interest. The value of this parameter is copied into the new object.

    remoteAddress

    The remote address associated with a network connection. If NULL, only the local address is of interest. The value of this parameter is copied into the new object.

    Return Value

    A new immutable reachability reference. You must release the returned value.

    Discussion

    You can use the reachability reference returned by this function to monitor the reachability of the target host.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Creates a reachability reference to the specified network host or node name.

    Declaration

    Swift

    func SCNetworkReachabilityCreateWithName(_ allocator: CFAllocator!, _ nodename: UnsafePointer<Int8>) -> Unmanaged<SCNetworkReachability>!

    Objective-C

    SCNetworkReachabilityRef SCNetworkReachabilityCreateWithName ( CFAllocatorRef allocator, const char *nodename );

    Parameters

    allocator

    The allocator to use. Pass NULL or kCFAllocatorDefault to use the default allocator.

    nodename

    The node name of the desired host. This name is the same as that passed to the gethostbyname or getaddrinfo functions. The value of this parameter is copied into the new object.

    Return Value

    A new immutable reachability reference. You must release the returned value.

    Discussion

    You can use the reachability reference returned by this function to monitor the reachability of the target host.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Determines if the specified network target is reachable using the current network configuration.

    Declaration

    Swift

    func SCNetworkReachabilityGetFlags(_ target: SCNetworkReachability!, _ flags: UnsafeMutablePointer<SCNetworkReachabilityFlags>) -> Boolean

    Objective-C

    Boolean SCNetworkReachabilityGetFlags ( SCNetworkReachabilityRef target, SCNetworkReachabilityFlags *flags );

    Parameters

    target

    The network reference associated with the address or name to be checked for reachability.

    flags

    A pointer to memory that, on output, is filled with flags that describe the reachability of the specified target. (See Network Reachability Flags for possible values.)

    Return Value

    TRUE if the flags are valid; FALSE if the status could not be determined.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Returns the type identifier of all SCNetworkReachability instances.

    Declaration

    Swift

    func SCNetworkReachabilityGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID SCNetworkReachabilityGetTypeID ( void );

    Return Value

    The type identifier of all SCNetworkReachability instances.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Assigns a client to the specified target, which receives callbacks when the reachability of the target changes.

    Declaration

    Swift

    func SCNetworkReachabilitySetCallback(_ target: SCNetworkReachability!, _ callout: SCNetworkReachabilityCallBack, _ context: UnsafeMutablePointer<SCNetworkReachabilityContext>) -> Boolean

    Objective-C

    Boolean SCNetworkReachabilitySetCallback ( SCNetworkReachabilityRef target, SCNetworkReachabilityCallBack callout, SCNetworkReachabilityContext *context );

    Parameters

    target

    The network reference associated with the address or name to be checked for reachability.

    callout

    The function to be called when the reachability of the target changes. If NULL, the current client for the target is removed.

    context

    The reachability context associated with the callout. This value may be NULL.

    Return Value

    TRUE if the notification client was successfully set; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Schedules the specified network target with the specified run loop and mode.

    Declaration

    Swift

    func SCNetworkReachabilityScheduleWithRunLoop(_ target: SCNetworkReachability!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!) -> Boolean

    Objective-C

    Boolean SCNetworkReachabilityScheduleWithRunLoop ( SCNetworkReachabilityRef target, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    target

    The address or name that is set up for asynchronous notifications. Must not be NULL.

    runLoop

    The run loop on which the target should be scheduled. Must not be NULL.

    runLoopMode

    The mode in which to schedule the target. Must not be NULL.

    Return Value

    TRUE if the target is scheduled successfully; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Unschedules the specified target from the specified run loop and mode.

    Declaration

    Swift

    func SCNetworkReachabilityUnscheduleFromRunLoop(_ target: SCNetworkReachability!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!) -> Boolean

    Objective-C

    Boolean SCNetworkReachabilityUnscheduleFromRunLoop ( SCNetworkReachabilityRef target, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    target

    The address or name that is set up for asynchronous notifications. Must not be NULL.

    runLoop

    The run loop on which the target should be unscheduled. Must not be NULL.

    runLoopMode

    The mode in which to unschedule the target. Must not be NULL.

    Return Value

    TRUE if the target is unscheduled successfully; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Schedules callbacks for the specified target on the specified dispatch queue.

    Declaration

    Swift

    func SCNetworkReachabilitySetDispatchQueue(_ target: SCNetworkReachability!, _ queue: dispatch_queue_t!) -> Boolean

    Objective-C

    Boolean SCNetworkReachabilitySetDispatchQueue ( SCNetworkReachabilityRef target, dispatch_queue_t queue );

    Parameters

    target

    The address or name that is set up for asynchronous notifications. Must not be NULL.

    queue

    The libdispatch queue on which the target should run. Pass NULL to disable notifications and release the queue.

    Return Value

    TRUE if the target is scheduled successfully; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 4.0 and later.

Callbacks

  • Type of callback function used when the reachability of a network address or name changes.

    Declaration

    Swift

    typealias SCNetworkReachabilityCallBack = CFunctionPointer<((SCNetworkReachability!, SCNetworkReachabilityFlags, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*SCNetworkReachabilityCallBack) ( SCNetworkReachabilityRef target, SCNetworkReachabilityFlags flags, void *info );

    Parameters

    target

    The network target being monitored for changes.

    flags

    The flags representing the reachability status of the network address or name (see Network Reachability Flags for information about these flags).

    info

    A C pointer to a user-specified block of data.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

Data Types

  • The handle to a network address or name.

    Declaration

    Swift

    typealias SCNetworkReachabilityRef = SCNetworkReachability

    Objective-C

    typedef const struct __SCNetworkReachability * SCNetworkReachabilityRef;

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

  • Structure containing user-specified data and callbacks used with SCNetworkReachabilitySetCallback.

    Declaration

    Swift

    struct SCNetworkReachabilityContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)> var release: CFunctionPointer<((UnsafePointer<Void>) -> Void)> var copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)> }

    Objective-C

    typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } SCNetworkReachabilityContext;

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.

Constants

  • Flags that indicate the reachability of a network node name or address, including whether a connection is required, and whether some user intervention might be required when establishing a connection.

    Declaration

    Swift

    typealias SCNetworkReachabilityFlags = UInt32

    Objective-C

    enum { kSCNetworkReachabilityFlagsTransientConnection = 1<<0, kSCNetworkReachabilityFlagsReachable = 1<<1, kSCNetworkReachabilityFlagsConnectionRequired = 1<<2, kSCNetworkReachabilityFlagsConnectionOnTraffic = 1<<3, kSCNetworkReachabilityFlagsInterventionRequired = 1<<4, kSCNetworkReachabilityFlagsConnectionOnDemand = 1<<5, kSCNetworkReachabilityFlagsIsLocalAddress = 1<<16, kSCNetworkReachabilityFlagsIsDirect = 1<<17, kSCNetworkReachabilityFlagsIsWWAN = 1<<18, kSCNetworkReachabilityFlagsConnectionAutomatic = kSCNetworkReachabilityFlagsConnectionOnTraffic }; typedef uint32_t SCNetworkReachabilityFlags;

    Constants

    • kSCNetworkReachabilityFlagsTransientConnection

      kSCNetworkReachabilityFlagsTransientConnection

      The specified node name or address can be reached via a transient connection, such as PPP.

      Available in iOS 2.0 and later.

    • kSCNetworkReachabilityFlagsReachable

      kSCNetworkReachabilityFlagsReachable

      The specified node name or address can be reached using the current network configuration.

      Available in iOS 2.0 and later.

    • kSCNetworkReachabilityFlagsConnectionRequired

      kSCNetworkReachabilityFlagsConnectionRequired

      The specified node name or address can be reached using the current network configuration, but a connection must first be established. If this flag is set, the kSCNetworkReachabilityFlagsConnectionOnTraffic flag, kSCNetworkReachabilityFlagsConnectionOnDemand flag, or kSCNetworkReachabilityFlagsIsWWAN flag is also typically set to indicate the type of connection required. If the user must manually make the connection, the kSCNetworkReachabilityFlagsInterventionRequired flag is also set.

      Available in iOS 2.0 and later.

    • kSCNetworkReachabilityFlagsConnectionOnTraffic

      kSCNetworkReachabilityFlagsConnectionOnTraffic

      The specified node name or address can be reached using the current network configuration, but a connection must first be established. Any traffic directed to the specified name or address will initiate the connection.

      This flag was previously named kSCNetworkReachabilityFlagsConnectionAutomatic.

      Available in iOS 3.0 and later.

    • kSCNetworkReachabilityFlagsInterventionRequired

      kSCNetworkReachabilityFlagsInterventionRequired

      The specified node name or address can be reached using the current network configuration, but a connection must first be established.

      In addition, some form of user intervention will be required to establish this connection, such as providing a password, an authentication token, etc.

      Currently, this flag is returned only when there is a dial-on-traffic configuration (kSCNetworkReachabilityFlagsConnectionOnTraffic), an attempt to connect has already been made, and when some error (such as no dial tone, no answer, bad password, etc.) occurred during the automatic connection attempt. In this case the PPP controller stops attempting to establish a connection until the user has intervened.

      Available in iOS 2.0 and later.

    • kSCNetworkReachabilityFlagsConnectionOnDemand

      kSCNetworkReachabilityFlagsConnectionOnDemand

      The specified node name or address can be reached using the current network configuration, but a connection must first be established. The connection will be established "On Demand" by the CFSocketStream programming interface (see CFStream Socket Additions for information on this). Other functions will not establish the connection.

      Available in iOS 3.0 and later.

    • kSCNetworkReachabilityFlagsIsLocalAddress

      kSCNetworkReachabilityFlagsIsLocalAddress

      The specified node name or address is one that is associated with a network interface on the current system.

      Available in iOS 2.0 and later.

    • kSCNetworkReachabilityFlagsIsDirect

      kSCNetworkReachabilityFlagsIsDirect

      Network traffic to the specified node name or address will not go through a gateway, but is routed directly to one of the interfaces in the system.

      Available in iOS 2.0 and later.

    • kSCNetworkReachabilityFlagsIsWWAN

      kSCNetworkReachabilityFlagsIsWWAN

      The specified node name or address can be reached via a cellular connection, such as EDGE or GPRS.

      Available in iOS 2.0 and later.

    • kSCNetworkReachabilityFlagsConnectionAutomatic

      kSCNetworkReachabilityFlagsConnectionAutomatic

      The specified node name or address can be reached using the current network configuration, but a connection must first be established. Any traffic directed to the specified name or address will initiate the connection. This flag is a synonym for kSCNetworkReachabilityFlagsConnectionOnTraffic.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in iOS 2.0 and later.