Creating a Reference

The SCNetworkReachability API provides three functions that create a target reference you can use to monitor the reachability of a remote host:

• SCNetworkReachabilityCreateWithAddress

• SCNetworkReachabilityCreateWithAddressPair

• SCNetworkReachabilityCreateWithName

If you are interested in the reachability of only the remote host, you can use either SCNetworkReachabilityCreateWithAddress or SCNetworkReachabilityCreateWithName. For SCNetworkReachabilityCreateWithAddress, you supply a remote host address in a sockaddr structure. For more information on the sockaddr structure, see the networking man page at http://developer.apple.com/documentation/Darwin/Reference/ManPages/man4/netintro.4.html. For SCNetworkReachabilityCreateWithName, you supply a remote host name, such as www.apple.com.

If you need to monitor possible changes to both the local and remote host addresses, you use the SCNetworkReachabilityCreateWithAddressPair function. This function returns a reference you can use to find out if:

• The address of your local host changes

• The remote address becomes unreachable

• The network route associated with the remote host changes

All three functions return an object of type SCNetworkReachabilityRef for the remote host, which you can use in any of the other SCNetworkReachability functions.

Adding a Target to a Run Loop

To ensure that your application receives notification when the reachability status of the target remote host changes, you add the target’s SCNetworkReachabilityRef to your application’s run loop. A run loop monitors sources of input to an application. When an input source becomes ready for processing (because some activity occurs), the run loop dispatches control to a callback function associated with the input source. For more information on run loops and modes, see Run Loops.

For a network-aware application, the input source is the SCNetworkReachabilityRef, the activity is a change in the target’s connection status, and the callback function is one you provide. Thus, by using the reachability API to add your target to your application’s run loop and to provide a callback function (described in Associating a Callback Function With the Target), you ensure your application will be notified of changes in the target’s reachability.

To add an SCNetworkReachabilityRef to your application’s run loop, you use the SCNetworkReachabilityScheduleWithRunLoop function. You provide the SCNetworkReachabilityRef, a reference to your application’s run loop, and the mode in which the run loop should run, typically the default mode.

To remove an SCNetworkReachabilityRef from your application’s run loop, you use the SCNetworkReachabilityUnscheduleFromRunLoop function, which requires the same parameters as the SCNetworkReachabilityScheduleWithRunLoop function.

Associating a Callback Function With the Target

To make use of the notifications the reachability API provides, you should associate a callback function with the SCNetworkReachabilityRef representing the remote host you’re interested in. The callback function might display the change in the connection to the user or perform some other task.

To associate a callback function with your target, you first define a function of type SCNetworkReachabilityCallBack (this type is defined in SCNetworkReachability.h). To pass contextual information about the changes to your callback function, you define a structure of type SCNetworkReachabilityContext. You use the info argument to contain the context information (you can also specify NULL, if context information is unnecessary). Finally, you pass the callback function, the SCNetworkReachabilityRef representing the remote host, and the context to the SCNetworkReachabilitySetCallback function.

Determining Reachability

The SCNetworkReachability API provides the SCNetworkReachabilityGetFlags function you can use to determine the reachability of a remote host. This function supplies the same connection-status flags the older reachability functions defined in SCNetwork.h supplied.

To use this function, you supply the SCNetworkReachabilityRef for your remote host and the address of the variable you declare to contain the flags. The flags you can receive are listed in Table 4-1.

Creating a Connection Reference

The SCNetworkConnection API provides one function you can use to create a connection reference: SCNetworkConnectionCreateWithServiceID. To use this function, you supply a service ID and a callback function, along with a couple of other parameters, and you receive an object of type SCNetworkConnectionRef. You use this object to represent the connection in the other SCNetworkConnection functions.

Because you’ll be using the SCNetworkConnectionRef to refer to a specific PPP connection, you must supply a unique service ID to identify it. There are two ways to get this service ID. One way is to look in the dynamic store for available services and choose one. The second way is for your application to use the SCNetworkConnectionCopyUserPreferences function to get the default service ID (the one the Internet Connect application uses).

Although you can pass NULL for the callback function parameter, it is not recommended. If you don’t define a callback function, your application will not receive status-change notifications and will have to poll for updates.

Adding a Connection Reference to a Run Loop

To ensure your application gets notified of changes in a specific connection’s status, you can add the SCNetworkConnectionRef representing the connection to your application’s run loop. When the connection’s status changes, the SCNetworkConnectionRef alerts the run loop and the run loop passes control to the callback function you provide.

To add an SCNetworkConnectionRef to your application’s run loop, you use the SCNetworkConnectionScheduleWithRunLoop function. You provide the SCNetworkConnectionRef, a reference to your application’s run loop, and the mode in which the run loop should run (in most cases, the default mode). For more information on run loops and modes, see Introduction to Run Loops in the Core Foundation Reference Library.

To remove the SCNetworkConnectionRef from your application’s run loop, you use the SCNetworkConnectionUnscheduleFromRunLoop function. Like the SCNetworkConnectionScheduleWithRunLoop function, this function expects the SCNetworkConnectionRef, a reference to your application’s run loop, and the run loop mode.

Starting and Stopping a Connection

The SCNetworkConnection API provides two functions your application can use to control a connection using an SCNetworkConnectionRef object:

• SCNetworkConnectionStart

• SCNetworkConnectionStop

Both functions return immediately while the connection or disconnection process they initiate proceeds asynchronously. If you add the connection’s SCNetworkConnectionRef to your application’s run loop and provide a callback function, your application is notified when the status of the connection changes. Your application can then check the status to determine if the connection process is complete. If you don’t add the connection reference to the run loop, you will have to poll to discover the connection status, and this is not recommended.

By default, the SCNetworkConnectionStart function uses the user’s preferred connection settings to start the connection. You can, however, provide a dictionary of values to override some of these settings for the duration of the connection.

If you do provide a dictionary of additional settings be aware that:

• The dictionary must be in the correct format for a network service dictionary (described in The NetworkServices Dictionary). If you do not follow this format precisely, the PPP controller may ignore the dictionary.

• The PPP controller merges the settings you provide with the user’s existing settings before the connection is established, ignoring any inappropriate values in your dictionary.

Starting and stopping a connection are implicitly arbitrated. This means that the interest other applications may have in a connection is taken into account before the connection is stopped. For example, application “B” can start a connection that has already been started by application “A”. Application “A” may choose to stop the connection but the system should not stop the connection until “B” is finished with it. Using the SCNetworkConnection functions, application “A” can call SCNetworkConnectionStop on the connection and the function will return success, but the connection will not stop until “B” calls SCNetworkConnectionStop. An application can also use the linger parameter (discussed below) to register interest.

The SCNetworkConnectionStart function allows an application to indicate an interest in a connection. In this way, an application can request that the existence of the connection be tied to actions the application takes. In the simplest case, an application might want a connection to start when the application calls SCNetworkConnectionStart and stop when any of the following events occur:

• The application quits.

• The application releases the SCNetworkConnectionRef representing the connection.

• The application calls SCNetworkConnectionStop.

To indicate interest in a connection, an application can use the linger parameter of the SCNetworkConnectionStart function. An application, such as an email client, that needs to get connected, perform its tasks, and get disconnected, sets the parameter to FALSE. This indicates that the connection should stop when the application quits or releases the connection reference. A PPP dialer application, on the other hand, might choose to set the parameter to TRUE so that the user has control over the modem. The TRUE value indicates the connection should not stop when the application quits or releases the connection reference.

It’s important to note, however, that several concurrent applications might register interest in the same connection. When this is the case, the System Configuration framework keeps track of the references to the connection, stopping it when the last reference is released (or the last application holding a reference quits).

The SCNetworkConnectionStop function performs an arbitrated stop of the connection. In other words, it closes the connection if:

• There are no other interested applications currently running or holding references to the connection. If there are, the SCNetworkConnectionStop function returns success to the calling application, but the connection will persist until all interested applications terminate or release their references to the connection.

• An application calls SCNetworkConnectionStop and passes TRUE in the forceDisconnect parameter. This stops the connection regardless of the interest of other currently running applications. Most applications do not need to force a connection to stop in this way. A PPP dialer application, however, would probably choose to do this because it ensures that the connection stops when the user wants it to.

Getting the Status of a Connection

An application can use the SCNetworkConnectionGetStatus function to get the high-level status of the connection. You pass the SCNetworkConnectionRef representing the connection to the function and you receive one of the constants shown in Introduction to System Configuration Programming Guidelines.

If your application needs to know more about the PPP connection, such as when the PPP controller is authenticating to the server, you should use the SCNetworkConnectionCopyExtendedStatus function. You pass the SCNetworkConnectionRef representing the connection to the function and you receive a dictionary that contains subdictionaries for each subcomponent of the service, such as PPP, IPv4, and Modem. The PPP connection status is represented by a constant defined in the SCNetworkConnection API. Table 4-3 shows the current set of constants. Note that additional status values might be defined in the future, so your application should be able to handle an unknown value.

For more information on why you might choose to use the SCNetworkConnectionCopyExtendedStatus function, see Getting Detailed PPP Connection-Status Information.