this repo has no description
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
32typedef struct _nwi_state * nwi_state_t;
33typedef 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 */
44nwi_state_t
45nwi_state_copy(void);
46
47/*
48 * Function: nwi_state_release
49 * Purpose:
50 * Release the memory associated with the network state.
51 */
52void
53nwi_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 */
65const char *
66nwi_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 */
83nwi_ifstate_t
84nwi_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 */
93uint64_t
94nwi_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 */
101uint64_t
102nwi_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 */
115nwi_ifstate_t
116nwi_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 */
123const char *
124nwi_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
137typedef 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 */
143nwi_ifstate_flags
144nwi_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 */
154nwi_ifstate_t
155nwi_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 */
169int
170nwi_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 */
178void
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 */
211uint32_t
212nwi_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 */
235unsigned int
236nwi_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 */
246const struct sockaddr *
247nwi_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 */
257uint32_t
258nwi_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 */
268const uint8_t *
269nwi_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 */
281const uint8_t *
282nwi_ifstate_get_dns_signature(nwi_ifstate_t ifstate, int * length);
283
284__END_DECLS
285
286#endif