nwi/network_information.h

   1 /*
   2  * Copyright (c) 2011-2013 Apple 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
  25 #ifndef _NETWORK_INFORMATION_H_
  26 #define _NETWORK_INFORMATION_H_
  27
  28 #include <stdint.h>
  29 #include <sys/cdefs.h>
  30
  31 typedef struct _nwi_state * nwi_state_t;
  32 typedef struct _nwi_ifstate * nwi_ifstate_t;
  33
  34 __BEGIN_DECLS
  35
  36 /*
  37  * Function: nwi_state_copy
  38  * Purpose:
  39  *   Returns the current network state information.
  40  *   Release after use by calling nwi_state_release().
  41  */
  42 nwi_state_t
  43 nwi_state_copy(void);
  44
  45 /*
  46  * Function: nwi_state_release
  47  * Purpose:
  48  *   Release the memory associated with the network state.
  49  */
  50 void
  51 nwi_state_release(nwi_state_t state);
  52
  53 /*
  54  * Function: nwi_state_get_notify_key
  55  * Purpose:
  56  *   Returns the BSD notify key to use to monitor when the state changes.
  57  *
  58  * Note:
  59  *   The nwi_state_copy API uses this notify key to monitor when the state
  60  *   changes, so each invocation of nwi_state_copy returns the current
  61  *   information.
  62  */
  63 const char *
  64 nwi_state_get_notify_key(void);
  65
  66 /*
  67  * Function: nwi_state_get_first_ifstate
  68  * Purpose:
  69  *   Returns the first and highest priority interface that has connectivity
  70  *   for the specified address family 'af'. 'af' is either AF_INET or AF_INET6.
  71  *   The connectivity provided is for general networking.   To get information
  72  *   about an interface that isn't available for general networking, use
  73  *   nwi_state_get_ifstate().
  74  *
  75  *   Use nwi_ifstate_get_next() to get the next, lower priority interface
  76  *   in the list.
  77  *
  78  *   Returns NULL if no connectivity for the specified address family is
  79  *   available.
  80  */
  81 nwi_ifstate_t
  82 nwi_state_get_first_ifstate(nwi_state_t state, int af);
  83
  84 /*
  85  * Function: nwi_state_get_generation
  86  * Purpose:
  87  *   Returns the generation of the nwi_state data.
  88  *   Every time the data is updated due to changes
  89  *   in the network, this value will change.
  90  */
  91 uint64_t
  92 nwi_state_get_generation(nwi_state_t state);
  93
  94 /*
  95  * Function: nwi_ifstate_get_generation
  96  * Purpose:
  97  *   Returns the generation of the nwi_ifstate data.
  98  */
  99 uint64_t
 100 nwi_ifstate_get_generation(nwi_ifstate_t ifstate);
 101
 102 /*
 103  * Function: nwi_state_get_ifstate
 104  * Purpose:
 105  *   Return information for the specified interface 'ifname'.
 106  *
 107  *   This API directly returns the ifstate for the specified interface.
 108  *   This is the only way to access information about an interface that isn't
 109  *   available for general networking.
 110  *
 111  *   Returns NULL if no information is available for that interface.
 112  */
 113 nwi_ifstate_t
 114 nwi_state_get_ifstate(nwi_state_t state, const char * ifname);
 115
 116 /*
 117  * Function: nwi_ifstate_get_ifname
 118  * Purpose:
 119  *   Return the interface name of the specified ifstate.
 120  */
 121 const char *
 122 nwi_ifstate_get_ifname(nwi_ifstate_t ifstate);
 123
 124 /*
 125  * Type: nwi_ifstate_flags
 126  * Purpose:
 127  *   Provide information about the interface, including its IPv4 and IPv6
 128  *   connectivity, and whether DNS is configured or not.
 129  */
 130 #define NWI_IFSTATE_FLAGS_HAS_IPV4      0x1     /* has IPv4 connectivity */
 131 #define NWI_IFSTATE_FLAGS_HAS_IPV6      0x2     /* has IPv6 connectivity */
 132 #define NWI_IFSTATE_FLAGS_HAS_DNS       0x4     /* has DNS configured */
 133
 134 typedef uint64_t nwi_ifstate_flags;
 135 /*
 136  * Function: nwi_ifstate_get_flags
 137  * Purpose:
 138  *   Return the flags for the given ifstate (see above for bit definitions).
 139  */
 140 nwi_ifstate_flags
 141 nwi_ifstate_get_flags(nwi_ifstate_t ifstate);
 142
 143 /*
 144  * Function: nwi_ifstate_get_next
 145  * Purpose:
 146  *   Returns the next, lower priority nwi_ifstate_t after the specified
 147  *   'ifstate' for the protocol family 'af'.
 148  *
 149  *   Returns NULL when the end of the list is reached.
 150  */
 151 nwi_ifstate_t
 152 nwi_ifstate_get_next(nwi_ifstate_t ifstate, int af);
 153
 154 /*
 155  * Function: nwi_ifstate_compare_rank
 156  * Purpose:
 157  *   Compare the relative rank of two nwi_ifstate_t objects.
 158  *
 159  *   The "rank" indicates the importance of the underlying interface.
 160  *
 161  * Returns:
 162  *   0  if ifstate1 and ifstate2 are ranked equally
 163  *  -1  if ifstate1 is ranked ahead of ifstate2
 164  *   1  if ifstate2 is ranked ahead of ifstate1
 165  */
 166 int
 167 nwi_ifstate_compare_rank(nwi_ifstate_t ifstate1, nwi_ifstate_t ifstate2);
 168
 169 /*
 170  * Function: _nwi_state_ack
 171  * Purpose:
 172  *   Acknowledge receipt and any changes associated with the [new or
 173  *   updated] network state.
 174  */
 175 void
 176 _nwi_state_ack(nwi_state_t state, const char *bundle_id)
 177         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0);
 178
 179 /*
 180  * nwi_state_get_reachability_flags
 181  *
 182  * returns the global reachability flags for a given address family.
 183  * If no address family is passed in, it returns the global reachability
 184  * flags for either families.
 185  *
 186  * The reachability flags returned follow the definition of
 187  * SCNetworkReachabilityFlags.
 188  *
 189  * If the flags are zero (i.e. do not contain kSCNetworkReachabilityFlagsReachable), there is no connectivity.
 190  *
 191  * Otherwise, at least kSCNetworkReachabilityFlagsReachable is set:
 192  *        Reachable only
 193  *          No other connection flags are set.
 194  *        Reachable and no ConnectionRequired
 195  *          If we have connectivity for the specified address family (and we'd
 196  *          be returning the reachability flags associated with the default route)
 197  *        Reachable and ConnectionRequired
 198  *          If we do not currently have an active/primary network but we may
 199  *          be able to establish connectivity.
 200  *        Reachable and OnDemand
 201  *          If we do not currently have an active/primary network but we may
 202  *          be able to establish connective on demand.
 203  *        Reachable and TransientConnection
 204  *          This connection is transient.
 205  *        Reachable and WWAN
 206  *          This connection will be going over the cellular network.
 207  */
 208 uint32_t
 209 nwi_state_get_reachability_flags(nwi_state_t nwi_state, int af);
 210
 211 /*
 212  * nwi_ifstate_get_vpn_server
 213  *
 214  * returns a sockaddr representation of the vpn server address.
 215  * NULL if PPP/VPN/IPSec server address does not exist.
 216  */
 217 const struct sockaddr *
 218 nwi_ifstate_get_vpn_server(nwi_ifstate_t ifstate);
 219
 220 /*
 221  * nwi_ifstate_get_reachability_flags
 222  *
 223  * returns the reachability flags for the interface given an address family.
 224  * The flags returned are those determined outside of
 225  * the routing table.  [None, ConnectionRequired, OnDemand,
 226  * Transient Connection, WWAN].
 227  */
 228 uint32_t
 229 nwi_ifstate_get_reachability_flags(nwi_ifstate_t ifstate);
 230
 231 /*
 232  * nwi_ifstate_get_signature
 233  *
 234  * returns the signature and its length for an ifstate given an address family.
 235  * If AF_UNSPEC is passed in, the signature for a given ifstate is returned.
 236  *
 237  * If the signature does not exist, NULL is returned.
 238  */
 239 const uint8_t *
 240 nwi_ifstate_get_signature(nwi_ifstate_t ifstate, int af, int * length);
 241
 242
 243 /*
 244  * nwi_ifstate_get_dns_signature
 245  *
 246  * returns the signature and its length for given
 247  * ifstate with a valid dns configuration.
 248  *
 249  * If the signature does not exist, NULL is returned.
 250  *
 251  */
 252 const uint8_t *
 253 nwi_ifstate_get_dns_signature(nwi_ifstate_t ifstate, int * length);
 254
 255 __END_DECLS
 256
 257 #endif