SystemConfiguration.fproj/SCNetwork.h

   1 /*
   2  * Copyright (c) 2000-2003 Apple Computer, 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 <sys/cdefs.h>
  28 #include <sys/types.h>
  29 #include <sys/socket.h>
  30 #include <CoreFoundation/CoreFoundation.h>
  31
  32
  33 /*!
  34         @header SCNetwork
  35         @discussion The SCNetwork API contains functions an application can
  36                 use to determine remote host reachability and notify the
  37                 system of configuration changes.
  38
  39                 The two SCNetworkCheckReachability functions allow an
  40                 application to determine the status of the system's current
  41                 network configuration and the reachability of a target host
  42                 or address.
  43
  44                 "Reachability" reflects whether a data packet, sent by an
  45                 application into the network stack, can leave the local
  46                 computer.  Note that reachability does <i>not</i> guarantee
  47                 that the data packet will actually be received by the host.
  48
  49                 The SCNetworkInterfaceRefreshConfiguration function sends a
  50                 notification to interested network configuration agents to
  51                 retry their configuration immediately. For example, calling
  52                 this function will cause the DHCP client to contact the DHCP
  53                 server immediately rather than waiting until its timeout has
  54                 expired.  The utility of this function is to allow the caller
  55                 to give a hint to the system that the network infrastructure
  56                 or configuration has changed.
  57  */
  58
  59 /*!
  60         @enum SCNetworkConnectionFlags
  61         @discussion Flags that indicate whether the specified network
  62                 nodename or address is reachable, whether a connection is
  63                 required, and whether some user intervention may be required
  64                 when establishing a connection.
  65         @constant kSCNetworkFlagsTransientConnection
  66                 This flag indicates that the specified nodename or address can
  67                 be reached via a transient connection, such as PPP.
  68         @constant kSCNetworkFlagsReachable
  69                 This flag indicates that the specified nodename or address can
  70                 be reached using the current network configuration.
  71         @constant kSCNetworkFlagsConnectionRequired
  72                 This flag indicates that the specified nodename or address can
  73                 be reached using the current network configuration, but a
  74                 connection must first be established.
  75
  76                 As an example, this status would be returned for a dialup
  77                 connection that was not currently active, but could handle
  78                 network traffic for the target system.
  79         @constant kSCNetworkFlagsConnectionAutomatic
  80                 This flag indicates that the specified nodename or address can
  81                 be reached using the current network configuration, but a
  82                 connection must first be established.  Any traffic directed
  83                 to the specified name or address will initiate the connection.
  84         @constant kSCNetworkFlagsInterventionRequired
  85                 This flag indicates that the specified nodename or address can
  86                 be reached using the current network configuration, but a
  87                 connection must first be established.  In addition, some
  88                 form of user intervention will be required to establish this
  89                 connection, such as providing a password, an authentication
  90                 token, etc.
  91
  92                 Note: At the present time, this flag will only be returned
  93                 in the case where you have a dial-on-traffic configuration
  94                 (ConnectionAutomatic), where an attempt to connect has
  95                 already been made, and where some error (e.g. no dial tone,
  96                 no answer, bad password, ...) was encountered during the
  97                 automatic connection attempt.  In this case the PPP controller
  98                 will stop attempting to establish a connection until the user
  99                 has intervened.
 100         @constant kSCNetworkFlagsIsLocalAddress
 101                 This flag indicates that the specified nodename or address
 102                 is one associated with a network interface on the current
 103                 system.
 104         @constant kSCNetworkFlagsIsDirect
 105                 This flag indicates that network traffic to the specified
 106                 nodename or address will not go through a gateway, but is
 107                 routed directly to one of the interfaces in the system.
 108  */
 109 enum {
 110         kSCNetworkFlagsTransientConnection      = 1<<0,
 111         kSCNetworkFlagsReachable                = 1<<1,
 112         kSCNetworkFlagsConnectionRequired       = 1<<2,
 113         kSCNetworkFlagsConnectionAutomatic      = 1<<3,
 114         kSCNetworkFlagsInterventionRequired     = 1<<4,
 115         kSCNetworkFlagsIsLocalAddress           = 1<<16,
 116         kSCNetworkFlagsIsDirect                 = 1<<17
 117 };
 118 typedef uint32_t        SCNetworkConnectionFlags;
 119
 120 __BEGIN_DECLS
 121
 122 /*!
 123         @function SCNetworkCheckReachabilityByAddress
 124         @discussion Determines if the given network address is
 125                 reachable using the current network configuration.
 126         @param address The network address of the desired host.
 127         @param addrlen The length, in bytes, of the address.
 128         @param flags A pointer to memory that will be filled with a
 129                 set of SCNetworkConnectionFlags detailing the reachability
 130                 of the specified address.
 131         @result Returns TRUE if the network connection flags are valid;
 132                 FALSE if the status could not be determined.
 133  */
 134 Boolean
 135 SCNetworkCheckReachabilityByAddress     (
 136                                         const struct sockaddr           *address,
 137                                         int                             addrlen,
 138                                         SCNetworkConnectionFlags        *flags
 139                                         );
 140
 141 /*!
 142         @function SCNetworkCheckReachabilityByName
 143         @discussion Determines if the given network host or node name is
 144                 reachable using the current network configuration.
 145         @param nodename The node name of the desired host. This name would
 146                 be the same as that passed to the gethostbyname(3) or
 147                 getaddrinfo(3) functions.
 148         @param flags A pointer to memory that will be filled with a
 149                 set of SCNetworkConnectionFlags detailing the reachability
 150                 of the specified node name.
 151         @result Returns TRUE if the network connection flags are valid;
 152                 FALSE if the status could not be determined.
 153  */
 154 Boolean
 155 SCNetworkCheckReachabilityByName        (
 156                                         const char                      *nodename,
 157                                         SCNetworkConnectionFlags        *flags
 158                                         );
 159
 160 /*!
 161         @function SCNetworkInterfaceRefreshConfiguration
 162         @discussion Sends a notification to interested configuration agents
 163                 to have them immediately retry their configuration over a
 164                 particular network interface.
 165
 166                 Note: This function must be invoked by root (uid == 0).
 167         @param ifName The BSD name of the network interface, such as
 168                 CFSTR("en0").
 169         @result Returns TRUE if the notification was sent; FALSE otherwise.
 170  */
 171 Boolean
 172 SCNetworkInterfaceRefreshConfiguration  (
 173                                         CFStringRef ifName
 174                                         );
 175
 176 __END_DECLS
 177
 178 #endif /* _SCNETWORK_H */