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