SCNetworkReachability.h

Overview

The SCNetworkReachability API allows an application to determine the status of a system's current network configuration and the reachability of a target host. In addition, reachability can be monitored with notifications that are sent when the status has changed. Note that these functions follow Core Foundation function-name conventions in that a function that has "Create" or "Copy" in its name returns a reference you must release with CFRelease.

"Reachability" reflects whether 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.

For more information on using System Configuration framework APIs, see System Configuration Programming Guidelines.

Functions

SCNetworkReachabilityCreateWithAddress

SCNetworkReachabilityCreateWithAddressPair

SCNetworkReachabilityCreateWithName

SCNetworkReachabilityGetFlags

SCNetworkReachabilityGetTypeID

SCNetworkReachabilityScheduleWithRunLoop

SCNetworkReachabilitySetCallback

SCNetworkReachabilityUnscheduleFromRunLoop

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

Parameters

address

The address of the desired host.

Return Value

Returns a reference to the new immutable SCNetworkReachabilityRef.

You must release the returned value.

Discussion

Creates a reference to the specified network address. This reference can be used later to monitor the reachability of the target host.

Availability

Introduced in Mac OS X v10.3.

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

Parameters

localAddress

The local address associated with a network connection. If NULL, only the remote address is of interest.

remoteAddress

The remote address associated with a network connection. If NULL, only the local address is of interest.

Return Value

Returns a reference to the new immutable SCNetworkReachabilityRef.

You must release the returned value.

Discussion

Creates a reference to the specified network address. This reference can be used later to monitor the reachability of the target host.

Availability

Introduced in Mac OS X v10.3.

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

Parameters

nodename

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

Return Value

Returns a reference to the new immutable SCNetworkReachabilityRef.

You must release the returned value.

Discussion

Creates a reference to the specified network host or node name. This reference can be used later to monitor the reachability of the target host.

Availability

Introduced in Mac OS X v10.3.

Boolean SCNetworkReachabilityGetFlags ( 
    SCNetworkReachabilityRef target, 
    SCNetworkConnectionFlags *flags );  

Parameters

target

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

flags

A pointer to memory that will be filled with the SCNetworkConnectionFlags detailing the reachability of the specified target.

Return Value

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

Discussion

Determines if the given target is reachable using the current network configuration.

Availability

Introduced in Mac OS X v10.3.

CFTypeID SCNetworkReachabilityGetTypeID (
    void);  

Discussion

Returns the type identifier of all SCNetworkReachability instances.

Availability

Introduced in Mac OS X v10.3.

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

Parameters

target

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

runLoop

A reference to a run loop on which the target should be scheduled. Must be non-NULL.

runLoopMode

The mode on which to schedule the target. Must be non-NULL.

Return Value

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

Discussion

Schedules the given target with the given run loop and mode.

Availability

Introduced in Mac OS X v10.3.

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 SCNetworkReachabilityContext associated with the callout. The value may be NULL.

Return Value

Returns TRUE if the notification client was successfully set.

Discussion

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

Availability

Introduced in Mac OS X v10.3.

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

Parameters

target

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

runLoop

A reference to a run loop from which the target should be unscheduled. Must be non-NULL.

runLoopMode

The mode on which to unschedule the target. Must be non-NULL.

Return Value

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

Discussion

Unschedules the given target from the given run loop and mode.

Availability

Introduced in Mac OS X v10.3.

Typedefs

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

Parameters

target

The SCNetworkReachability reference being monitored for changes.

flags

The new SCNetworkConnectionFlags representing the reachability status of the network address/name.

info

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

Discussion

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

Availability

Introduced in Mac OS X v10.3.

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

Fields

version

The version number of the structure type being passed in as a parameter to the SCDynamicStore creation function. 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 may 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 may be NULL.

copyDescription

The callback used to provide a description of the info field.

Discussion

Structure containing user-specified data and callbacks for SCNetworkReachability.

Availability

Introduced in Mac OS X v10.3.

typedef const struct __SCNetworkReachability * SCNetworkReachabilityRef;  

Discussion

This is the handle to a network address or name.

Availability

Introduced in Mac OS X v10.3.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11