SystemConfiguration.fproj/SCNetwork.h

   1 /*
   2  * Copyright (c) 2000-2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 #ifndef _SCNETWORK_H
  27 #define _SCNETWORK_H
  28
  29 #include <sys/cdefs.h>
  30 #include <sys/types.h>
  31 #include <sys/socket.h>
  32 #include <CoreFoundation/CoreFoundation.h>
  33
  34
  35 /*!
  36         @header SCNetwork
  37
  38         SCNetworkCheckReachabilityXXX()
  39
  40         The SCNetworkCheckReachabilityXXX() APIs allow an application to
  41         determine the status of the system's current network configuration
  42         and the accessibility of a target host/address.
  43
  44         The term "reachable" reflects whether a data packet, sent by
  45         an application into the network stack, can be sent to the
  46         the target host/address.  Please note that their is no
  47         guarantee that the data packet will actually be received by
  48         the host.
  49
  50
  51         SCNetworkInterfaceRefreshConfiguration()
  52
  53         This API sends a notification to interested network configuration
  54         agents to retry their configuraton immediately. For example, calling
  55         this API will cause the DHCP client to contact the DHCP server
  56         immediately rather than waiting until its timeout has expired.
  57         The utility of this API is to allow the caller to give a hint to
  58         the system that the network infrastructure/configuration has changed.
  59  */
  60
  61 /*!
  62         @enum SCNetworkConnectionFlags
  63         @discussion Flags that indicate whether the specified network
  64                 nodename/address is reachable, requires a connection,
  65                 requires some user intervention in establishing the
  66                 connection, and whether the calling application must
  67                 initiate the connection using the (TBD???) API.
  68
  69         @constant kSCNetworkFlagsTransientConnection
  70                 This flag indicates that the specified nodename/address can
  71                 be reached via a transient (e.g. PPP) connection.
  72
  73         @constant kSCNetworkFlagsReachable
  74                 This flag indicates that the specified nodename/address can
  75                 be reached using the current network configuration.
  76
  77         @constant kSCNetworkFlagsConnectionRequired
  78                 This flag indicates that the specified nodename/address can
  79                 be reached using the current network configuration but a
  80                 connection must first be established.
  81
  82                 As an example, this status would be returned for a dialup
  83                 connection that was not currently active but could handle
  84                 network traffic for the target system.
  85
  86         @constant kSCNetworkFlagsConnectionAutomatic
  87                 This flag indicates that the specified nodename/address can
  88                 be reached using the current network configuration but a
  89                 connection must first be established.  Any traffic directed
  90                 to the specified name/address will initiate the connection.
  91
  92         @constant kSCNetworkFlagsInterventionRequired
  93                 This flag indicates that the specified nodename/address can
  94                 be reached using the current network configuration but a
  95                 connection must first be established.  In addition, some
  96                 form of user intervention will be required to establish
  97                 this connection (e.g. providing a password, authentication
  98                 token, etc.).
  99
 100         @constant kSCNetworkFlagsIsLocalAddress
 101                 This flag indicates that the specified nodename/address
 102                 is one associated with a network interface on the current
 103                 system.
 104
 105         @constant kSCNetworkFlagsIsDirect
 106                 This flag indicates that network traffic to the specified
 107                 nodename/address will not go through a gateway but is routed
 108                 directly to one of the interfaces in the system.
 109  */
 110 enum {
 111         kSCNetworkFlagsTransientConnection      = 1<<0,
 112         kSCNetworkFlagsReachable                = 1<<1,
 113         kSCNetworkFlagsConnectionRequired       = 1<<2,
 114         kSCNetworkFlagsConnectionAutomatic      = 1<<3,
 115         kSCNetworkFlagsInterventionRequired     = 1<<4,
 116         kSCNetworkFlagsIsLocalAddress           = 1<<16,
 117         kSCNetworkFlagsIsDirect                 = 1<<17
 118 };
 119 typedef uint32_t        SCNetworkConnectionFlags;
 120
 121 __BEGIN_DECLS
 122
 123 /*!
 124         @function SCNetworkCheckReachabilityByAddress
 125         @discussion Determines if the given network address is
 126                 reachable using the current network configuration.
 127         @param address The network address of the desired host.
 128         @param addrlen The length, in bytes, of the address.
 129         @param flags A pointer to memory that will be filled with a
 130                 set of SCNetworkConnectionFlags detailing the reachability
 131                 of the specified address.
 132         @result TRUE if the network connection flags are valid; FALSE if the
 133                 status could not be determined.
 134  */
 135 Boolean
 136 SCNetworkCheckReachabilityByAddress     (
 137                                         const struct sockaddr           *address,
 138                                         int                             addrlen,
 139                                         SCNetworkConnectionFlags        *flags
 140                                         );
 141
 142 /*!
 143         @function SCNetworkCheckReachabilityByName
 144         @discussion Determines if the given network host/node name is
 145                 reachable using the current network configuration.
 146         @param nodename The node name of the desired host. This name would
 147                 be the same as that passed to gethostbyname() or getaddrinfo().
 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 TRUE if the network connection flags are valid; FALSE if the
 152                 status could not be determined.
 153  */
 154 Boolean
 155 SCNetworkCheckReachabilityByName        (
 156                                         const char                      *nodename,
 157                                         SCNetworkConnectionFlags        *flags
 158                                         );
 159 /*!
 160         @function SCNetworkInterfaceRefreshConfiguration
 161         @discussion Sends a notification to interested configuration agents
 162                 to have them immediately retry their configuration over a
 163                 particular network interface.
 164                 Note: This API must be invoked by root (uid == 0).
 165
 166         @param ifName The BSD name of the network interface e.g. CFSTR("en0").
 167         @result TRUE if the notification was sent; FALSE otherwise.
 168  */
 169 Boolean
 170 SCNetworkInterfaceRefreshConfiguration  (
 171                                         CFStringRef ifName
 172                                         );
 173 __END_DECLS
 174
 175 #endif /* _SCNETWORK_H */