VPN Unlimited SDK - Mac - v1.2 - Reference

VPNUConfigurator

This class provides an interface for controlling VPN connections.

Discussion

Before using this class you must authorize or register with the help of VPNUAuthorizer class. You must pass the same VPNUTransport instance to its constructor as you have passed to VPNUAuthorizer instance constructor.

A basic workflow after initializing looks as follows: For iOS 9+ / macOS 10.11+ only (ignore first two steps if you don't support iOS 9+ / macOS 10.11+):

Set desired value for `protocol` property if needed.
Asynchronously call loadInitialConfiguration.
Provide a custom VPNUOnDemandConnectionManager object for onDemandConnectionManager property if you want to manage VPN On Demand Rules.
Configure VPN server item using setupWithServerItem:alreadyInstalled: method.
Connect to the configured VPN server using startVPNWithError: method.
Disconnect at any time using stopVPNWithError: method.

You can check connectionStatus property of this class to know the real VPN connection status every time VPNUConnectionStatusDidChangeNotification notification is posted or simply use KVO.

attention: This class is a public interface of a class cluster. You are discouraged from subclassing it. attention: You MUST call loadInitialConfiguration method asynchronously if you are using iOS 9+ / macOS 10.11+ BEFORE any call to instance of this class.

Extends: NSObject

Declared in: VPNUConfigurator.h

Class Methods

configuratorWithTransport:

 + (instancetype)configuratorWithTransport:(VPNUTransport *)transport;

Creates and returns a newly allocated VPN configurator object with the specified transport object.

Parameters

transport: The transport object for internal usage.

Return value

An initialized VPN configurator object or nil if the object couldn't be created.

Discussion

This method is a convenience constructor.

Availability

Available in Mac OS X v10.7. Available in iOS v7.0.

isNEVPNManagerSupportedByPlatform

 + (BOOL)isNEVPNManagerSupportedByPlatform;

Tells whether current platform version supports NEVPNManager.

Return value

YES if current platform version supports NEVPNManager, NO otherwise.

Discussion

For macOS this method returns YES for OS version starting from 10.11+. Although NEVPNManager is available for 10.10, it just doesn't work.

Instance Methods

enableVPN

 - (NSError *)enableVPN;

Sets VPN configuration for current app enabled.

Return value

nil if VPN was enabled, error object otherwise.

Discussion

If succeeded, this method disables VPN configurations of other apps. This method blocks a calling thread.

Warning

This method shouldn't be called from main thread.

Availability

Available in Mac OS X v10.11. Available in iOS v8.0.

initWithTransport:

 - (instancetype)initWithTransport:(VPNUTransport *)transport NS_DESIGNATED_INITIALIZER;

Initializes and returns a newly allocated VPN configurator object with the specified transport object.

Parameters

transport: The transport object for internal usage.

Return value

An initialized VPN configurator object or nil if the object couldn't be created.

Availability

Available in Mac OS X v10.7. Available in iOS v7.0.

loadInitialConfiguration

 - (BOOL)loadInitialConfiguration;

Loads VPN manager for selected protocol.

Return value

YES if load was successful, NO otherwise.

Discussion

Call this method asynchronously to load default VPN manager for selected protocol if you are using this class on iOS 9+ / macOS 10.11 and support custom protocol.

Warning

This method shouldn't be called from main thread.

Availability

Available in Mac OS X v10.11. Available in iOS v9.0.

loadPreferences

 - (NSError *)loadPreferences;

Loads VPN configuration preferences.

Return value

nil if preferences were loaded successfully, error object otherwise.

Discussion

This method loads the preferences for VPN configuration of the current application. You can call this method if you want to retrieve connectionStatus property before any call to configurator. This method blocks a calling thread.

Warning

This method shouldn't be called from main thread.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

removeProfile

 - (NSError *)removeProfile;

Removes the VPN configuration from the Network Extension preferences if present.

Return value

nil if removal was successful, error object otherwise.

Discussion

This method blocks a calling thread.

Warning

This method shouldn't be called from main thread.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

setOnDemandEnabled:

 - (NSError *)setOnDemandEnabled:(BOOL)enabled;

Turns VPN On Demand on or off.

Parameters

enabled: Boolean value which controls VPN On Demand toggling. If set to YES VPN On Demand is turned on, otherwise VPN On Demand is turned off.

Return value

nil on success, error object otherwise.

Discussion

This method blocks a calling thread.

Warning

This method shouldn't be called from main thread.

Availability

Available in Mac OS X v10.7. Available in iOS v7.0.

setupWithServerItem:alreadyInstalled:

 - (NSError *)setupWithServerItem:(VPNUServerItem *)serverItem alreadyInstalled:(BOOL *)alreadyInstalled;

Installs VPN profile for the specified server item.

Parameters

serverItem: Server item object to perform setup for. Cannot be nil.
alreadyInstalled: This value is set to YES, if VPN profile is already installed.

Return value

nil if setup was successful, error object otherwise.

Discussion

This method first retrieves VPN profile information for the specified server item. If this step was succesful, it then tries to install a new VPN profile into the system using the information retrieved in the first step. If configuration downloaded for the server item is corrupted (e.g., has no server address) the profile is automatically deleted. This method blocks a calling thread.

Warning

This method shouldn't be called from main thread.

Availability

Available in Mac OS X v10.7. Available in iOS v7.0.

startVPNWithError:

 - (BOOL)startVPNWithError:(NSError **)error;

Starts the VPN tunnel using the current VPN configuration.

Parameters

error: If method generates an error, a new error object is created and returned as an object pointed to by this parameter. Can be nil.

Return value

YES if the VPN tunnel was started successfully, NO if an error occurred.

Discussion

This method returns after VPN tunnel connection process is started and does not signals about the actual success of the VPN connection. In order to obtain the connection status, use the connectionStatus property. This method blocks a calling thread.

Warning

This method shouldn't be called from main thread.

Properties

appScheme

@property (copy) NSString *appScheme;

Application scheme used by local server.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

customProfileDownloadHTMLPath

@property (nonatomic, copy) NSString *customProfileDownloadHTMLPath;

An absolute path to your custom local HTML page which is shown to user during profile download process.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

onDemandConnectionManager

@property (strong) VPNUOnDemandConnectionManager *onDemandConnectionManager;

If you want to manage VPN On Demand Rules using VPNUOnDemandConnectionManager, set its instance here.

Discussion

If you don't set this value before configuring a new connection with setupWithServerItem: default On Demand rules will be applied for the connection.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

profileName

@property (copy) NSString *profileName;

Custom name for a downloaded VPN profile.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

protocol

@property VPNUProtocol protocol;

Protocol used when downloading and configuring VPN profile.

Discussion

Set this property before calling setupWithServerItem:alreadyInstalled: method. Default value is VPNUProtocolIPSec.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

useNEVPNManager

@property BOOL useNEVPNManager;

Tells the configurator to use NEVPNManager class for configuring and controlling a VPN.

Discussion

If set to YES, user will be able to turn a VPN connection on and off inside the host application. If set to NO, user will have to explicitly download profiles and turn a VPN connection on and off inside iOS Settings (pre-iOS8 style). Default value is YES.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

VPNEnabled

@property (readonly, getter=isVPNEnabled) BOOL VPNEnabled;

This property is set to YES if VPN configuration for current app is enabled.

Discussion

This property will be set to NO when other VPN configurations (from other apps) are enabled.

Availability

Available in Mac OS X v10.7. Available in iOS v8.0.

Typedefs

VPNUConnectionStatus

 typedef NS_ENUM(NSInteger, VPNUConnectionStatus) { VPNUConnectionStatusInvalid = 0, VPNUConnectionStatusDisconnected = 1, VPNUConnectionStatusConnecting = 2, VPNUConnectionStatusConnected = 3, VPNUConnectionStatusReasserting = 4, VPNUConnectionStatusDisconnecting = 5, } NS_ENUM_AVAILABLE( 10_7, 8_0);

VPN status codes

Constants

VPNUConnectionStatusInvalid: The VPN is not configured.
VPNUConnectionStatusDisconnected: The VPN is disconnected.
VPNUConnectionStatusConnecting: The VPN is connecting.
VPNUConnectionStatusConnected: The VPN is connected.
VPNUConnectionStatusReasserting: The VPN is reconnecting following loss of underlying network connectivity.
VPNUConnectionStatusDisconnecting: The VPN is disconnecting.