SystemConfiguration.fproj/CaptiveNetwork.h

   1 /*
   2  * Copyright (c) 2009-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 #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  */
  73 Boolean
  74 CNSetSupportedSSIDs     (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  */
  85 Boolean
  86 CNMarkPortalOnline      (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  */
  95 Boolean
  96 CNMarkPortalOffline     (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  */
 106 CFArrayRef
 107 CNCopySupportedInterfaces       (void)                          __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_4_1);
 108
 109 #if     TARGET_OS_EMBEDDED
 110
 111 /*!
 112  @constant kCNNetworkInfoKeySSIDData
 113  @discussion NetworkInfo Dictionary key for SSID in CFData format
 114  */
 115 extern const CFStringRef kCNNetworkInfoKeySSIDData              __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1);
 116
 117 /*!
 118  @constant kCNNetworkInfoKeySSID
 119  @discussion NetworkInfo Dictionary key for SSID in CFString format
 120  */
 121 extern const CFStringRef kCNNetworkInfoKeySSID                  __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1);
 122
 123 /*!
 124  @constant kCNNetworkInfoKeyBSSID
 125  @discussion NetworkInfo Dictionary key for BSSID in CFString format
 126  */
 127 extern const CFStringRef kCNNetworkInfoKeyBSSID                 __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1);
 128
 129 /*!
 130  @function CNCopyCurrentNetworkInfo
 131  @discussion Returns the Network Info for the specified interface.
 132         For example, Network Info dictionary will contain the following
 133         keys, and values:
 134         <pre>
 135         @textblock
 136         Keys                      : Values
 137         =======================================
 138         kCNNetworkInfoKeySSIDData : CFDataRef
 139         kCNNetworkInfoKeySSID     : CFStringRef
 140         kCNNetworkInfoKeyBSSID    : CFStringRef
 141         @/textblock
 142         </pre>
 143  @param interfaceName Name of the interface you are interested in
 144  @result Network Info dictionary associated with the interface.
 145          Returns NULL if an error was encountered.
 146          You MUST release the returned value.
 147  */
 148 CFDictionaryRef
 149 CNCopyCurrentNetworkInfo        (CFStringRef interfaceName)     __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_4_1);
 150
 151 #endif  // TARGET_OS_EMBEDDED
 152
 153 __END_DECLS
 154
 155 #endif  /* _CAPTIVENETWORK_H */