iOS Developer Library

Developer

SystemConfiguration Framework Reference CaptiveNetwork Reference

Options
Deployment Target:

On This Page

CaptiveNetwork Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import SystemConfiguration;

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

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Availability

    Available in iOS 4.0 and later.

  • 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.

    Declaration

    Objective-C

    Boolean CNMarkPortalOnline ( CFStringRef interfaceName );

    Parameters

    interfaceName

    The name of the interface that is now online.

    Return Value

    TRUE if the operation succeeded; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Objective-C

    Boolean CNMarkPortalOffline ( CFStringRef interfaceName );

    Parameters

    interfaceName

    The name of the interface that is now offline.

    Return Value

    TRUE if the operation succeeded; otherwise, FALSE.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Availability

    Available in iOS 4.0 and later.

  • Returns the current network info for a given network interface.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Availability

    Available in iOS 4.1 and later.

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

    Declaration

    Objective-C

    CFArrayRef CNCopySupportedInterfaces ( void );

    Return Value

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

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Availability

    Available in iOS 4.1 and later.

Constants

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

    Declaration

    Objective-C

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

    Constants

    • kCNNetworkInfoKeyBSSID

      kCNNetworkInfoKeyBSSID

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

      Available in iOS 4.1 and later.

    • kCNNetworkInfoKeySSID

      kCNNetworkInfoKeySSID

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

      Available in iOS 4.1 and later.

    • kCNNetworkInfoKeySSIDData

      kCNNetworkInfoKeySSIDData

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

      Available in iOS 4.1 and later.