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:successfullyInstalled: 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.
This class is a public interface of a class cluster. You are discouraged from subclassing it. 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.
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. 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.
isOnDemandEnabled
- (BOOL)isOnDemandEnabled;
Gets status of VPN On Demand setting.
Return value
YES if VPN On Demand is turned on, NO otherwise.
Discussion
This method return actual value from System Preferences.
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. 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. This method shouldn't be called from main thread.
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. This method shouldn't be called from main thread.
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. This method shouldn't be called from main thread.
setupWithServerItem:successfullyInstalled:
- (NSError *)setupWithServerItem:(VPNUServerItem *)serverItem successfullyInstalled:(BOOL *)successfullyInstalled;
Installs VPN profile for the specified server item.
Parameters
- serverItem
- Server item object to perform setup for. Cannot be nil.
- successfullyInstalled
- This value is set to YES, if VPN profile is successfully 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. This method shouldn't be called from main thread.
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. This method shouldn't be called from main thread.
stopVPNWithError:
- (void)stopVPNWithError:(NSError **)error;
Stops the VPN tunnel.
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.
Discussion
This method returns after VPN tunnel disconnect 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. This method shouldn't be called from main thread.
Properties
appScheme
@property (copy) NSString *appScheme;
Application scheme used by local server.
customProfileDownloadHTMLPath
@property (nonatomic, copy) NSString *customProfileDownloadHTMLPath;
An absolute path to your custom local HTML page which is shown to user during profile download process.
customProtocolProfileName
@property (copy) NSString *customProtocolProfileName;
Custom name for a downloaded VPN profile if Wise or OpenVPN is selected as protocol.
Discussion
If not set - `profileName` is used.
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.
profileName
@property (copy) NSString *profileName;
Custom name for a downloaded VPN profile.
protocol
@property VPNUProtocol protocol;
Protocol used when downloading and configuring VPN profile.
Discussion
Set this property before calling setupWithServerItem:successfullyInstalled: method. Default value is VPNUProtocolIPSec.
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.
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.