nwi/network_information.h

   1 /*
   2  * Copyright (c) 2011 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
  30 typedef struct _nwi_state * nwi_state_t;
  31 typedef struct _nwi_ifstate * nwi_ifstate_t;
  32
  33 /*
  34  * Function: nwi_state_copy
  35  * Purpose:
  36  *   Returns the current network state information.
  37  *   Release after use by calling nwi_state_release().
  38  */
  39 nwi_state_t
  40 nwi_state_copy(void);
  41
  42 /*
  43  * Function: nwi_state_release
  44  * Purpose:
  45  *   Release the memory associated with the network state.
  46  */
  47 void
  48 nwi_state_release(nwi_state_t state);
  49
  50 /*
  51  * Function: nwi_state_get_notify_key
  52  * Purpose:
  53  *   Returns the BSD notify key to use to monitor when the state changes.
  54  *
  55  * Note:
  56  *   The nwi_state_copy API uses this notify key to monitor when the state
  57  *   changes, so each invocation of nwi_state_copy returns the current
  58  *   information.
  59  */
  60 const char *
  61 nwi_state_get_notify_key(void);
  62
  63 /*
  64  * Function: nwi_state_get_first_ifstate
  65  * Purpose:
  66  *   Returns the first and highest priority interface that has connectivity
  67  *   for the specified address family 'af'. 'af' is either AF_INET or AF_INET6.
  68  *   The connectivity provided is for general networking.   To get information
  69  *   about an interface that isn't available for general networking, use
  70  *   nwi_state_get_ifstate().
  71  *
  72  *   Use nwi_ifstate_get_next() to get the next, lower priority interface
  73  *   in the list.
  74  *
  75  *   Returns NULL if no connectivity for the specified address family is
  76  *   available.
  77  */
  78 nwi_ifstate_t
  79 nwi_state_get_first_ifstate(nwi_state_t state, int af);
  80
  81 /*
  82  * Function: nwi_state_get_generation
  83  * Purpose:
  84  *   Returns the generation (mach_time) of the nwi_state data.
  85  *   Every time the data is updated due to changes
  86  *   in the network, this value will change.
  87  */
  88 uint64_t
  89 nwi_state_get_generation(nwi_state_t state);
  90
  91 /*
  92  * Function: nwi_state_get_ifstate
  93  * Purpose:
  94  *   Return information for the specified interface 'ifname'.
  95  *
  96  *   This API directly returns the ifstate for the specified interface.
  97  *   This is the only way to access information about an interface that isn't
  98  *   available for general networking.
  99  *
 100  *   Returns NULL if no information is available for that interface.
 101  */
 102 nwi_ifstate_t
 103 nwi_state_get_ifstate(nwi_state_t state, const char * ifname);
 104
 105 /*
 106  * Function: nwi_ifstate_get_ifname
 107  * Purpose:
 108  *   Return the interface name of the specified ifstate.
 109  */
 110 const char *
 111 nwi_ifstate_get_ifname(nwi_ifstate_t ifstate);
 112
 113 /*
 114  * Type: nwi_ifstate_flags
 115  * Purpose:
 116  *   Provide information about the interface, including its IPv4 and IPv6
 117  *   connectivity, and whether DNS is configured or not.
 118  */
 119 #define NWI_IFSTATE_FLAGS_HAS_IPV4      0x1     /* has IPv4 connectivity */
 120 #define NWI_IFSTATE_FLAGS_HAS_IPV6      0x2     /* has IPv6 connectivity */
 121 #define NWI_IFSTATE_FLAGS_HAS_DNS       0x4     /* has DNS configured */
 122
 123 typedef uint64_t nwi_ifstate_flags;
 124 /*
 125  * Function: nwi_ifstate_get_flags
 126  * Purpose:
 127  *   Return the flags for the given ifstate (see above for bit definitions).
 128  */
 129 nwi_ifstate_flags
 130 nwi_ifstate_get_flags(nwi_ifstate_t ifstate);
 131
 132 /*
 133  * Function: nwi_ifstate_get_next
 134  * Purpose:
 135  *   Returns the next, lower priority nwi_ifstate_t after the specified
 136  *   'ifstate' for the protocol family 'af'.
 137  *
 138  *   Returns NULL when the end of the list is reached.
 139  */
 140 nwi_ifstate_t
 141 nwi_ifstate_get_next(nwi_ifstate_t ifstate, int af);
 142
 143 /*
 144  * Function: nwi_ifstate_compare_rank
 145  * Purpose:
 146  *   Compare the relative rank of two nwi_ifstate_t objects.
 147  *
 148  *   The "rank" indicates the importance of the underlying interface.
 149  *
 150  * Returns:
 151  *   0  if ifstate1 and ifstate2 are ranked equally
 152  *  -1  if ifstate1 is ranked ahead of ifstate2
 153  *   1  if ifstate2 is ranked ahead of ifstate1
 154  */
 155 int
 156 nwi_ifstate_compare_rank(nwi_ifstate_t ifstate1, nwi_ifstate_t ifstate2);
 157
 158 /*
 159  * Function: _nwi_state_ack
 160  * Purpose:
 161  *   Acknowledge receipt and any changes associated with the [new or
 162  *   updated] network state.
 163  */
 164 void
 165 _nwi_state_ack(nwi_state_t state, const char *bundle_id)
 166         __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0);
 167
 168 #endif