SystemConfiguration.fproj/CaptiveNetwork.h

   1 /*
   2  * Copyright (c) 2009-2016, 2018, 2019, 2020 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 #ifndef _CAPTIVENETWORK_H
  25 #define _CAPTIVENETWORK_H
  26
  27 #include <os/availability.h>
  28 #include <sys/cdefs.h>
  29 #include <CoreFoundation/CoreFoundation.h>
  30
  31 CF_IMPLICIT_BRIDGING_ENABLED
  32 CF_ASSUME_NONNULL_BEGIN
  33
  34 /*!
  35         @header CaptiveNetwork
  36         @discussion The CaptiveNetwork API allows applications to interact
  37                 with Captive Network Support. Captive Network Support is a
  38                 system component responsible for detecting and help users
  39                 navigate networks that require interaction before providing
  40                 internet access. The most common Captive Networks are WiFi
  41                 Hotspots in places like airports, restaurants, and hotels.
  42                 Captive Network Support will attempt to authenticate if
  43                 possible or drop a user in to a web sheet if authentication
  44                 is not possible. In the web sheet the user has an opportunity
  45                 to authenticate or disassociate from the network.
  46
  47                 The following APIs are designed for third party applications
  48                 that may handle authentication on these networks on behalf of
  49                 the user.
  50
  51                 These APIs are treated as advisory only.
  52                 There is no guarantee or contract that the operating system
  53                 will take the intended action.
  54  */
  55
  56 __BEGIN_DECLS
  57
  58 /*!
  59         @function CNSetSupportedSSIDs
  60         @discussion Provides Captive Network Support with an updated list of
  61                 SSIDs that this application will perform authentication on.
  62
  63                 Captive Network Support suppresses showing the Web Sheet
  64                 for a captive Wi-Fi network if that network's SSID is in the
  65                 specified list.
  66
  67                 On iOS, the registrations persist until the application is
  68                 removed from the device.
  69
  70                 On MacOSX, the registrations persist as long as the application
  71                 is running.
  72
  73         @param ssidArray A CFArray of CFStrings of the SSIDs.
  74         @result Returns TRUE if the operation succeeded, FALSE otherwise.
  75  */
  76 Boolean
  77 CNSetSupportedSSIDs     (CFArrayRef     ssidArray)
  78     API_AVAILABLE(macos(10.8))
  79     API_DEPRECATED_WITH_REPLACEMENT("Replaced by <NetworkExtension/NEHotspotHelper.h>", ios(4.0,9.0))
  80     SPI_AVAILABLE(tvos(9.0), watchos(1.0), bridgeos(1.0));
  81
  82 /*!
  83         @function CNMarkPortalOnline
  84         @discussion Tells Captive Network Support that your application has
  85                 authenticated the device to the network. Captive Network Support
  86                 will notify the rest of the system that WiFi is now a viable
  87                 interface.
  88         @param interfaceName Name of the interface that is now online.
  89         @result Returns TRUE if the operation succeeded, FALSE otherwise.
  90  */
  91 Boolean
  92 CNMarkPortalOnline      (CFStringRef    interfaceName)
  93     API_AVAILABLE(macos(10.8))
  94     API_DEPRECATED_WITH_REPLACEMENT("Replaced by <NetworkExtension/NEHotspotHelper.h>", ios(4.0,9.0))
  95     SPI_AVAILABLE(tvos(9.0), watchos(1.0), bridgeos(1.0));
  96
  97 /*!
  98         @function CNMarkPortalOffline
  99         @discussion Tells Captive Network Support that the device is not
 100                 authenticated on the given network interface.
 101         @param interfaceName Name of the interface that is still captive.
 102         @result Returns TRUE if the operation succeeded, FALSE otherwise.
 103  */
 104 Boolean
 105 CNMarkPortalOffline     (CFStringRef    interfaceName)
 106     API_AVAILABLE(macos(10.8))
 107     API_DEPRECATED_WITH_REPLACEMENT("Replaced by <NetworkExtension/NEHotspotHelper.h>", ios(4.0,9.0))
 108     SPI_AVAILABLE(tvos(9.0), watchos(1.0), bridgeos(1.0));
 109
 110 /*!
 111  @function CNCopySupportedInterfaces
 112  @discussion copies a list of all interfaces CaptiveNetworkSupport is monitoring.
 113  @result An array of CFStringRef- BSD interface names.
 114          Returns NULL if an error was encountered.
 115          You MUST release the returned value.
 116  */
 117 CFArrayRef __nullable
 118 CNCopySupportedInterfaces       (void)
 119     API_AVAILABLE(macos(10.8), ios(4.1))
 120     SPI_AVAILABLE(tvos(9.0), watchos(1.0), bridgeos(1.0));
 121
 122 /*!
 123  @constant kCNNetworkInfoKeySSIDData
 124  @discussion NetworkInfo Dictionary key for SSID in CFData format
 125  */
 126 extern const CFStringRef kCNNetworkInfoKeySSIDData
 127     API_AVAILABLE(ios(4.1))
 128     SPI_AVAILABLE(macos(10.6), tvos(9.0), watchos(1.0), bridgeos(1.0));
 129
 130 /*!
 131  @constant kCNNetworkInfoKeySSID
 132  @discussion NetworkInfo Dictionary key for SSID in CFString format
 133  */
 134 extern const CFStringRef kCNNetworkInfoKeySSID
 135     API_AVAILABLE(ios(4.1))
 136     SPI_AVAILABLE(macos(10.6), tvos(9.0), watchos(1.0), bridgeos(1.0));
 137
 138 /*!
 139  @constant kCNNetworkInfoKeyBSSID
 140  @discussion NetworkInfo Dictionary key for BSSID in CFString format
 141  */
 142 extern const CFStringRef kCNNetworkInfoKeyBSSID
 143     API_AVAILABLE(ios(4.1))
 144     SPI_AVAILABLE(macos(10.6), tvos(9.0), watchos(1.0), bridgeos(1.0));
 145
 146 /*!
 147  @function CNCopyCurrentNetworkInfo
 148  @discussion Returns the network information for the specified interface when the requesting application meets one of following 4 requirements -.
 149         1. application is using CoreLocation API and has the user's authorization to access location.
 150         2. application has used the NEHotspotConfiguration API to configure the current Wi-Fi network.
 151         3. application has active VPN configurations installed.
 152         4. application has active NEDNSSettingsManager configurations installed.
 153
 154         - An application that is linked against iOS 12.0 SDK and above must have the "com.apple.developer.networking.wifi-info" entitlement.
 155         - An application will receive a pseudo network information if it is linked against an SDK before iOS 13.0, and if it fails to meet any of the
 156           above requirements.
 157         - An application will receive NULL if it is linked against iOS 13.0 SDK (or newer), and if it fails to meet any of the above requirements.
 158         - On Mac Catalyst platform, to receive current Wi-Fi network information, an application must have "com.apple.developer.networking.wifi-info"
 159          entitlement and user's authorization to access location.
 160
 161         Network Information dictionary will contain the following keys, and values:
 162         <pre>
 163         @textblock
 164         Keys                      : Values
 165         =======================================
 166         kCNNetworkInfoKeySSIDData : CFDataRef
 167         kCNNetworkInfoKeySSID     : CFStringRef
 168         kCNNetworkInfoKeyBSSID    : CFStringRef
 169         @/textblock
 170         </pre>
 171
 172         Pseudo network information will contain "Wi-Fi" SSID and "00:00:00:00:00:00" BSSID. For China region, the SSID will be "WLAN".
 173  @param interfaceName Name of the interface you are interested in
 174  @result Network Information dictionary associated with the interface.
 175          Returns NULL if an error was encountered.
 176          You MUST release the returned value.
 177  */
 178 CFDictionaryRef __nullable
 179 CNCopyCurrentNetworkInfo        (CFStringRef    interfaceName)
 180 API_DEPRECATED_WITH_REPLACEMENT("[NEHotspotNetwork fetchCurrentWithCompletionHandler:]", ios(4.1, API_TO_BE_DEPRECATED), macCatalyst(14.0, API_TO_BE_DEPRECATED))
 181 SPI_AVAILABLE(macos(10.6), tvos(9.0), watchos(1.0), bridgeos(1.0));
 182
 183 __END_DECLS
 184
 185 CF_ASSUME_NONNULL_END
 186 CF_IMPLICIT_BRIDGING_DISABLED
 187
 188 #endif  /* _CAPTIVENETWORK_H */