1/* 2 * Copyright (c) 2009-2012 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 <Availability.h> 28#include <sys/cdefs.h> 29#include <CoreFoundation/CoreFoundation.h> 30 31/*! 32 @header CaptiveNetwork 33 @discussion The CaptiveNetwork API allows applications to interact 34 with Captive Network Support. Captive Network Support is a 35 system component responsible for detecting and help users 36 navigate networks that require interaction before providing 37 internet access. The most common Captive Networks are WiFi 38 Hotspots in places like airports, restaurants, and hotels. 39 Captive Network Support will attempt to authenticate if 40 possible or drop a user in to a web sheet if authentication 41 is not possible. In the web sheet the user has an opportunity 42 to authenticate or disassociate from the network. 43 44 The following APIs are designed for third party applications 45 that may handle authentication on these networks on behalf of 46 the user. 47 48 These APIs are treated as advisory only. 49 There is no guarantee or contract that the operating system 50 will take the intended action. 51 */ 52 53__BEGIN_DECLS 54 55/*! 56 @function CNSetSupportedSSIDs 57 @discussion Provides Captive Network Support with an updated list of 58 SSIDs that this application will perform authentication on. 59 60 Captive Network Support suppresses showing the Web Sheet 61 for a captive Wi-Fi network if that network's SSID is in the 62 specified list. 63 64 On iOS, the registrations persist until the application is 65 removed from the device. 66 67 On MacOSX, the registrations persist as long as the application 68 is running. 69 70 @param ssidArray A CFArray of CFStrings of the SSIDs. 71 @result Returns TRUE if the operation succeeded, FALSE otherwise. 72 */ 73Boolean 74CNSetSupportedSSIDs (CFArrayRef ssidArray) __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_4_0); 75 76/*! 77 @function CNMarkPortalOnline 78 @discussion Tells Captive Network Support that your application has 79 authenticated the device to the network. Captive Network Support 80 will notify the rest of the system that WiFi is now a viable 81 interface. 82 @param interfaceName Name of the interface that is now online. 83 @result Returns TRUE if the operation succeeded, FALSE otherwise. 84 */ 85Boolean 86CNMarkPortalOnline (CFStringRef interfaceName) __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_4_0); 87 88/*! 89 @function CNMarkPortalOffline 90 @discussion Tells Captive Network Support that the device is not 91 authenticated on the given network interface. 92 @param interfaceName Name of the interface that is still captive. 93 @result Returns TRUE if the operation succeeded, FALSE otherwise. 94 */ 95Boolean 96CNMarkPortalOffline (CFStringRef interfaceName) __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_4_0); 97 98 99/*! 100 @function CNCopySupportedInterfaces 101 @discussion copies a list of all interfaces CaptiveNetworkSupport is monitoring. 102 @result An array of CFStringRef- BSD interface names. 103 Returns NULL if an error was encountered. 104 You MUST release the returned value. 105 */ 106CFArrayRef 107CNCopySupportedInterfaces (void) __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_4_1); 108 109/*! 110 @constant kCNNetworkInfoKeySSIDData 111 @discussion NetworkInfo Dictionary key for SSID in CFData format 112 */ 113extern const CFStringRef kCNNetworkInfoKeySSIDData __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1); 114 115/*! 116 @constant kCNNetworkInfoKeySSID 117 @discussion NetworkInfo Dictionary key for SSID in CFString format 118 */ 119extern const CFStringRef kCNNetworkInfoKeySSID __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1); 120 121/*! 122 @constant kCNNetworkInfoKeyBSSID 123 @discussion NetworkInfo Dictionary key for BSSID in CFString format 124 */ 125extern const CFStringRef kCNNetworkInfoKeyBSSID __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1); 126 127/*! 128 @function CNCopyCurrentNetworkInfo 129 @discussion Returns the Network Info for the specified interface. 130 For example, Network Info dictionary will contain the following 131 keys, and values: 132 <pre> 133 @textblock 134 Keys : Values 135 ======================================= 136 kCNNetworkInfoKeySSIDData : CFDataRef 137 kCNNetworkInfoKeySSID : CFStringRef 138 kCNNetworkInfoKeyBSSID : CFStringRef 139 @/textblock 140 </pre> 141 @param interfaceName Name of the interface you are interested in 142 @result Network Info dictionary associated with the interface. 143 Returns NULL if an error was encountered. 144 You MUST release the returned value. 145 */ 146CFDictionaryRef 147CNCopyCurrentNetworkInfo (CFStringRef interfaceName) __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1); 148 149__END_DECLS 150 151#endif /* _CAPTIVENETWORK_H */ 152