SCNetwork Reference

Framework
Declared in
SCNetwork.h

Overview

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

SCNetworkCheckReachabilityByAddress

Determines whether the specified network address is reachable using the current network configuration. (Deprecated. See the discussion for a coding alternative.)

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);
Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
SCNetwork.h

SCNetworkCheckReachabilityByName

Determines whether the specified network host or node name is reachable using the current network configuration. (Deprecated. See the discussion for a coding alternative.)

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);
Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
SCNetwork.h

SCNetworkInterfaceRefreshConfiguration

Sends a notification to interested configuration agents to have them immediately retry their configuration over a particular network interface. (Deprecated. Use the SCNetworkInterfaceForceConfigurationRefresh function instead.)

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

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.5.
Declared In
SCNetwork.h

Constants

Network Connection Flags

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.

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

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

Available in OS X v10.1 and later.

Declared in SCNetwork.h.

kSCNetworkFlagsReachable

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

Available in OS X v10.1 and later.

Declared in SCNetwork.h.

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.

Declared in SCNetwork.h.

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.

Declared in SCNetwork.h.

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.

Declared in SCNetwork.h.

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.

Declared in SCNetwork.h.

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.

Declared in SCNetwork.h.