### Execute Provider Setup Commands

Source: https://context7.com/leap/bitmask_android/llms.txt

Utilize ProviderAPICommand to send setup commands to the ProviderAPI service. Supports various operations like setting up a provider, downloading certificates, updating invalid certificates, and fetching GeoIP data or MOTD. Callbacks can be handled using ResultReceiver.

```java
import se.leap.bitmaskclient.providersetup.ProviderAPICommand;
import se.leap.bitmaskclient.providersetup.ProviderAPI;
import se.leap.bitmaskclient.base.models.Provider;
import android.os.Bundle;
import android.os.ResultReceiver;

// Set up a new provider (downloads config, certificates, etc.)
Provider provider = new Provider("https://riseup.net");
ProviderAPICommand.execute(context, ProviderAPI.SET_UP_PROVIDER, provider);

// Download VPN certificate
ProviderAPICommand.execute(context, ProviderAPI.DOWNLOAD_VPN_CERTIFICATE, provider);

// Update invalid VPN certificate (when certificate expired)
ProviderAPICommand.execute(context, ProviderAPI.UPDATE_INVALID_VPN_CERTIFICATE, provider);

// Download GeoIP data for gateway selection
ProviderAPICommand.execute(context, ProviderAPI.DOWNLOAD_GEOIP_JSON, provider);

// Download Message of the Day
ProviderAPICommand.execute(context, ProviderAPI.DOWNLOAD_MOTD, provider);

// Execute with result receiver for callbacks
ResultReceiver receiver = new ResultReceiver(new Handler(Looper.getMainLooper())) {
    @Override
    protected void onReceiveResult(int resultCode, Bundle resultData) {
        switch (resultCode) {
            case ProviderAPI.PROVIDER_OK:
                // Provider setup successful
                break;
            case ProviderAPI.PROVIDER_NOK:
                String error = resultData.getString(ProviderAPI.ERRORS);
                // Handle error
                break;
            case ProviderAPI.CORRECTLY_DOWNLOADED_VPN_CERTIFICATE:
                // Certificate ready
                break;
        }
    }
};
ProviderAPICommand.execute(context, ProviderAPI.SET_UP_PROVIDER, provider, receiver);

// Execute with additional parameters
Bundle params = new Bundle();
params.putLong(ProviderAPI.DELAY, 5000); // Add 5 second delay
ProviderAPICommand.execute(context, ProviderAPI.DOWNLOAD_GEOIP_JSON, params, provider);
```

--------------------------------

### Install Modern GL Libraries

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

Install updated Mesa libraries to resolve issues with outdated GL libraries that can prevent the emulator from starting.

```shell
sudo apt-get install mesa-utils
```

--------------------------------

### Install fastlane

Source: https://github.com/leap/bitmask_android/blob/master/src/README.md

Follow the official fastlane documentation to set up fastlane for Android development.

```bash
https://docs.fastlane.tools/getting-started/android/setup/
```

--------------------------------

### Start Main Activity

Source: https://context7.com/leap/bitmask_android/llms.txt

Standard intent to launch the main activity of the application.

```java
// Start main activity
Intent mainIntent = new Intent(context, StartActivity.class);
mainIntent.setAction(Intent.ACTION_MAIN);
startActivity(mainIntent);
```

--------------------------------

### Install C Libraries for Cross-Compilation

Source: https://github.com/leap/bitmask_android/blob/master/README.md

Installs essential C libraries required for cross-compiling dependencies like openssl, openvpn, and tor for the Bitmask Android client.

```bash
sudo apt-get -y install make gcc swig file lib32stdc++6 lib32z1 autoconf autogen automake autopoint autotools-dev gettext-base libtool patch pkg-config mesa-utils
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/leap/bitmask_android/blob/master/fastlane/README.md

Ensure you have the latest version of the Xcode command line tools installed before proceeding with Fastlane installation.

```sh
xcode-select --install
```

--------------------------------

### Install pythong3-babel

Source: https://github.com/leap/bitmask_android/blob/master/src/README.md

Install the python3-babel package, which may be required for localization tasks.

```bash
apt install pythong3-babel
```

--------------------------------

### Install OpenJDK 21

Source: https://github.com/leap/bitmask_android/blob/master/README.md

Installs OpenJDK 21 on Debian/Ubuntu-based systems. This is a prerequisite for compiling the Bitmask Android client.

```bash
sudo apt-get update -qq && \
    apt-get install -y openjdk-21-jdk
```

--------------------------------

### Configure Android SDK and NDK Environment Variables

Source: https://github.com/leap/bitmask_android/blob/master/README.md

Sets environment variables for Android SDK and NDK paths. Ensure `<path/where/you/installed/android/sdk>` is replaced with your actual SDK installation directory.

```bash
export ANDROID_HOME=<path/where/you/installed/android/sdk>
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/28.2.13676358
export PATH=$ANDROID_NDK_HOME:$PATH
export PATH=$ANDROID_HOME/platform-tools:$PATH
export PATH=$ANDROID_HOME/tools/bin:$PATH
```

--------------------------------

### Control VPN Connection Lifecycle with EipCommand

Source: https://context7.com/leap/bitmask_android/llms.txt

Use EipCommand static methods to control the VPN connection. Options include starting with or without traffic blocking (early routes), specifying gateway index, stopping the VPN, initiating traffic blocking, checking certificate validity, and launching specific VPN profiles.

```java
import se.leap.bitmaskclient.eip.EipCommand;
import android.content.Context;

// Start VPN connection with early routes (blocks traffic until connected)
EipCommand.startVPN(context, true);

// Start VPN connection without early routes
EipCommand.startVPN(context, false);

// Start VPN with specific gateway index (0 = nearest, 1 = second nearest, etc.)
EipCommand.startVPN(context, true, 0);

// Stop VPN connection
EipCommand.stopVPN(context);

// Start blocking VPN (blocks all traffic without establishing full VPN)
EipCommand.startBlockingVPN(context);

// Check if VPN certificate is valid
EipCommand.checkVpnCertificate(context);

// Launch a specific VPN profile
import de.blinkt.openvpn.VpnProfile;
VpnProfile profile = gatewaysManager.selectVpnProfile(0);
EipCommand.launchVPNProfile(context, profile, 0);
```

--------------------------------

### Handle VPN Start/Stop Events

Source: https://context7.com/leap/bitmask_android/llms.txt

Register a BroadcastReceiver with LocalBroadcastManager to listen for EIP (VPN) events, such as start initiation success or failure, and VPN stop notifications.

```java
import androidx.localbroadcastmanager.content.LocalBroadcastManager;
import android.content.BroadcastReceiver;
import android.content.IntentFilter;
import se.leap.bitmaskclient.base.models.Constants;
import android.content.Context;
import android.content.Intent;
import android.app.Activity;

// EIP (VPN) events
BroadcastReceiver eipReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();
        int resultCode = intent.getIntExtra(Constants.BROADCAST_RESULT_CODE, Activity.RESULT_CANCELED);

        if (Constants.EIP_ACTION_START.equals(action)) {
            if (resultCode == Activity.RESULT_OK) {
                // VPN start initiated successfully
            } else {
                String errors = intent.getStringExtra("errors");
                // Handle start failure
            }
        } else if (Constants.EIP_ACTION_STOP.equals(action)) {
            // VPN stopped
        }
    }
};

IntentFilter eipFilter = new IntentFilter(Constants.BROADCAST_EIP_EVENT);
LocalBroadcastManager.getInstance(context).registerReceiver(eipReceiver, eipFilter);
```

--------------------------------

### Listen for OpenVPN Traffic Statistics

Source: https://context7.com/leap/bitmask_android/llms.txt

Implement ByteCountListener to get real-time traffic statistics, including total bytes received/sent and bytes transferred since the last update. Ensure formatBytes is defined elsewhere to display data correctly.

```java
import de.blinkt.openvpn.core.VpnStatus;
import de.blinkt.openvpn.core.VpnStatus.ByteCountListener;

// Listen for traffic statistics
ByteCountListener byteListener = (in, out, diffIn, diffOut) -> {
    // in/out: total bytes received/sent
    // diffIn/diffOut: bytes since last update
    String downloaded = formatBytes(in);
    String uploaded = formatBytes(out);
};
VpnStatus.addByteCountListener(byteListener);
```

--------------------------------

### Get Current OpenVPN Status

Source: https://context7.com/leap/bitmask_android/llms.txt

Retrieve the current VPN connection status using utility methods like isVPNActive(), getLastConnectedVPNProfileId(), and getLastConnectedVpnName().

```java
import de.blinkt.openvpn.core.VpnStatus;

// Get current VPN status
boolean isActive = VpnStatus.isVPNActive();
String lastProfile = VpnStatus.getLastConnectedVPNProfileId();
String vpnName = VpnStatus.getLastConnectedVpnName();
```

--------------------------------

### EIP Service Actions

Source: https://context7.com/leap/bitmask_android/llms.txt

Constants for internal EIP (Encrypted IP) service actions, used for starting, stopping, and managing VPN blocking.

```java
// EIP Service actions (internal use)
String EIP_ACTION_START = "se.leap.bitmaskclient.EIP.START";
String EIP_ACTION_STOP = "se.leap.bitmaskclient.EIP.STOP";
String EIP_ACTION_START_BLOCKING_VPN = "se.leap.bitmaskclient.EIP_ACTION_START_BLOCKING_VPN";
String EIP_ACTION_STOP_BLOCKING_VPN = "se.leap.bitmaskclient.EIP_ACTION_STOP_BLOCKING_VPN";
```

--------------------------------

### Handle Provider API Events

Source: https://context7.com/leap/bitmask_android/llms.txt

Use a BroadcastReceiver with LocalBroadcastManager to monitor Provider API events, including setup completion, errors, and successful downloads of VPN certificates or GeoIP data.

```java
import androidx.localbroadcastmanager.content.LocalBroadcastManager;
import android.content.BroadcastReceiver;
import android.content.IntentFilter;
import se.leap.bitmaskclient.base.models.Constants;
import android.content.Context;
import android.content.Intent;
import android.app.Activity;
// Assuming ProviderAPI class is accessible
// import se.leap.bitmaskclient.provider.ProviderAPI;

// Provider API events
BroadcastReceiver providerReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        int resultCode = intent.getIntExtra(Constants.BROADCAST_RESULT_CODE, -1);

        switch (resultCode) {
            case ProviderAPI.PROVIDER_OK:
                // Provider setup complete
                break;
            case ProviderAPI.PROVIDER_NOK:
                String error = intent.getStringExtra(ProviderAPI.ERRORS);
                // Provider setup failed
                break;
            case ProviderAPI.CORRECTLY_DOWNLOADED_VPN_CERTIFICATE:
                // Certificate downloaded
                break;
            case ProviderAPI.CORRECTLY_DOWNLOADED_GEOIP_JSON:
                // GeoIP data updated
                break;
        }
    }
};

IntentFilter providerFilter = new IntentFilter(Constants.BROADCAST_PROVIDER_API_EVENT);
LocalBroadcastManager.getInstance(context).registerReceiver(providerReceiver, providerFilter);
```

--------------------------------

### Get Sorted Gateway Locations and Load Information

Source: https://context7.com/leap/bitmask_android/llms.txt

Retrieve gateway locations sorted by load, specifying the transport type. Obtain specific load details for a given location and transport type. The load can be UNKNOWN, GOOD, AVERAGE, or CRITICAL.

```java
import de.blinkt.openvpn.core.connection.Connection.TransportType;
import java.util.List;

// Get sorted locations with load information
List<Location> sortedLocations = gatewaysManager.getSortedGatewayLocations(TransportType.OPENVPN);

// Get location by name
Location amsterdam = gatewaysManager.getLocation("Amsterdam");

// Get load for a location
GatewaysManager.Load load = gatewaysManager.getLoadForLocation("Amsterdam", TransportType.OPENVPN);
// Load values: UNKNOWN, GOOD, AVERAGE, CRITICAL
```

--------------------------------

### Launch Emulator with System Libraries

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

Use the -use-system-libs flag when launching an emulator to ensure it utilizes the correct, modern GL libraries.

```shell
emulator -use-system-libs -avd Nexus_5_API_25
```

--------------------------------

### Set Preferred City and Auto-Start Settings

Source: https://context7.com/leap/bitmask_android/llms.txt

Set a preferred city for gateway selection and retrieve it. Configure whether the VPN should automatically restart on device boot.

```java
// Set preferred city for gateway selection
PreferenceHelper.setPreferredCity("Amsterdam");
String city = PreferenceHelper.getPreferredCity();

// Auto-start settings
PreferenceHelper.restartOnBoot(true);        // Start VPN on device boot
boolean restartOnBoot = PreferenceHelper.getRestartOnBoot();
```

--------------------------------

### Build and Sign Release APKs and AABs

Source: https://github.com/leap/bitmask_android/blob/master/README.md

This script prepares, builds, and signs release APKs and AAB bundles. You must provide the path to your keystore file and its alias. Use the -h flag for more options.

```bash
./scripts/prepareForDistribution.sh build sign -ks ~/path/to/bitmask-android.keystore -ka <yourKeystoreKeyAlias>
```

--------------------------------

### Quick Settings Tile Functionality

Source: https://context7.com/leap/bitmask_android/llms.txt

Notes on the automatic handling of tile interactions and state updates by the `BitmaskTileService`. The tile's appearance reflects the VPN connection status (CONNECTED, CONNECTING, DISCONNECTED, BLOCKING).

```java
// The tile service automatically handles:
// - Tap: Toggle VPN on/off
// - Long press: Open app settings
// - Updates tile state based on EipStatus changes

// Tile states reflect EipStatus:
// - CONNECTED: Tile shows active state with connected icon
// - CONNECTING: Tile shows updating state
// - DISCONNECTED: Tile shows inactive state
// - BLOCKING: Tile shows active state (traffic blocked)
```

--------------------------------

### Get OpenVPN UI Status Message

Source: https://context7.com/leap/bitmask_android/llms.txt

Obtain the last clean log message suitable for display in the UI using VpnStatus.getLastCleanLogMessage(context).

```java
import de.blinkt.openvpn.core.VpnStatus;

// Get clean status message for UI
String statusMessage = VpnStatus.getLastCleanLogMessage(context);
```

--------------------------------

### Run Unit Tests

Source: https://github.com/leap/bitmask_android/blob/master/README.md

Execute all unit tests from the command line using this Gradle command. It's recommended to run tests against release builds as some tests may fail in debug builds.

```bash
./gradlew testCustomProductionFatReleaseUnitTest testNormalProductionFatReleaseUnitTest
```

--------------------------------

### Quick Settings Tile Preferences Intent

Source: https://context7.com/leap/bitmask_android/llms.txt

Intent used to open the preferences for the Quick Settings tile. This is handled by `StartActivity`.

```java
// Quick Settings tile preferences
Intent tilePrefsIntent = new Intent("android.service.quicksettings.action.QS_TILE_PREFERENCES");
// Handled by StartActivity
```

--------------------------------

### Initialize and Update Git Submodules

Source: https://github.com/leap/bitmask_android/blob/master/README.md

Run these commands to initialize and update all git submodules required for building Bitmask Android. Ensure you are in the project's root directory.

```bash
cd <path/to/bitmask_android>
git submodule init
git submodule update --init --recursive
```

--------------------------------

### Get Location Name from IP Address

Source: https://context7.com/leap/bitmask_android/llms.txt

Determine the location name associated with a given IP address. This is useful for displaying the connected state in the UI.

```java
// Get location name for IP (useful for connected state display)
String locationName = gatewaysManager.getLocationNameForIP("198.252.153.70", context);
```

--------------------------------

### Launch Android Studio from Bash Shell

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

To use the desktop launcher for Android Studio after applying fixes, you must launch Android Studio from a bash shell using the 'studio' command.

```shell
studio
```

--------------------------------

### Assemble Debug APKs

Source: https://github.com/leap/bitmask_android/blob/master/README.md

After building dependencies, use this Gradle command to assemble debug packages for local running or CI testing. The resulting APKs will be located in the specified output directory.

```bash
./gradlew assembleNormalProductionFatDebug
```

--------------------------------

### Clean Project and Build Dependencies

Source: https://github.com/leap/bitmask_android/blob/master/README.md

Execute these scripts to perform a clean build of the project and compile all necessary dependencies. The `cleanProject.sh` script fetches submodules, and `build_deps.sh` creates required libraries.

```bash
./scripts/cleanProject.sh
```

```bash
./scripts/build_deps.sh
```

--------------------------------

### Build Custom Production Fat Debug App

Source: https://github.com/leap/bitmask_android/blob/master/app/src/custom/README.md

Run this command to build a debug version of your custom branded app. Ensure submodules and dependencies are built beforehand.

```bash
./gradlew assembleCustomProductionFatDebug
```

--------------------------------

### Handle Invite Code Deep Link

Source: https://context7.com/leap/bitmask_android/llms.txt

Use this intent to handle invite code URLs with the `obfsvpnintro` scheme. This is typically handled by `SetupActivity`.

```java
// Invite code deep link (handled by SetupActivity)
// URL format: obfsvpnintro://domain.com/invite?code=XXXX
Intent inviteIntent = new Intent(Intent.ACTION_VIEW);
inviteIntent.setData(Uri.parse("obfsvpnintro://vpn.example.com/invite?code=ABC123"));
startActivity(inviteIntent);
```

--------------------------------

### Initialize and Use GatewaysManager

Source: https://context7.com/leap/bitmask_android/llms.txt

Instantiate GatewaysManager to manage VPN gateways. Load gateways automatically upon creation. Use selectVpnProfile to choose a gateway by index or city, and getGatewayLocations to retrieve available locations.

```java
import se.leap.bitmaskclient.eip.GatewaysManager;
import se.leap.bitmaskclient.base.models.Location;
import de.blinkt.openvpn.VpnProfile;
import java.util.List;

// Create manager (automatically loads current provider's gateways)
GatewaysManager gatewaysManager = new GatewaysManager(context);

// Select VPN profile (0 = nearest gateway)
VpnProfile profile = gatewaysManager.selectVpnProfile(0);

// Select profile for specific city
VpnProfile cityProfile = gatewaysManager.selectVpnProfile(0, "Amsterdam");

// Get all available locations
List<Location> locations = gatewaysManager.getGatewayLocations();
```

--------------------------------

### Deploy to Google Play

Source: https://github.com/leap/bitmask_android/blob/master/fastlane/README.md

Deploy a new version of your Android application to the Google Play Store using the 'deploy' action.

```sh
[bundle exec] fastlane android deploy
```

--------------------------------

### Initialize and Use PreferenceHelper

Source: https://context7.com/leap/bitmask_android/llms.txt

Initialize PreferenceHelper once in your Application class. Use it to manage application preferences, including provider data, VPN settings, and user preferences via encrypted SharedPreferences.

```java
import se.leap.bitmaskclient.base.utils.PreferenceHelper;
import se.leap.bitmaskclient.base.models.Provider;
import java.util.Set;

// Initialize (call once in Application.onCreate())
new PreferenceHelper(context);

// Get saved provider
Provider provider = PreferenceHelper.getSavedProviderFromSharedPreferences();

// Save provider
PreferenceHelper.storeProviderInPreferences(provider);
```

--------------------------------

### Create and Configure LEAP VPN Provider

Source: https://context7.com/leap/bitmask_android/llms.txt

Instantiate and configure a LEAP VPN Provider. Supports creation from a URL, custom domains, and defining API details via JSON. Certificates and private keys can be set for secure communication.

```java
import se.leap.bitmaskclient.base.models.Provider;
import org.json.JSONObject;

// Create provider from URL
Provider provider = new Provider("https://riseup.net");

// Create provider with custom domain and main URL
Provider customProvider = Provider.createCustomProvider(
    "https://vpn.example.com",
    "example.com",
    null  // Optional Introducer for invite codes
);

// Configure provider with definition JSON
JSONObject definition = new JSONObject();
definition.put("api_uri", "https://api.example.com");
definition.put("api_version", "5");
definition.put("domain", "example.com");
provider.define(definition);

// Set certificates and keys
provider.setCaCert(caCertificatePem);
provider.setVpnCertificate(vpnCertificatePem);
provider.setPrivateKeyString(privateKeyPem);

// Check provider capabilities
boolean hasAnonymous = provider.allowsAnonymous();
boolean hasRegistration = provider.allowsRegistered();
boolean supportsPT = provider.supportsPluggableTransports();
boolean supportsObfs4 = provider.supportsObfs4();
boolean supportsObfs4Kcp = provider.supportsObfs4Kcp();

// Check if provider is fully configured
boolean ready = provider.isConfigured();

// Get provider info
String name = provider.getName();           // Localized name
String domain = provider.getDomain();       // e.g., "riseup.net"
String apiUrl = provider.getApiUrlWithVersion(); // e.g., "https://api.riseup.net/5"

// Check if updates are needed
boolean needsEipUpdate = provider.shouldUpdateEipServiceJson();
boolean needsGeoIpUpdate = provider.shouldUpdateGeoIpJson();
boolean needsCertUpdate = provider.shouldUpdateVpnCertificate();
```

--------------------------------

### Check Gateway Availability and Count

Source: https://context7.com/leap/bitmask_android/llms.txt

Check if OpenVPN gateways are available, if the manager is empty, and the total number of gateways. Retrieve a list of all gateway hostnames and the IP address for a specific host.

```java
// Check gateway availability
boolean hasOpenVPN = gatewaysManager.hasLocationsForOpenVPN();
boolean isEmpty = gatewaysManager.isEmpty();
int gatewayCount = gatewaysManager.size();

// Get all gateway hosts
List<String> hosts = gatewaysManager.getHosts();

// Get IP for specific gateway
String ip = gatewaysManager.getIpForHost("gateway1.riseup.net");
```

--------------------------------

### Run Emulator from its Directory

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

This workaround involves manually navigating to the emulator's directory before execution. It is less robust than the bash function fix.

```shell
cd "$(dirname "$(which emulator)")"
emulator <name_of_your_emulator>
```

--------------------------------

### Configure Donation Settings in build.gradle

Source: https://github.com/leap/bitmask_android/blob/master/app/src/custom/README.md

Set the donation URL, enable/disable donations, and configure donation reminder frequency within the app's build.gradle file.

```gradle
      buildConfigField 'String', 'donation_url', '"https://riseup.net/vpn/donate"'
      buildConfigField 'boolean', 'enable_donation', 'true'
      buildConfigField 'boolean', 'enable_donation_reminder', 'true'
      buildConfigField 'int', 'donation_reminder_duration', '7'
```

--------------------------------

### Quick Settings Tile Service Declaration

Source: https://context7.com/leap/bitmask_android/llms.txt

XML declaration for the `BitmaskTileService` in `AndroidManifest.xml`. It defines the service, its icon, label, permissions, and intent filters for Quick Settings tiles.

```xml
<!-- AndroidManifest.xml service declaration -->
<service
    android:name=".base.BitmaskTileService"
    android:icon="@drawable/vpn_disconnected"
    android:label="@string/qs_title"
    android:permission="android.permission.BIND_QUICK_SETTINGS_TILE"
    android:exported="true">
    <intent-filter>
        <action android:name="android.service.quicksettings.action.QS_TILE" />
    </intent-filter>
    <meta-data
        android:name="android.service.quicksettings.ACTIVE_TILE"
        android:value="false" />
</service>
```

--------------------------------

### Configure VPN Connection Settings

Source: https://context7.com/leap/bitmask_android/llms.txt

Control VPN connection behaviors such as enabling pluggable transports (bridges), using Snowflake for discovery, and preferring UDP over TCP. Retrieve the current settings for these options.

```java
// VPN connection settings
PreferenceHelper.useBridges(true);           // Enable pluggable transports
boolean useBridges = PreferenceHelper.getUseBridges();

PreferenceHelper.useSnowflake(true);         // Enable Snowflake for discovery
boolean useSnowflake = PreferenceHelper.getUseSnowflake();

PreferenceHelper.preferUDP(true);            // Prefer UDP over TCP
boolean preferUDP = PreferenceHelper.getPreferUDP();
```

--------------------------------

### EipCommand - VPN Control API

Source: https://context7.com/leap/bitmask_android/llms.txt

Provides static methods to control the VPN connection lifecycle by sending commands to the EIP service.

```APIDOC
## EipCommand - VPN Control API

### Description
Provides static methods to control the VPN connection lifecycle. It sends commands to the EIP (Encrypted Internet Proxy) service that manages OpenVPN connections and traffic blocking.

### Methods

#### Start VPN Connection

- **`startVPN(Context context, boolean earlyRoutes)`**: Starts the VPN connection. If `earlyRoutes` is true, it blocks traffic until the VPN is established.
- **`startVPN(Context context, boolean earlyRoutes, int gatewayIndex)`**: Starts the VPN connection with a specific gateway index. `0` typically refers to the nearest gateway.

### Stop VPN Connection

- **`stopVPN(Context context)`**: Stops the current VPN connection.

### Traffic Blocking

- **`startBlockingVPN(Context context)`**: Starts blocking all traffic without establishing a full VPN connection. This is useful for enforcing network policies.

### Certificate Validation

- **`checkVpnCertificate(Context context)`**: Checks the validity of the VPN certificate.

### Launch VPN Profile

- **`launchVPNProfile(Context context, VpnProfile profile, int gatewayIndex)`**: Launches a specific VPN profile. Requires a `VpnProfile` object and a gateway index.

### Request Example (Java)
```java
import se.leap.bitmaskclient.eip.EipCommand;
import android.content.Context;
import de.blinkt.openvpn.VpnProfile;

// Example usage:
Context context = getApplicationContext();

// Start VPN with early routes
EipCommand.startVPN(context, true);

// Start VPN without early routes and specify gateway index
EipCommand.startVPN(context, false, 0);

// Stop VPN
EipCommand.stopVPN(context);

// Start traffic blocking
EipCommand.startBlockingVPN(context);

// Check certificate
EipCommand.checkVpnCertificate(context);

// Launch a specific profile (assuming gatewaysManager and profile are obtained elsewhere)
// VpnProfile profile = gatewaysManager.selectVpnProfile(0);
// EipCommand.launchVPNProfile(context, profile, 0);
```
```

--------------------------------

### Monitor VPN Connection Status with EipStatus

Source: https://context7.com/leap/bitmask_android/llms.txt

The EipStatus singleton provides real-time VPN connection status. Observe changes using PropertyChangeListener to update the UI. It tracks OpenVPN and traffic blocking states, offering detailed status information.

```java
import se.leap.bitmaskclient.eip.EipStatus;
import se.leap.bitmaskclient.eip.EipStatus.EipLevel;
import java.beans.PropertyChangeListener;

// Get singleton instance
EipStatus eipStatus = EipStatus.getInstance();

// Check connection states
boolean isConnected = eipStatus.isConnected();      // VPN fully established
boolean isConnecting = eipStatus.isConnecting();    // VPN establishing
boolean isDisconnected = eipStatus.isDisconnected(); // No VPN active
boolean isDisconnecting = eipStatus.isDisconnecting(); // VPN shutting down
boolean isBlocking = eipStatus.isBlocking();        // Traffic blocking active

// Get detailed EIP level
EipLevel level = eipStatus.getEipLevel();
// Possible values: CONNECTING, DISCONNECTING, CONNECTED, DISCONNECTED, BLOCKING, UNKNOWN

// Get raw state and log message
String state = eipStatus.getState();        // e.g., "CONNECTED", "RECONNECTING"
String logMsg = eipStatus.getLogMessage();  // Detailed status message

// Listen for status changes
PropertyChangeListener listener = evt -> {
    EipStatus status = (EipStatus) evt.getNewValue();
    if (status.isConnected()) {
        // Update UI for connected state
    }
};
eipStatus.addObserver(listener);

// Remove listener when done
eipStatus.deleteObserver(listener);
```

--------------------------------

### Initialize fastlane supply with API token

Source: https://github.com/leap/bitmask_android/blob/master/src/README.md

Initialize fastlane supply for a specific project and package name using your Google Play Developer API JSON details.

```bash
fastlane supply init -j <YOUR-API-DETAILS.json> -p se.leap.<PROJECTNAME> -m src/customProductionFat/fastlane/metadata/
```

--------------------------------

### Update Submodules with Git

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

Manually update the ics-openvpn submodule using Git by adding the upstream remote and pulling changes. Resolve conflicts according to project guidelines.

```shell
cd <path/to/bitmask_android>
cd ics-openvpn
git remote add upstream https://github.com/schwabe/ics-openvpn.git
git pull --rebase upstream master
```

--------------------------------

### Configure Obfuscation Pinning and Port Hopping

Source: https://context7.com/leap/bitmask_android/llms.txt

Enable and configure obfuscation pinning for debugging specific bridges by setting IP, port, and certificate. Enable port hopping for censorship circumvention.

```java
// Obfuscation pinning (for debugging/testing specific bridges)
PreferenceHelper.setUseObfuscationPinning(true);
PreferenceHelper.setObfuscationPinningIP("192.168.1.100");
PreferenceHelper.setObfuscationPinningPort("443");
PreferenceHelper.setObfuscationPinningCert("obfs4-certificate-string");

// Port hopping for censorship circumvention
PreferenceHelper.setUsePortHopping(true);
boolean usePortHopping = PreferenceHelper.getUsePortHopping();
```

--------------------------------

### EipStatus - VPN Connection Status

Source: https://context7.com/leap/bitmask_android/llms.txt

The EipStatus singleton provides real-time VPN connection status and supports property change observers for UI updates.

```APIDOC
## EipStatus - VPN Connection Status

### Description
The `EipStatus` singleton provides real-time VPN connection status and supports property change observers for UI updates. It tracks both OpenVPN connection states and traffic blocking VPN states.

### Methods

#### Get Singleton Instance

- **`getInstance()`**: Returns the singleton instance of `EipStatus`.

#### Connection State Checks

- **`isConnected()`**: Returns `true` if the VPN is fully established.
- **`isConnecting()`**: Returns `true` if the VPN is currently establishing.
- **`isDisconnected()`**: Returns `true` if no VPN is active.
- **`isDisconnecting()`**: Returns `true` if the VPN is shutting down.
- **`isBlocking()`**: Returns `true` if traffic blocking is active.

#### Detailed Status

- **`getEipLevel()`**: Returns the detailed EIP connection level. Possible values include `CONNECTING`, `DISCONNECTING`, `CONNECTED`, `DISCONNECTED`, `BLOCKING`, `UNKNOWN`.
- **`getState()`**: Returns the raw state string (e.g., "CONNECTED", "RECONNECTING").
- **`getLogMessage()`**: Returns a detailed status message providing more context.

#### Observers

- **`addObserver(PropertyChangeListener listener)`**: Adds a listener to observe status changes. The listener will receive updates when the VPN status changes.
- **`deleteObserver(PropertyChangeListener listener)`**: Removes a previously added listener.

### Request Example (Java)
```java
import se.leap.bitmaskclient.eip.EipStatus;
import se.leap.bitmaskclient.eip.EipStatus.EipLevel;
import java.beans.PropertyChangeListener;

// Get the singleton instance
EipStatus eipStatus = EipStatus.getInstance();

// Check connection states
boolean isConnected = eipStatus.isConnected();
boolean isBlocking = eipStatus.isBlocking();

// Get detailed EIP level
EipLevel level = eipStatus.getEipLevel();

// Get raw state and log message
String state = eipStatus.getState();
String logMsg = eipStatus.getLogMessage();

// Add a listener for status changes
PropertyChangeListener listener = evt -> {
    EipStatus status = (EipStatus) evt.getNewValue();
    if (status.isConnected()) {
        System.out.println("VPN is connected!");
        // Update UI for connected state
    } else if (status.isDisconnected()) {
        System.out.println("VPN is disconnected.");
        // Update UI for disconnected state
    }
};
eipStatus.addObserver(listener);

// Remember to remove the listener when it's no longer needed
// eipStatus.deleteObserver(listener);
```
```

--------------------------------

### Update Submodules with Gradle

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

Refresh the upstream dependency on ics-openvpn by running the updateIcsOpenVpn Gradle task.

```shell
cd <path/to/bitmask_android>
./gradlew updateIcsOpenVpn
```

--------------------------------

### Configure Always-On VPN Profile

Source: https://context7.com/leap/bitmask_android/llms.txt

Intent to trigger the configuration of the always-on VPN profile. This action is defined in `Constants.APP_ACTION_CONFIGURE_ALWAYS_ON_PROFILE`.

```java
// Configure always-on VPN profile
Intent configIntent = new Intent(context, StartActivity.class);
configIntent.setAction(Constants.APP_ACTION_CONFIGURE_ALWAYS_ON_PROFILE);
startActivity(configIntent);
```

--------------------------------

### Log OpenVPN Messages

Source: https://context7.com/leap/bitmask_android/llms.txt

Use VpnStatus.logInfo(), VpnStatus.logWarning(), and VpnStatus.logError() for structured logging of VPN-related events. Remember to clear the log with VpnStatus.clearLog() when appropriate.

```java
import de.blinkt.openvpn.core.VpnStatus;

// Log messages
VpnStatus.logInfo("VPN connection started");
VpnStatus.logWarning("Connection attempt failed, retrying...");
VpnStatus.logError("Fatal error occurred");

// Clear log
VpnStatus.clearLog();
```

--------------------------------

### Listen for OpenVPN State Changes

Source: https://context7.com/leap/bitmask_android/llms.txt

Register a StateListener to receive updates on VPN connection states like CONNECTED, CONNECTING, and DISCONNECTED. The ConnectionStatus enum provides more detailed state information.

```java
import de.blinkt.openvpn.core.VpnStatus;
import de.blinkt.openvpn.core.VpnStatus.StateListener;
import de.blinkt.openvpn.core.VpnStatus.ByteCountListener;
import de.blinkt.openvpn.core.ConnectionStatus;

// Listen for state changes
StateListener stateListener = new StateListener() {
    @Override
    public void updateState(String state, String logmessage, int localizedResId, ConnectionStatus level) {
        // state: "CONNECTED", "CONNECTING", "RECONNECTING", "DISCONNECTED", etc.
        // level: ConnectionStatus enum for detailed state
        switch (level) {
            case LEVEL_CONNECTED:
                // VPN connected
                break;
            case LEVEL_CONNECTING_NO_SERVER_REPLY_YET:
            case LEVEL_CONNECTING_SERVER_REPLIED:
                // VPN connecting
                break;
            case LEVEL_NOTCONNECTED:
                // VPN disconnected
                break;
            case LEVEL_BLOCKING:
                // Traffic blocking active
                break;
        }
    }

    @Override
    public void setConnectedVPN(String uuid) {
        // Called when VPN profile connects
    }
};
VpnStatus.addStateListener(stateListener);
```

--------------------------------

### Clone l10n repository

Source: https://github.com/leap/bitmask_android/blob/master/src/README.md

Clone the l10n repository to access translated metadata. Use the appropriate branch for your build flavor.

```bash
git clone -b bitmask-playstore https://0xacab.org/leap/l10n.git (the other branches for custom builds)
```

--------------------------------

### Manage Excluded Apps and Tethering Settings

Source: https://context7.com/leap/bitmask_android/llms.txt

Specify which applications should be excluded from the VPN tunnel. Configure settings to allow or disallow Wi-Fi, USB, and Bluetooth tethering through the VPN.

```java
// Exclude apps from VPN
Set<String> excludedApps = Set.of("com.example.app1", "com.example.app2");
PreferenceHelper.setExcludedApps(excludedApps);
Set<String> apps = PreferenceHelper.getExcludedApps();

// Tethering settings
PreferenceHelper.allowWifiTethering(true);
PreferenceHelper.allowUsbTethering(true);
PreferenceHelper.allowBluetoothTethering(true);
```

--------------------------------

### Pull translations using script

Source: https://github.com/leap/bitmask_android/blob/master/src/README.md

Use the provided script to pull store metadata translations from the l10n git repository for the main or a custom flavor.

```bash
scripts/pullTranslations.py main (or custom flavor)
```

--------------------------------

### Build Android APKs for Screengrab

Source: https://github.com/leap/bitmask_android/blob/master/fastlane/README.md

Build debug and test APKs specifically for use with screengrab. This action is available for both bitmask and custom build configurations.

```sh
[bundle exec] fastlane android build_bitmask_for_screengrab
```

```sh
[bundle exec] fastlane android build_custom_for_screengrab
```

--------------------------------

### Set Environment Variable for System Libraries

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

Export the ANDROID_EMULATOR_USE_SYSTEM_LIBS variable to 1 in your ~/.bashrc or ~/.bash_profile to have the emulator automatically use system libraries.

```shell
export ANDROID_EMULATOR_USE_SYSTEM_LIBS=1
```

--------------------------------

### Run Android Tests with Fastlane

Source: https://github.com/leap/bitmask_android/blob/master/fastlane/README.md

Execute all automated tests for your Android project using the 'test' action in Fastlane.

```sh
[bundle exec] fastlane android test
```

--------------------------------

### Submit Beta Build to Crashlytics

Source: https://github.com/leap/bitmask_android/blob/master/fastlane/README.md

Submit a new Beta Build to Crashlytics Beta using the 'beta' action for Android.

```sh
[bundle exec] fastlane android beta
```

--------------------------------

### Run Bitmask Android NDK Docker Container

Source: https://github.com/leap/bitmask_android/blob/master/README.md

Runs an interactive Docker container with the Bitmask Android NDK environment. Use the volume mount option to access your local source code.

```shell
cd <path/to/bitmask_android>
docker run --rm -it -v`pwd`:/bitmask_android -t registry.0xacab.org/leap/bitmask_android/android-ndk:latest
```

--------------------------------

### Build Dependencies with Tor Disabled

Source: https://github.com/leap/bitmask_android/blob/master/README.md

To build dependencies while temporarily disabling the compilation of Tor, set the BUILD_TOR environment variable to 'false' before running the build script.

```bash
BUILD_TOR=false ./scripts/build_deps.sh
```

--------------------------------

### Generate Google Play Developer API Token

Source: https://github.com/leap/bitmask_android/blob/master/src/README.md

Instructions for generating a JSON web token for the Google Play Developer API, requiring a Google Cloud Platform account, service account creation, and permission grants.

```markdown
https://medium.com/@Codeible/generating-the-json-web-token-for-the-google-play-developer-api-f6be6439b1af
https://developers.google.com/android-publisher/authorization
```

--------------------------------

### Generate Screenshots with Fastlane

Source: https://github.com/leap/bitmask_android/blob/master/fastlane/README.md

Triggers the process for generating screenshots on Android. Separate actions exist for bitmask and custom build configurations.

```sh
[bundle exec] fastlane android bitmask_screenshots
```

```sh
[bundle exec] fastlane android custom_build_screenshots
```

--------------------------------

### Fix Emulator Filepath Bug with Bash Function

Source: https://github.com/leap/bitmask_android/blob/master/docs/Troubleshooting.md

Insert this function into your ~/.bashrc to automatically navigate to the correct directory when invoking the emulator, resolving relative filepath issues.

```shell
function emulator { pushd `pwd`; cd "$(dirname "$(which emulator)")" && ./emulator "$@"; popd;}
```