CaptiveNetwork Reference

Framework
Declared in
CaptiveNetwork.h

Overview

The CaptiveNetwork programming interface allows an application to interact with Captive Network Support, the system component responsible for detecting networks that require user interaction before providing internet access. These networks are most commonly WiFi hotspots in public locations such as airports and hotels.

By calling the CNSetSupportedSSIDs function, an application can register a list of wireless network SSIDs with Captive Network Support, thereby assuming responsibility for authenticating with those networks. Typically when a user joins a captive network, Captive Network Support provides a web sheet that allows the user to authenticate with the network. If an application has registered the SSID of the captive network, however, the web sheet is suppressed, and the user can complete authentication in the appropriate application.

After a user performs authentication in the application that registered the SSID, the application should inform Captive Network Support of the result of the authentication with either the CNMarkPortalOnline function or the CNMarkPortalOffline function.

Functions by Task

Registering SSIDs

Reporting Authentication Results

Getting Network Info

Functions

CNCopyCurrentNetworkInfo

Returns the current network info for a given network interface.

CFDictionaryRef CNCopyCurrentNetworkInfo (
   CFStringRef interfaceName
);
Parameters
interfaceName

The network interface.

Return Value

A dictionary containing the interface’s current network info. Ownership follows the Create Rule.

Availability
  • Available in iOS 4.1 and later.
Declared In
CaptiveNetwork.h

CNCopySupportedInterfaces

Returns the names of all network interfaces Captive Network Support is monitoring.

CFArrayRef CNCopySupportedInterfaces (
   void
);
Return Value

The network interface names, as an array of CFStringRef objects. Ownership follows the Create Rule.

Availability
  • Available in iOS 4.1 and later.
Declared In
CaptiveNetwork.h

CNMarkPortalOffline

Informs Captive Network Support that the device is not authenticated on a captive network.

Boolean CNMarkPortalOffline (
   CFStringRef interfaceName
);
Parameters
interfaceName

The name of the interface that is now offline.

Return Value

TRUE if the operation succeeded; otherwise, FALSE.

Availability
  • Available in iOS 4.0 and later.
Declared In
CaptiveNetwork.h

CNMarkPortalOnline

Informs Captive Network Support that the application has successfully authenticated the device to a captive network. Captive Network Support notifies the rest of the system that WiFi is a viable interface.

Boolean CNMarkPortalOnline (
   CFStringRef interfaceName
);
Parameters
interfaceName

The name of the interface that is now online.

Return Value

TRUE if the operation succeeded; otherwise, FALSE.

Availability
  • Available in iOS 4.0 and later.
Declared In
CaptiveNetwork.h

CNSetSupportedSSIDs

Specifies an updated list of captive network SSIDs that the application performs authentication on.

Boolean CNSetSupportedSSIDs (
   CFArrayRef ssidArray
);
Parameters
ssidArray

An array of CFString objects representing the SSIDs the application supports.

Return Value

TRUE if the list is successfully updated; otherwise, FALSE.

Discussion

The list is maintained for as long as the application is installed.

Providing a new list replaces any earlier list the application has provided.

Availability
  • Available in iOS 4.0 and later.
Declared In
CaptiveNetwork.h

Constants

Network Info Keys

Keys that correspond to values in a network info dictionary obtained with the CNCopyCurrentNetworkInfo function.

const CFStringRef kCNNetworkInfoKeyBSSID;
const CFStringRef kCNNetworkInfoKeySSID;
const CFStringRef kCNNetworkInfoKeySSIDData;
Constants
kCNNetworkInfoKeyBSSID

The key for the network’s BSSID, which is represented as a CFStringRef object.

Available in iOS 4.1 and later.

Declared in CaptiveNetwork.h.

kCNNetworkInfoKeySSID

The key for the network’s SSID, which is represented as a CFStringRef object.

Available in iOS 4.1 and later.

Declared in CaptiveNetwork.h.

kCNNetworkInfoKeySSIDData

The key for the network’s SSID, which is represented as a CFDataRef object.

Available in iOS 4.1 and later.

Declared in CaptiveNetwork.h.