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+ only (ignore first two steps if you don't support iOS 9+):
Set desired value for `protocol` property if needed.
-
Asynchronously call
loadInitialConfiguration. Provide a custom
VPNUOnDemandConnectionManagerobject foronDemandConnectionManagerproperty 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 should check connectionStatus property of this class to know the real VPN connection status every time VPNUConnectionStatusDidChangeNotification notification is posted.
attention: You MUST call loadInitialConfiguration method asynchronously if you are using iOS 9+ 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.
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
Not available in Mac OS X. 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+ and support custom protocol.
Warning
This method shouldn't be called from main thread.
Availability
Not available in Mac OS X. 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
Not available in Mac OS X. 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
Not available in Mac OS X. 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
YESVPN 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.
See also
connectionStatus
Availability
Available in Mac OS X v10.7. Available in iOS v8.0.
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.
Warning
This method shouldn't be called from main thread.
See also
connectionStatus
Availability
Available in Mac OS X v10.7. Available in iOS v8.0.
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.
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.