nwi/network_information.h

   1 /*
   2  * Copyright (c) 2011-2019 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 #define NWI_IFSTATE_FLAGS_HAS_CLAT46    0x0040  /* has CLAT46 configured */
 136
 137 typedef uint64_t nwi_ifstate_flags;
 138 /*
 139  * Function: nwi_ifstate_get_flags
 140  * Purpose:
 141  *   Return the flags for the given ifstate (see above for bit definitions).
 142  */
 143 nwi_ifstate_flags
 144 nwi_ifstate_get_flags(nwi_ifstate_t ifstate);
 145
 146 /*
 147  * Function: nwi_ifstate_get_next
 148  * Purpose:
 149  *   Returns the next, lower priority nwi_ifstate_t after the specified
 150  *   'ifstate' for the protocol family 'af'.
 151  *
 152  *   Returns NULL when the end of the list is reached.
 153  */
 154 nwi_ifstate_t
 155 nwi_ifstate_get_next(nwi_ifstate_t ifstate, int af);
 156
 157 /*
 158  * Function: nwi_ifstate_compare_rank
 159  * Purpose:
 160  *   Compare the relative rank of two nwi_ifstate_t objects.
 161  *
 162  *   The "rank" indicates the importance of the underlying interface.
 163  *
 164  * Returns:
 165  *   0  if ifstate1 and ifstate2 are ranked equally
 166  *  -1  if ifstate1 is ranked ahead of ifstate2
 167  *   1  if ifstate2 is ranked ahead of ifstate1
 168  */
 169 int
 170 nwi_ifstate_compare_rank(nwi_ifstate_t ifstate1, nwi_ifstate_t ifstate2);
 171
 172 /*
 173  * Function: _nwi_state_ack
 174  * Purpose:
 175  *   Acknowledge receipt and any changes associated with the [new or
 176  *   updated] network state.
 177  */
 178 void
 179 _nwi_state_ack(nwi_state_t state, const char *bundle_id)
 180         API_AVAILABLE(macos(10.8), ios(6.0));
 181
 182 /*
 183  * Function: nwi_state_get_reachability_flags
 184  * Purpose:
 185  * Returns the global reachability flags for a given address family.
 186  * If no address family is passed in, it returns the global reachability
 187  * flags for either families.
 188  *
 189  * The reachability flags returned follow the definition of
 190  * SCNetworkReachabilityFlags.
 191  *
 192  * If the flags are zero (i.e. do not contain kSCNetworkReachabilityFlagsReachable), there is no connectivity.
 193  *
 194  * Otherwise, at least kSCNetworkReachabilityFlagsReachable is set:
 195  *        Reachable only
 196  *          No other connection flags are set.
 197  *        Reachable and no ConnectionRequired
 198  *          If we have connectivity for the specified address family (and we'd
 199  *          be returning the reachability flags associated with the default route)
 200  *        Reachable and ConnectionRequired
 201  *          If we do not currently have an active/primary network but we may
 202  *          be able to establish connectivity.
 203  *        Reachable and OnDemand
 204  *          If we do not currently have an active/primary network but we may
 205  *          be able to establish connective on demand.
 206  *        Reachable and TransientConnection
 207  *          This connection is transient.
 208  *        Reachable and WWAN
 209  *          This connection will be going over the cellular network.
 210  */
 211 uint32_t
 212 nwi_state_get_reachability_flags(nwi_state_t nwi_state, int af);
 213
 214 /*
 215  * Function: nwi_state_get_interface_names
 216  * Purpose:
 217  *   Returns the list of network interface names that have connectivity.
 218  *   The list is sorted from highest priority to least, highest priority
 219  *   appearing at index 0.
 220  *
 221  *   If 'names' is NULL or 'names_count' is zero, this function returns
 222  *   the number of elements that 'names' must contain to get the complete
 223  *   list of interface names.
 224  *
 225  *   If 'names' is not NULL and 'names_count' is not zero, fills 'names' with
 226  *   the list of interface names not exceeding 'names_count'. Returns the
 227  *   number of elements that were actually populated.
 228  *
 229  * Notes:
 230  * 1. The connectivity that an interface in this list provides may not be for
 231  *    general purpose use.
 232  * 2. The string pointers remain valid only as long as 'state' remains
 233  *    valid.
 234  */
 235 unsigned int
 236 nwi_state_get_interface_names(nwi_state_t state,
 237                               const char * names[],
 238                               unsigned int names_count);
 239
 240 /*
 241  * nwi_ifstate_get_vpn_server
 242  *
 243  * returns a sockaddr representation of the vpn server address.
 244  * NULL if PPP/VPN/IPSec server address does not exist.
 245  */
 246 const struct sockaddr *
 247 nwi_ifstate_get_vpn_server(nwi_ifstate_t ifstate);
 248
 249 /*
 250  * nwi_ifstate_get_reachability_flags
 251  *
 252  * returns the reachability flags for the interface given an address family.
 253  * The flags returned are those determined outside of
 254  * the routing table.  [None, ConnectionRequired, OnDemand,
 255  * Transient Connection, WWAN].
 256  */
 257 uint32_t
 258 nwi_ifstate_get_reachability_flags(nwi_ifstate_t ifstate);
 259
 260 /*
 261  * nwi_ifstate_get_signature
 262  *
 263  * returns the signature and its length for an ifstate given an address family.
 264  * If AF_UNSPEC is passed in, the signature for a given ifstate is returned.
 265  *
 266  * If the signature does not exist, NULL is returned.
 267  */
 268 const uint8_t *
 269 nwi_ifstate_get_signature(nwi_ifstate_t ifstate, int af, int * length);
 270
 271
 272 /*
 273  * nwi_ifstate_get_dns_signature
 274  *
 275  * returns the signature and its length for given
 276  * ifstate with a valid dns configuration.
 277  *
 278  * If the signature does not exist, NULL is returned.
 279  *
 280  */
 281 const uint8_t *
 282 nwi_ifstate_get_dns_signature(nwi_ifstate_t ifstate, int * length);
 283
 284 __END_DECLS
 285
 286 #endif