nwi/network_information.h

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