iOS Developer Library

Developer

System Configuration 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>) -> 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.

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

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

    Availability

    Available in iOS 2.0 and later.

Callbacks

Data Types

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

    struct SCNetworkReachabilityFlags : OptionSetType { init(rawValue rawValue: UInt32) static var TransientConnection: SCNetworkReachabilityFlags { get } static var Reachable: SCNetworkReachabilityFlags { get } static var ConnectionRequired: SCNetworkReachabilityFlags { get } static var ConnectionOnTraffic: SCNetworkReachabilityFlags { get } static var InterventionRequired: SCNetworkReachabilityFlags { get } static var ConnectionOnDemand: SCNetworkReachabilityFlags { get } static var IsLocalAddress: SCNetworkReachabilityFlags { get } static var IsDirect: SCNetworkReachabilityFlags { get } static var IsWWAN: SCNetworkReachabilityFlags { get } static var ConnectionAutomatic: SCNetworkReachabilityFlags { get } }

    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

    • transientConnection

      kSCNetworkReachabilityFlagsTransientConnection

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

      Available in iOS 2.0 and later.

    • reachable

      kSCNetworkReachabilityFlagsReachable

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

      Available in iOS 2.0 and later.

    • connectionRequired

      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.

    • connectionOnTraffic

      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.

    • interventionRequired

      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.

    • connectionOnDemand

      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.

    • isLocalAddress

      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.

    • isDirect

      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.

    • isWWAN

      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.

    • connectionAutomatic

      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.