Mac Developer Library

Developer

SystemConfiguration Framework Reference SCNetwork Reference

Options
Deployment Target:

On This Page
Language:

SCNetwork Reference

The SCNetwork programming interface contains functions an application can use to determine whether that application can reach a remote host and to notify the system of configuration changes.

A remote host is considered reachable when a data packet, sent by an application into the network stack, can leave the local computer. Note that reachability does not guarantee that the data packet will actually be received by the host.

Functions

  • Determines whether the specified network address is reachable using the current network configuration.

    Deprecation Statement

    See the discussion for a coding alternative.

    Declaration

    Objective-C

    Boolean SCNetworkCheckReachabilityByAddress ( const struct sockaddr *address, socklen_t addrlen, SCNetworkConnectionFlags *flags );

    Parameters

    address

    The network address of the desired host.

    addrlen

    The length, in bytes, of the address.

    flags

    A pointer to memory that, on output, will be filled with a set of SCNetworkConnectionFlags values detailing the reachability of the specified address

    Return Value

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

    Discussion

    This function is deprecated, but you can get equivalent results using the following code:

    • SCNetworkReachabilityRef target;
    • SCNetworkConnectionFlags flags = 0;
    • Boolean ok;
    • target = SCNetworkReachabilityCreateWithAddress(NULL, address);
    • ok = SCNetworkReachabilityGetFlags(target, &flags);
    • CFRelease(target);

    Import Statement

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

  • Determines whether the specified network host or node name is reachable using the current network configuration.

    Deprecation Statement

    See the discussion for a coding alternative.

    Declaration

    Objective-C

    Boolean SCNetworkCheckReachabilityByName ( const char *nodename, SCNetworkConnectionFlags *flags );

    Parameters

    nodename

    The node name of the desired host. This is the same name that would be passed to the gethostbyname(3) or getaddrinfo(3) functions.

    flags

    A pointer to memory that, on output, will be filled with a set of SCNetworkConnectionFlags values detailing the reachability of the specified address

    Return Value

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

    Discussion

    This function is deprecated, but you can get equivalent results using the following code:

    • SCNetworkReachabilityRef target;
    • SCNetworkConnectionFlags flags = 0;
    • Boolean ok;
    • target = SCNetworkReachabilityCreateWithName(NULL, name);
    • ok = SCNetworkReachabilityGetFlags(target, &flags);
    • CFRelease(target);

    Import Statement

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

  • Sends a notification to interested configuration agents to have them immediately retry their configuration over a particular network interface.

    Deprecation Statement

    Use the SCNetworkInterfaceForceConfigurationRefresh function instead.

    Declaration

    Objective-C

    Boolean SCNetworkInterfaceRefreshConfiguration ( CFStringRef ifName );

    Parameters

    ifName

    The BSD name of the network interface, such as CFSTR("en0").

    Return Value

    TRUE if the notification was sent; otherwise, FALSE.

    Discussion

    This function must be invoked by root (in other words, the user with uid equal to 0).

    Import Statement

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.5.

Constants

  • Flags that indicate whether the specified network node name or address is reachable, whether a connection is required, and whether some user intervention may be required when establishing a connection.

    Declaration

    Swift

    typealias SCNetworkConnectionFlags = UInt32

    Objective-C

    enum { kSCNetworkFlagsTransientConnection = 1<<0, kSCNetworkFlagsReachable = 1<<1, kSCNetworkFlagsConnectionRequired = 1<<2, kSCNetworkFlagsConnectionAutomatic = 1<<3, kSCNetworkFlagsInterventionRequired = 1<<4, kSCNetworkFlagsIsLocalAddress = 1<<16, kSCNetworkFlagsIsDirect = 1<<17, }; typedef uint32_t SCNetworkConnectionFlags;

    Constants

    • kSCNetworkFlagsTransientConnection

      kSCNetworkFlagsTransientConnection

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

      Available in OS X v10.1 and later.

    • kSCNetworkFlagsReachable

      kSCNetworkFlagsReachable

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

      Available in OS X v10.1 and later.

    • kSCNetworkFlagsConnectionRequired

      kSCNetworkFlagsConnectionRequired

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

      For example, this status would be returned for a dialup connection that was not currently active, but could handle network traffic for the target system.

      Available in OS X v10.1 and later.

    • kSCNetworkFlagsConnectionAutomatic

      kSCNetworkFlagsConnectionAutomatic

      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.

      Available in OS X v10.1 and later.

    • kSCNetworkFlagsInterventionRequired

      kSCNetworkFlagsInterventionRequired

      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 when there is a dial-on-traffic configuration (ConnectionAutomatic), an attempt to connect has already been made, and when some error (for example, no dial tone, no answer, bad password, etc.) was encountered during the automatic connection attempt. In this case the PPP controller stops attempting to establish a connection until the user has intervened.

      Available in OS X v10.1 and later.

    • kSCNetworkFlagsIsLocalAddress

      kSCNetworkFlagsIsLocalAddress

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

      Available in OS X v10.3 and later.

    • kSCNetworkFlagsIsDirect

      kSCNetworkFlagsIsDirect

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

      Available in OS X v10.3 and later.

    Import Statement

    import SystemConfiguration

    Availability

    Available in OS X v10.1 and later.