Framework | |
Declared in | SCNetworkReachability.h |
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.
SCNetworkReachabilityCreateWithAddress
SCNetworkReachabilityCreateWithAddressPair
SCNetworkReachabilityCreateWithName
SCNetworkReachabilityGetTypeID
SCNetworkReachabilitySetCallback
SCNetworkReachabilityScheduleWithRunLoop
SCNetworkReachabilityUnscheduleFromRunLoop
SCNetworkReachabilitySetDispatchQueue
Creates a reachability reference to the specified network address.
SCNetworkReachabilityRef SCNetworkReachabilityCreateWithAddress ( CFAllocatorRef allocator, const struct sockaddr *address );
The allocator to use. Pass NULL
or kCFAllocatorDefault
to use the default allocator.
The address of the desired host.
A new immutable reachability reference. You must release the returned value.
You can use the reachability reference returned by this function to monitor the reachability of the target host.
SCNetworkReachability.h
Creates a reachability reference to the specified network address.
SCNetworkReachabilityRef SCNetworkReachabilityCreateWithAddressPair ( CFAllocatorRef allocator, const struct sockaddr *localAddress, const struct sockaddr *remoteAddress );
The allocator to use. Pass NULL
or kCFAllocatorDefault
to use the default allocator.
The local address associated with a network connection. If NULL
, only the remote address is of interest.
The remote address associated with a network connection. If NULL
, only the local address is of interest.
A new immutable reachability reference. You must release the returned value.
You can use the reachability reference returned by this function to monitor the reachability of the target host.
SCNetworkReachability.h
Creates a reachability reference to the specified network host or node name.
SCNetworkReachabilityRef SCNetworkReachabilityCreateWithName ( CFAllocatorRef allocator, const char *nodename );
The allocator to use. Pass NULL
or kCFAllocatorDefault
to use the default allocator.
The node name of the desired host. This name is the same as that passed to the gethostbyname(3)
or getaddrinfo(3)
functions.
A new immutable reachability reference. You must release the returned value.
You can use the reachability reference returned by this function to monitor the reachability of the target host.
SCNetworkReachability.h
Determines if the specified network target is reachable using the current network configuration.
Boolean SCNetworkReachabilityGetFlags ( SCNetworkReachabilityRef target, SCNetworkReachabilityFlags *flags );
The network reference associated with the address or name to be checked for reachability.
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.)
TRUE
if the flags are valid; FALSE
if the status could not be determined.
SCNetworkReachability.h
Returns the type identifier of all SCNetworkReachability
instances.
CFTypeID SCNetworkReachabilityGetTypeID ( void );
The type identifier of all SCNetworkReachability
instances.
SCNetworkReachability.h
Schedules the specified network target with the specified run loop and mode.
Boolean SCNetworkReachabilityScheduleWithRunLoop ( SCNetworkReachabilityRef target, CFRunLoopRef runLoop, CFStringRef runLoopMode );
The address or name that is set up for asynchronous notifications. Must not be NULL
.
The run loop on which the target should be scheduled. Must not be NULL
.
The mode in which to schedule the target. Must not be NULL
.
TRUE
if the target is scheduled successfully; otherwise, FALSE
.
SCNetworkReachability.h
Assigns a client to the specified target, which receives callbacks when the reachability of the target changes.
Boolean SCNetworkReachabilitySetCallback ( SCNetworkReachabilityRef target, SCNetworkReachabilityCallBack callout, SCNetworkReachabilityContext *context );
The network reference associated with the address or name to be checked for reachability.
The function to be called when the reachability of the target changes. If NULL
, the current client for the target is removed.
The reachability context associated with the callout. This value may be NULL
.
TRUE
if the notification client was successfully set; otherwise, FALSE
.
SCNetworkReachability.h
Schedules callbacks for the specified target on the specified dispatch queue.
Boolean SCNetworkReachabilitySetDispatchQueue ( SCNetworkReachabilityRef target, dispatch_queue_t queue );
The address or name that is set up for asynchronous notifications. Must not be NULL
.
The libdispatch queue on which the target should run. Pass NULL
to disable notifications and release the queue.
TRUE
if the target is scheduled successfully; otherwise, FALSE
.
SCNetworkReachability.h
Unschedules the specified target from the specified run loop and mode.
Boolean SCNetworkReachabilityUnscheduleFromRunLoop ( SCNetworkReachabilityRef target, CFRunLoopRef runLoop, CFStringRef runLoopMode );
The address or name that is set up for asynchronous notifications. Must not be NULL
.
The run loop on which the target should be unscheduled. Must not be NULL
.
The mode in which to unschedule the target. Must not be NULL
.
TRUE
if the target is unscheduled successfully; otherwise, FALSE
.
SCNetworkReachability.h
The handle to a network address or name.
typedef const struct __SCNetworkReachability * SCNetworkReachabilityRef;
SCNetworkReachability.h
Structure containing user-specified data and callbacks used with SCNetworkReachabilitySetCallback
.
typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } SCNetworkReachabilityContext;
version
The version number of the structure type being passed in as a parameter to an SCDynamicStore
creation function, such as SCDynamicStoreCreate
. This structure is version 0
.
info
A C pointer to a user-specified block of data.
retain
The callback used to add a retain for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value can be NULL
.
release
The calllback used to remove a retain previously added for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value can be NULL
.
copyDescription
The callback used to provide a description of the info field.
SCNetworkReachability.h
Type of callback function used when the reachability of a network address or name changes.
typedef void (*SCNetworkReachabilityCallBack) ( SCNetworkReachabilityRef target, SCNetworkReachabilityFlags flags, void *info );
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.
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.
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, kSCNetworkReachabilityFlagsConnectionAutomatic = kSCNetworkReachabilityFlagsConnectionOnTraffic }; typedef uint32_t SCNetworkReachabilityFlags;
kSCNetworkReachabilityFlagsTransientConnection
The specified node name or address can be reached via a transient connection, such as PPP.
Available in Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
kSCNetworkReachabilityFlagsReachable
The specified node name or address can be reached using the current network configuration.
Available in Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
kSCNetworkReachabilityFlagsConnectionRequired
The specified node name or address can be reached using the current network configuration, but a connection must first be established.
Available in Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
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 Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
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 Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
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 Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
kSCNetworkReachabilityFlagsIsLocalAddress
The specified node name or address is one that is associated with a network interface on the current system.
Available in Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
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 Mac OS X v10.6 and later.
Declared in SCNetworkReachability.h
.
Last updated: 2010-03-24