nwi/network_information.h

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