Interface IVpnAdapter
- Namespace
- VpnHood.Net.VpnAdapters.Abstractions
- Assembly
- VpnHood.Net.VpnAdapters.Abstractions.dll
Represents a VPN adapter: a virtual network interface that the host's traffic is routed into, whose packets a VPN reads and writes as an IPacketTransport.
public interface IVpnAdapter : IPacketTransport, IDisposable- Inherited Members
Remarks
An adapter is made once and started and stopped many times. TunVpnAdapter is the base class of VpnHood's adapters, one per platform.
Properties
CanProtectSocket
Gets a value indicating whether the adapter can keep a socket's traffic out of the tunnel.
bool CanProtectSocket { get; }Property Value
IsStarted
Gets a value indicating whether the adapter is started.
bool IsStarted { get; }Property Value
Methods
GetPrimaryAdapterAddress(IpVersion)
Gets the host's primary address of an IP version: the one it reaches the internet from, outside the tunnel.
IPAddress? GetPrimaryAdapterAddress(IpVersion ipVersion)Parameters
ipVersionIpVersionThe IP version.
Returns
GetPrimaryAdapterDnsServers()
Gets the DNS servers of the network the tunnel runs over, which a protected socket reaches outside the tunnel; not the tunnel's own.
IReadOnlyList<IPAddress> GetPrimaryAdapterDnsServers()Returns
- IReadOnlyList<IPAddress>
The DNS servers; none where they are unknown.
IsIpVersionSupported(IpVersion)
Determines whether the host's network, outside the tunnel, supports an IP version.
bool IsIpVersionSupported(IpVersion ipVersion)Parameters
ipVersionIpVersionThe IP version.
Returns
Remarks
It tells whether the primary interface has an address of that version, for routing and split-tunneling decisions and to know whether the server can be reached with it. It says nothing of what the tunnel itself carries.
IsNatSupported(IpVersion)
Determines whether the adapter's NAT translates an IP version. A server forwards a version the adapter does not translate by its own forwarders.
bool IsNatSupported(IpVersion ipVersion)Parameters
ipVersionIpVersionThe IP version.
Returns
ProtectSocket(Socket)
Keeps a socket's traffic out of the tunnel, so it reaches the network directly. Call it before the socket is bound or connected.
bool ProtectSocket(Socket socket)Parameters
socketSocketThe socket, not bound yet.
Returns
- bool
true if the socket is protected; false if it cannot be, for example when the host has no primary address of the socket's IP version.
ProtectSocket(Socket, IPAddress)
Keeps a socket's traffic to a given address out of the tunnel, so it reaches the network directly. Call it before the socket is bound or connected.
bool ProtectSocket(Socket socket, IPAddress ipAddress)Parameters
socketSocketThe socket, not bound yet.
ipAddressIPAddressThe remote address the socket will reach.
Returns
RefreshPrimaryAdapterIps()
Looks at the host's network again for its primary addresses, as a change of the host's addresses makes the adapter do, and raises PrimaryAdapterIpChanged when they differ from the last ones.
void RefreshPrimaryAdapterIps()Remarks
For a caller that needs GetPrimaryAdapterAddress(IpVersion) and IsIpVersionSupported(IpVersion) to tell the network as it is now: the OS may move the host's traffic to another network without an address change. An adapter that is stopped, starting or restarting is left alone: its start finds the addresses.
Start(VpnAdapterOptions, CancellationToken)
Starts the adapter: makes its interface with its addresses, DNS servers, routes, NAT and app filter, opens it and starts reading packets.
Task Start(VpnAdapterOptions options, CancellationToken cancellationToken)Parameters
optionsVpnAdapterOptionsThe options this run uses, which each restart uses again.
cancellationTokenCancellationTokenThe token to monitor for cancellation requests.
Returns
- Task
A task that represents the asynchronous operation. It completes when the adapter is up.
Remarks
Await one start before the next. From the start on, the adapter keeps itself started until Stop(), disposal, or a failure it does not recover from (without AutoRestart), which raises Failed.
Exceptions
- ObjectDisposedException
The adapter is disposed.
- OperationCanceledException
cancellationTokenwas canceled, or a stop or disposal came during the start.
Stop()
Stops the adapter and removes its interface, with its routes and DNS servers. A restart under way ends first, and a pending retry is dropped, even when the adapter is already stopped.
void Stop()Remarks
The adapter counts as stopped even when closing or removing the interface fails: the error reaches the caller.
Exceptions
- ObjectDisposedException
The adapter is disposed.
Events
Disposed
Occurs when the adapter is disposed.
event EventHandler? DisposedEvent Type
Failed
Occurs when the adapter stopped on its own and stays down: by repeated I/O errors, by losing its interface, or by a restart that could not start it again. Its owner must act, a client by ending its session.
event EventHandler<Exception>? FailedEvent Type
Remarks
It is raised on a thread-pool task, after the failure. A stop, a disposal or a new start by the owner that begins before that task runs cancels it; one that begins while a handler runs does not interrupt the handler. It is not raised with AutoRestart, where the adapter retries instead. The owner's stop or disposal does not raise it, nor does a failed owner's start, whose caller gets the exception.
PrimaryAdapterIpChanged
Occurs when the adapter finds new primary addresses without a restart, as when the OS rotates a temporary IPv6 address within its network.
event EventHandler? PrimaryAdapterIpChangedEvent Type
Remarks
It is raised on the thread that saw the network change, only when the addresses found differ from the last ones; not for the start's own discovery, nor when a stop clears them.
PrimaryNetworkChanged
Occurs when the host moved to other networks and the adapter took their primary addresses without a restart: what was connected from the old networks may be dead, though an OS may keep it open, as Linux does.
event EventHandler? PrimaryNetworkChangedEvent Type
Remarks
It is raised on the thread that saw the network change. The primary addresses may stay the same.
Started
Occurs when the adapter is up, with the options it runs with: after the owner's start and after each restart, which may make the interface anew. What points at the interface from outside, such as a kill switch's block, must follow it.
event EventHandler<VpnAdapterOptions>? StartedEvent Type
Remarks
It is raised on the starting thread, once the adapter is up and before the start or the restart completes. A handler may stop or dispose the adapter, and start it again once it has stopped it; it must not wait for another start or restart of it. A run that is over by a handler's turn is not announced to that handler, and one run's handlers return before the next run's are called, except those of a run a handler itself starts. A stop or a disposal on another thread does not wait for the handlers: one may still run, or be called, as that stop returns.