SystemConfiguration.fproj/SCNetwork.h

   1 /*
   2  * Copyright (c) 2000, 2001, 2003-2009 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _SCNETWORK_H
  25 #define _SCNETWORK_H
  26
  27 #include <Availability.h>
  28 #include <sys/cdefs.h>
  29 #include <sys/types.h>
  30 #include <sys/socket.h>
  31 #include <CoreFoundation/CoreFoundation.h>
  32
  33
  34 /*!
  35         @header SCNetwork
  36         @discussion The SCNetwork API contains functions an application can
  37                 use to determine remote host reachability and notify the
  38                 system of configuration changes.
  39
  40                 The two SCNetworkCheckReachability functions allow an
  41                 application to determine the status of the system's current
  42                 network configuration and the reachability of a target host
  43                 or address.
  44
  45                 "Reachability" reflects whether a data packet, sent by an
  46                 application into the network stack, can leave the local
  47                 computer.  Note that reachability does <i>not</i> guarantee
  48                 that the data packet will actually be received by the host.
  49  */
  50
  51 /*!
  52         @enum SCNetworkConnectionFlags
  53         @discussion Flags that indicate whether the specified network
  54                 nodename or address is reachable, whether a connection is
  55                 required, and whether some user intervention may be required
  56                 when establishing a connection.
  57
  58                 Note: the SCNetworkConnection flags have been deprecated
  59                 in favor of the newer SCNetworkReachability flags defined
  60                 in SCNetworkReachability.h.
  61         @constant kSCNetworkFlagsTransientConnection
  62                 This flag indicates that the specified nodename or address can
  63                 be reached via a transient connection, such as PPP.
  64         @constant kSCNetworkFlagsReachable
  65                 This flag indicates that the specified nodename or address can
  66                 be reached using the current network configuration.
  67         @constant kSCNetworkFlagsConnectionRequired
  68                 This flag indicates that the specified nodename or address can
  69                 be reached using the current network configuration, but a
  70                 connection must first be established.
  71
  72                 As an example, this status would be returned for a dialup
  73                 connection that was not currently active, but could handle
  74                 network traffic for the target system.
  75         @constant kSCNetworkFlagsConnectionAutomatic
  76                 This flag indicates that the specified nodename or address can
  77                 be reached using the current network configuration, but a
  78                 connection must first be established.  Any traffic directed
  79                 to the specified name or address will initiate the connection.
  80         @constant kSCNetworkFlagsInterventionRequired
  81                 This flag indicates that the specified nodename or address can
  82                 be reached using the current network configuration, but a
  83                 connection must first be established.  In addition, some
  84                 form of user intervention will be required to establish this
  85                 connection, such as providing a password, an authentication
  86                 token, etc.
  87
  88                 Note: At the present time, this flag will only be returned
  89                 in the case where you have a dial-on-traffic configuration
  90                 (ConnectionAutomatic), where an attempt to connect has
  91                 already been made, and where some error (e.g. no dial tone,
  92                 no answer, bad password, ...) was encountered during the
  93                 automatic connection attempt.  In this case the PPP controller
  94                 will stop attempting to establish a connection until the user
  95                 has intervened.
  96         @constant kSCNetworkFlagsIsLocalAddress
  97                 This flag indicates that the specified nodename or address
  98                 is one associated with a network interface on the current
  99                 system.
 100         @constant kSCNetworkFlagsIsDirect
 101                 This flag indicates that network traffic to the specified
 102                 nodename or address will not go through a gateway, but is
 103                 routed directly to one of the interfaces in the system.
 104  */
 105 enum {
 106         kSCNetworkFlagsTransientConnection      = 1<<0,
 107         kSCNetworkFlagsReachable                = 1<<1,
 108         kSCNetworkFlagsConnectionRequired       = 1<<2,
 109         kSCNetworkFlagsConnectionAutomatic      = 1<<3,
 110         kSCNetworkFlagsInterventionRequired     = 1<<4,
 111         kSCNetworkFlagsIsLocalAddress           = 1<<16,
 112         kSCNetworkFlagsIsDirect                 = 1<<17,
 113 };
 114 typedef uint32_t        SCNetworkConnectionFlags;
 115
 116 __BEGIN_DECLS
 117
 118 /*!
 119         @function SCNetworkCheckReachabilityByAddress
 120         @discussion Determines if the given network address is
 121                 reachable using the current network configuration.
 122
 123                 Note: this API has been deprecated but you can
 124                       get equivalent results with :
 125 <pre>
 126         SCNetworkReachabiltyRef   target;
 127         SCNetworkReachabiltyFlags flags = 0;
 128         Boolean                   ok;
 129
 130         target = SCNetworkReachabilityCreateWithAddress(NULL, address);
 131         ok = SCNetworkReachabilityGetFlags(target, &flags);
 132         CFRelease(target);
 133 </pre>
 134         @param address The network address of the desired host.
 135         @param addrlen The length, in bytes, of the address.
 136         @param flags A pointer to memory that will be filled with a
 137                 set of SCNetworkConnectionFlags detailing the reachability
 138                 of the specified address.
 139         @result Returns TRUE if the network connection flags are valid;
 140                 FALSE if the status could not be determined.
 141  */
 142 Boolean
 143 SCNetworkCheckReachabilityByAddress     (
 144                                         const struct sockaddr           *address,
 145                                         socklen_t                       addrlen,
 146                                         SCNetworkConnectionFlags        *flags
 147                                         )                               __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_6,__IPHONE_NA,__IPHONE_NA);
 148
 149 /*!
 150         @function SCNetworkCheckReachabilityByName
 151         @discussion Determines if the given network host or node name is
 152                 reachable using the current network configuration.
 153
 154                 Note: this API has been deprecated but you can
 155                       get equivalent results with :
 156 <pre>
 157         SCNetworkReachabilityRef   target;
 158         SCNetworkReachabilityFlags flags = 0;
 159         Boolean                   ok;
 160
 161         target = SCNetworkReachabilityCreateWithName(NULL, name);
 162         ok = SCNetworkReachabilityGetFlags(target, &flags);
 163         CFRelease(target);
 164 </pre>
 165         @param nodename The node name of the desired host. This name would
 166                 be the same as that passed to the gethostbyname(3) or
 167                 getaddrinfo(3) functions.
 168         @param flags A pointer to memory that will be filled with a
 169                 set of SCNetworkConnectionFlags detailing the reachability
 170                 of the specified node name.
 171         @result Returns TRUE if the network connection flags are valid;
 172                 FALSE if the status could not be determined.
 173  */
 174 Boolean
 175 SCNetworkCheckReachabilityByName        (
 176                                         const char                      *nodename,
 177                                         SCNetworkConnectionFlags        *flags
 178                                         )                               __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_6,__IPHONE_NA,__IPHONE_NA);
 179
 180 /*!
 181         @function SCNetworkInterfaceRefreshConfiguration
 182         @discussion Sends a notification to interested configuration agents
 183                 to have them immediately retry their configuration over a
 184                 particular network interface.
 185
 186                 Note: This function must be invoked by root (uid == 0).
 187         @param ifName The BSD name of the network interface, such as
 188                 CFSTR("en0").
 189         @result Returns TRUE if the notification was sent; FALSE otherwise.
 190         @deprecated in version 10.4. Replaced with SCNetworkInterfaceForceConfigurationRefresh.
 191  */
 192 Boolean
 193 SCNetworkInterfaceRefreshConfiguration  (
 194                                         CFStringRef                     ifName
 195                                         )                               __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_1,__MAC_10_5,__IPHONE_NA,__IPHONE_NA);
 196
 197 __END_DECLS
 198
 199 #endif /* _SCNETWORK_H */