Class TerracottaAndroidAPI

ffi/TerracottaAndroidAPI.java:57–476

An API to handle Terracotta Android. Unlike normal JNI bindings, relocating this class to another package is supported. State Definition For Android platform, developers must invoke #initialize with a VpnServiceCallback to initialize the rust backend. The

 * <p>A RuntimeException will be thrown if an error occured in native level.</p>
 */
public final class TerracottaAndroidAPI {
    /**
     * <p>Callback for receiving VpnService Requests</p>
     *
     * <p>When receiving one, {@link #getPendingVpnServiceRequest()} is available to get the pending request.
     * Developer must make sure either {@link VpnServiceRequest#startVpnService} or {@link VpnServiceRequest#reject()} is invoked,
     * or Terracotta would stuck and EasyTier cannot submit a new VpnService Request.</p>
     *
     * @implNote The VpnServiceRequest must be fulfilled in 30 seconds, or it will be considered as timeout.
     */
    public interface VpnServiceCallback {
        void onStartVpnService();
    }

    /**
     * <p>A VpnService Request submitted by Terracotta. See {@link VpnServiceCallback}</p>
     */
    public interface VpnServiceRequest {
        /**
         * Create a Vpn Connection and fulfill the VpnService Request.
         *
         * @param builder A pre-configured VpnService builder.
         * @return The established Vpn Connection. Developers must close this file descriptor after EasyTier exits.
         * @throws RuntimeException if {@link VpnService.Builder#establish()} returns null.
         * @implNote Developers is able to configure the builder before passing it into Terracotta
         * to fully-custom the connection.
         */
        ParcelFileDescriptor startVpnService(VpnService.Builder builder);

        /**
         * <p>Reject the VpnServiceRequest.</p>
         */
        void reject();
    }

    /**
     * <p>Metadata of Terracotta Android</p>
     */
    public static final class Metadata {
        private final String terracottaVersion;

        private final long terracottaCompileTime;

        private final String easyTierVersion;

        private Metadata(String terracottaVersion, long terracottaCompileTime, String easyTierVersion) {
            this.terracottaVersion = terracottaVersion;
            this.terracottaCompileTime = terracottaCompileTime;
            this.easyTierVersion = easyTierVersion;
        }

        /**
         * @return Terracotta Android version.
         */
        public String getTerracottaVersion() {
            return terracottaVersion;
        }