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