Table of Contents

Class VpnHoodApp

Namespace
VpnHood.AppLib.App
Assembly
VpnHood.AppLib.App.dll

Represents the VPN app: its settings and VPN profiles, its connection through the device's VPN service, its account, ads and updates, and the API a UI reads it through (Api).

public class VpnHoodApp : Singleton<VpnHoodApp>, IPremiumFeatureChecker, IDisposable, IAsyncDisposable
Inheritance
VpnHoodApp
Implements
Inherited Members

Remarks

A head makes it once, through its platform's Init, which calls Init(IDevice, AppOptions), and reaches it as Instance.

Fields

FileNameLog

The name of the app's log file in its device-only storage folder (NoBackupStorageFolderPath), for a reader that holds no app.

public const string FileNameLog = "app.log"

Field Value

string

LogAppHeader

The header above the app's own log in the log the API sends, before the VPN service's.

public const string LogAppHeader = "VPN App Log"

Field Value

string

LogVpnServiceHeader

The header above the VPN service's log in the log the API sends.

public const string LogVpnServiceHeader = "VPN Service Log"

Field Value

string

Properties

Api

Gets the API a UI reads the app through: the six interfaces a browser reaches over HTTP, answered in process.

public VpnHoodApi Api { get; }

Property Value

VpnHoodApi

ConnectionState

Gets the connection's state as the app shows it.

public AppConnectionState ConnectionState { get; }

Property Value

AppConnectionState

Remarks

It reads Updating while the app installs its update, Diagnosing while a check of the network runs, and None while a disconnect finishes in the background; Initializing while the split by country or by IP address builds its list, and Connected for the last seconds after an ad closed.

Descriptor

Gets what this build is and offers, as the UI reads it.

public AppDescriptor Descriptor { get; }

Property Value

AppDescriptor

IsIdle

Gets a value indicating whether ConnectionState is None, as it is while a disconnect finishes in the background too.

public bool IsIdle { get; }

Property Value

bool

LocalWebHost

Gets the web host this device loads its UI from, made at the first read and not started, or null for a head with no web host (WebHostFactory).

public IAppWebHost? LocalWebHost { get; }

Property Value

IAppWebHost

Exceptions

InvalidOperationException

The head set WebHostFactory but no WebRootZipAsset.

RemoteWebHost

Gets the web host a phone pairs with, made at the first read, or null for a head with no web host (WebHostFactory).

public IAppWebHost? RemoteWebHost { get; }

Property Value

IAppWebHost

Remarks

In a Debug build, or with the RemoteAccess command, it stays up for the life of the process and asks for no pairing; when that changes, as the command is turned on or off outside a Debug build, the app replaces the host.

Exceptions

InvalidOperationException

The head set WebHostFactory but no WebRootZipAsset.

Resources

Gets the app's own words.

public AppResources Resources { get; }

Property Value

AppResources

Services

Gets the app's services and the providers it works through.

public AppServices Services { get; }

Property Value

AppServices

Settings

Gets the app's settings, which Save() saves.

public AppSettings Settings { get; }

Property Value

AppSettings

SettingsService

Gets the service that keeps the settings.

public AppSettingsService SettingsService { get; }

Property Value

AppSettingsService

State

Gets the app's state, made at each read, for a caller with no window to measure, whose system bars are then the defaults.

public AppState State { get; }

Property Value

AppState

StorageFolderPath

Gets the folder that holds the settings and the VPN profiles (StorageFolderPath).

public string StorageFolderPath { get; }

Property Value

string

UiAssetProvider

Gets the files the app's UI draws from, unpacked from UiZipAssets, which the web host serves too, or null for a head that named none.

public IAssetProvider? UiAssetProvider { get; }

Property Value

IAssetProvider

UserSettings

Gets the person's settings (UserSettings).

public UserSettings UserSettings { get; }

Property Value

UserSettings

VpnProfileService

Gets the VPN profiles.

public VpnProfileService VpnProfileService { get; }

Property Value

VpnProfileService

Methods

Connect(IUiContext?, ConnectOptions?, CancellationToken)

Connects the VPN, ending a connection under way first.

public Task Connect(IUiContext? uiContext, ConnectOptions? connectOptions, CancellationToken cancellationToken)

Parameters

uiContext IUiContext

The caller's window, which asks the person for the VPN permission and for notifications, or null when it has none, and then a missing permission fails and nothing is asked.

connectOptions ConnectOptions

The connect's options, or null for the defaults.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task

A task that completes once the VPN is connected.

Remarks

Unless the app is installing an update, it clears the last error first, and a connect applies every pending change of the settings. A failed connect throws the app's error: the server's refusal (SessionException), the VPN service's failure, an ad the session required that failed, or the system's own VPN failure, as where there is no window to ask for the VPN permission. The state keeps it as its last error (LastError), but for a refusal while the app installs an update, a connect a newer one replaced, and one its caller tries again (IsRetried). A token canceled while the connect runs may come as NoInternetException, as the check after the failure finds no internet.

Exceptions

EndPointDiscoveryException

A diagnosing connect found no endpoint of the server.

VpnServiceContractException

The app and the VPN engine it bundles share no version of the VPN service's contract.

ConnectionTimeoutException

The connection did not come up in the app's connect time (ConnectTimeout).

TimeoutException

The VPN service did not start in time, or the system's VPN permission prompt was not answered.

PremiumOnlyException

Always on is for premium only, and the connect was always on's.

NoInternetException

A check after a failed connect found the device without internet.

NoStableVpnException

A diagnosing connect found the tunnel not working.

InvalidOperationException

The split by country has no IP location data, or no known country; the client connected with no session; or, on a diagnosing connect, the access key has neither endpoints nor a real host name.

NotExistsException

No VPN profile is given and none is selected, or the profile does not exist.

AppUpdatingException

The app is installing an update.

UserCanceledException

A disconnect, or a newer connect, ended the connect, or the person refused the system's VPN permission.

OperationCanceledException

cancellationToken was canceled, while the connect waited for a disconnect or while it connected.

Disconnect()

Disconnects the VPN as a person does: it also stops always on, until a person connects or the service starts again, and lifts this app's kill switch block, even when the stop failed; in lockdown the block stays, by the split's settings.

public Task Disconnect()

Returns

Task

A task that represents the asynchronous operation.

Remarks

It takes no token: a person's disconnect is finished whoever stops waiting for it.

Exceptions

FormatException

In lockdown, the device's split list of IP ranges is not valid.

NotSupportedException

In lockdown, Linux has no nftables, or the service is in no cgroup v2 group of its own.

ExternalException

The system refused the kill switch's change: Linux's nft, or Windows' filtering engine.

Dispose(bool)

Releases the instance; with disposing and when it is the registered one, unregisters it.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true when called from Dispose().

Remarks

A second call does nothing.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

Remarks

It stops always on, disconnects the VPN where DisconnectOnDispose says so and the VPN can be disconnected, as it cannot while an update installs, lets a reconfigure under way end, then disposes the app. A second call waits for the first one's end.

Init(IDevice, AppOptions)

Creates the app: it makes the storage folders, opens the log, reads the settings and the VPN profiles, adds the built-in access keys, and registers the app as Instance.

public static VpnHoodApp Init(IDevice device, AppOptions options)

Parameters

device IDevice

The device, whose VPN service the app runs.

options AppOptions

The head's options.

Returns

VpnHoodApp

The app.

Exceptions

InvalidOperationException

An app is registered already.

FormatException

A built-in access key (AccessKeys) is not valid.

NotSupportedException

A built-in access key's version is not supported.

JsonException

A built-in access key's JSON is not valid.

InvalidDataException

A built-in access key's JSON is null.

OverflowException

A duration in a built-in access key is out of range.

Exception

An ad network item has both country lists (IncludeCountryCodes).

IOException

A storage folder could not be made, or a file of the app's written.

UnauthorizedAccessException

The process may not write the storage folders.

IsPremiumFeatureAllowed(AppFeature)

Returns a value indicating whether a feature may be used on the current plan.

public bool IsPremiumFeatureAllowed(AppFeature feature)

Parameters

feature AppFeature

The feature.

Returns

bool

true if the feature may be used; otherwise, false.

Remarks

Every feature is allowed on a build with no premium tier (Premium), and every one its tier does not sell; one it sells, only on a premium VPN profile.

UpdateUi()

Sets off applying the settings as they stand, as a save does, without saving them.

public void UpdateUi()

Events

ConnectionStateChanged

Occurs when ConnectionState has changed, on a thread pool thread.

public event EventHandler? ConnectionStateChanged

Event Type

EventHandler