# Package com.codename1.vpn.tunnel

package com.codename1.vpn.tunnel

Writing the tunnel itself, rather than asking the system to run one.

`com.codename1.vpn.profile` asks the operating system to run an IKEv2 or IPsec client it already implements, which is what most apps want. This package is the other thing: the app receives raw IP packets and decides what happens to them.

##### Android only

`Tunnels.isSupported()` answers true on Android and false everywhere else, including iOS. Ask it, and keep a path for the answer being no.

- Android: `CN1VpnService`, which ships in the port and which the builder declares in the manifest for an app that referenced this package. It is a `VpnService` in the app's own process, needing `BIND_VPN_SERVICE` and the user's consent. The tunnel runs in that process, so the instance passed to `Tunnels.start(VpnTunnel, TunnelSetup)` is the instance that runs and everything it closed over is still there.
- iOS: not supported. A packet tunnel there is an `NEPacketTunnelProvider` in a Network Extension -- a separate process with its own bundle -- and a Java tunnel needs a virtual machine inside it. The translation that would produce one without the application shell, which uses UIKit APIs an extension may not call, has not been written. `ios.vpn.tunnel` fails the build rather than generating an extension too broken to compile.
- Simulator and desktop: a loopback transport, so the packet loop can be exercised without a device.

##### Why the API is shaped for another process anyway

`TunnelSetup.data`, `TunnelConfiguration` and the packet pooling in `PacketBuffer` all assume the tunnel may be constructed somewhere the app's statics are not, under a memory budget far below an app's. That is the shape a Network Extension needs, and it costs an Android tunnel nothing to be written that way. A tunnel that takes its configuration from `VpnTunnel.onStart(TunnelConfiguration)` rather than reaching for a static the app set is the one that stays portable.

- Related Packages
  Package
  Description
  com.codename1.vpn
  Installing and controlling a VPN configuration.
  com.codename1.vpn.profile
  Asking the operating system to run a standard VPN tunnel.
  com.codename1.vpn.spi
  The seam between the portable `com.codename1.vpn` API and each platform's native VPN machinery.
- Class
  Description
  PacketBuffer
  One IP packet on its way through the tunnel.
  TunnelConfiguration
  What the tunnel was started with.
  Tunnels
  Starts and stops a packet tunnel this application implements.
  TunnelSetup
  What an application asks the platform to set up before its tunnel runs.
  TunnelStopReason
  Why a tunnel stopped.
  TunnelTransport
  How packets reach the tunnel, which is where the two platforms differ.
  VpnTunnel
  The packet loop, written once for both platforms.