SystemConfiguration.fproj/SCNetwork.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23 #ifndef _SCNETWORK_H
  24 #define _SCNETWORK_H
  25
  26 #include <sys/cdefs.h>
  27 #include <sys/types.h>
  28 #include <sys/socket.h>
  29 #include <CoreFoundation/CoreFoundation.h>
  30
  31
  32 /*!
  33         @header SCNetwork
  34         The SCNetworkCheckReachabilityXXX() APIs allow an application to
  35         determine the status of the system's current network configuration.
  36
  37         The term "reachable" reflects whether a data packet, sent by
  38         an application into the network stack, will be able to reach
  39         the destination host.
  40
  41         Please note that being able to reach the destination host
  42         does not guarantee that the data packet will reach the
  43         host.
  44
  45         The APIs provided by this framework communicate with the "configd"
  46         daemon to obtain information regarding the system's current
  47         configuration.
  48  */
  49
  50 /*!
  51         @enum SCNetworkConnectionFlags
  52         @discussion Flags that indicate whether the specified network
  53                 nodename/address is reachable, requires a connection,
  54                 requires some user intervention in establishing the
  55                 connection, and whether the calling application must
  56                 initiate the connection using the (TBD???) API.
  57
  58         @constant kSCNetworkFlagsTransientConnection
  59                 This flag indicates that the specified nodename/address can
  60                 be reached via a transient (e.g. PPP) connection.
  61
  62         @constant kSCNetworkFlagsReachable
  63                 This flag indicates that the specified nodename/address can
  64                 be reached using the current network configuration.
  65
  66         @constant kSCNetworkFlagsConnectionRequired
  67                 This flag indicates that the specified nodename/address can
  68                 be reached using the current network configuration but a
  69                 connection must first be established.
  70
  71                 As an example, this status would be returned for a dialup
  72                 connection that was not currently active but could handle
  73                 network traffic for the target system.
  74
  75         @constant kSCNetworkFlagsConnectionAutomatic
  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.  Any traffic directed
  79                 to the specified name/address will initiate the connection.
  80
  81         @constant kSCNetworkFlagsInterventionRequired
  82                 This flag indicates that the specified nodename/address can
  83                 be reached using the current network configuration but a
  84                 connection must first be established.  In addition, some
  85                 form of user intervention will be required to establish
  86                 this connection (e.g. providing a password, authentication
  87                 token, etc.).
  88  */
  89 typedef enum {
  90         kSCNetworkFlagsTransientConnection      =  1<<0,
  91         kSCNetworkFlagsReachable                =  1<<1,
  92         kSCNetworkFlagsConnectionRequired       =  1<<2,
  93         kSCNetworkFlagsConnectionAutomatic      =  1<<3,
  94         kSCNetworkFlagsInterventionRequired     =  1<<4,
  95 } SCNetworkConnectionFlags;
  96
  97
  98 __BEGIN_DECLS
  99
 100 /*!
 101         @function SCNetworkCheckReachabilityByAddress
 102         @discussion Determines if the given network address is
 103                 reachable using the current network configuration.
 104
 105                 Note: This API is not thread safe.
 106         @param address The network address of the desired host.
 107         @param addrlen The length, in bytes, of the address.
 108         @param flags A pointer to memory that will be filled with a
 109                 set of SCNetworkConnectionFlags detailing the reachability
 110                 of the specified address.
 111         @result TRUE if the network connection flags are valid; FALSE if the
 112                 status could not be determined.
 113  */
 114 Boolean
 115 SCNetworkCheckReachabilityByAddress     (
 116                                         const struct sockaddr           *address,
 117                                         const int                       addrlen,
 118                                         SCNetworkConnectionFlags        *flags
 119                                         );
 120
 121 /*!
 122         @function SCNetworkCheckReachabilityByName
 123         @discussion Determines if the given network host/node name is
 124                 reachable using the current network configuration.
 125
 126                 Note: This API is not thread safe.
 127
 128         @param nodename The node name of the desired host. This name would
 129                 be the same as that passed to gethostbyname() or getaddrinfo().
 130         @param flags A pointer to memory that will be filled with a
 131                 set of SCNetworkConnectionFlags detailing the reachability
 132                 of the specified node name.
 133         @result TRUE if the network connection flags are valid; FALSE if the
 134                 status could not be determined.
 135  */
 136 Boolean
 137 SCNetworkCheckReachabilityByName        (
 138                                         const char                      *nodename,
 139                                         SCNetworkConnectionFlags        *flags
 140                                         );
 141
 142 __END_DECLS
 143
 144 #endif /* _SCNETWORK_H */