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 _SCPNETWORK_H
  24 #define _SCPNETWORK_H
  25
  26 #include <sys/cdefs.h>
  27 #include <sys/socket.h>
  28
  29 /*!
  30         @header SCPNetwork.h
  31         The SystemConfiguration framework provides access to the data used
  32                 to configure a running system.
  33
  34         Specifically, the SCPNetworkXXX() API's allow an application
  35                 to determine the status of the systems current network
  36                 configuration.
  37
  38         The APIs provided by this framework communicate with the "configd"
  39                 daemon to obtain information regarding the systems current
  40                 configuration.
  41  */
  42
  43 /*!
  44         @enum SCNStatus
  45         @discussion Returned status codes from the SCNIsReachableByAddress()
  46                 and SCNIsReachableByName() functions.
  47
  48                 The term "reachable" in these status codes reflects whether
  49                 a data packet, sent by an application into the network stack,
  50                 will be able to reach the destination host.
  51
  52                 Please not that being "able" to reach the destination host
  53                 does not guarantee that the data packet "will" reach the
  54                 host.
  55
  56         @constant SCN_REACHABLE_UNKNOWN
  57                 A determination could not be made regarding the reachability
  58                 of the specified nodename/address.
  59
  60         @constant SCN_REACHABLE_NO
  61                 The specified nodename/address can not be reached using the
  62                 current network configuration.
  63
  64         @constant SCN_REACHABLE_CONNECTION_REQUIRED
  65                 The specified nodename/address can be reached using the
  66                 current network configuration but a connection must first
  67                 be established.
  68
  69                 This status would be returned for a dialup connection which
  70                 was not currently active but could handle network traffic for
  71                 the target system.
  72
  73         @constant SCN_REACHABLE_YES
  74                 The specified nodename/address can be reached using the
  75                 current network configuration.
  76  */
  77 typedef enum {
  78         SCN_REACHABLE_UNKNOWN                   = -1,
  79         SCN_REACHABLE_NO                        =  0,
  80         SCN_REACHABLE_CONNECTION_REQUIRED       =  1,
  81         SCN_REACHABLE_YES                       =  2,
  82 } SCNStatus;
  83
  84
  85 /*!
  86         @enum SCNConnectionFlags
  87         @discussion Additional flags which reflect whether a network connection
  88                 to the specified nodename/address is reachable, requires a
  89                 connection, requires some user intervention in establishing
  90                 the connection, and whether the calling application must initiate
  91                 the connection using the SCNEstablishConnection() API.
  92
  93         @constant kSCNFlagsTransientConnection
  94                 This flag indicates that the specified nodename/address can
  95                 be reached via a transient (e.g. PPP) connection.
  96
  97         @constant kSCNFlagsConnectionAutomatic
  98                 The specified nodename/address can be reached using the
  99                 current network configuration but a connection must first
 100                 be established.  Any traffic directed to the specified
 101                 name/address will initiate the connection.
 102
 103         @constant kSCNFlagsInterventionRequired
 104                 The specified nodename/address can be reached using the
 105                 current network configuration but a connection must first
 106                 be established.  In addition, some form of user intervention
 107                 will be required to establish this connection (e.g. providing
 108                 a password, authentication token, etc.).
 109  */
 110 typedef enum {
 111         kSCNFlagsTransientConnection    =  1<<0,
 112         kSCNFlagsConnectionAutomatic    =  1<<1,
 113         kSCNFlagsInterventionRequired   =  1<<2,
 114 } SCNConnectionFlags;
 115
 116
 117 __BEGIN_DECLS
 118
 119 /*!
 120         @function SCNIsReachableByAddress
 121         @discussion Determines if the given network address is
 122                 reachable using the current network configuration.
 123
 124                 Note: This API is not thread safe.
 125         @param address Pass the network address of the desired host.
 126         @param addrlen Pass the length, in bytes, of the address.
 127         @param flags A pointer to memory which will be filled with a
 128                 set of SCNConnectionFlags related to the reachability
 129                 of the specified address.  If NULL, no flags will be
 130                 returned.
 131         @param status A pointer to memory which will be filled with the
 132                 error status associated with any error communicating with
 133                 the system configuration daemon.
 134         @result A constant of type SCNStatus indicating the reachability
 135                 of the specified node address.
 136  */
 137 SCNStatus       SCNIsReachableByAddress (const struct sockaddr  *address,
 138                                          const int              addrlen,
 139                                          int                    *flags,
 140                                          const char             **errorMessage);
 141
 142 /*!
 143         @function SCNIsReachableByName
 144         @discussion Determines if the given network host/node name is
 145                 reachable using the current network configuration.
 146         @param nodename Pass a 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 which will be filled with a
 149                 set of SCNConnectionFlags related to the reachability
 150                 of the specified address.  If NULL, no flags will be
 151                 returned.
 152         @param status A pointer to memory which will be filled with the
 153                 error status associated with any error communicating with
 154                 the system configuration daemon.
 155         @result A constant of type SCNStatus indicating the reachability
 156                 of the specified node address.
 157  */
 158 SCNStatus       SCNIsReachableByName    (const char             *nodename,
 159                                          int                    *flags,
 160                                          const char             **errorMessage);
 161
 162 __END_DECLS
 163
 164 #endif /* _SCPNETWORK_H */