Skip to content

Using the SDK

Using SDK

Starting Tunnel

Note

App needs to start tunnel before making any other calls to mVPNSDK.

MicroVPNSDK.startTunnel(…) method is used to start tunnel. This method starts Micro VPN network tunnel asynchronously. App invokes #startTunnel(...) method from an activity (for example, onCreate() method of an activity) and pass that activity instance as an argument to this method. This method also takes a messenger object that is needed for async communication. #startTunnel(…) throws NetworkTunnelAlreadyRunningException when there is already a network tunnel is running. TunnelConfigException is thrown when network tunnel configuration couldn't be retrieved from the Provider for any reason. All other exceptions can be caught through MvpnException.

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    try {
        MicroVPNSDK.startTunnel(this, new Messenger(handler));
    } catch (NetworkTunnelAlreadyRunningException e) {
        MvpnLogger.getLogger().error(LOG_TAG, "Network Tunnel is already running.");
    } catch (TunnelConfigException te) {
        MvpnLogger.getLogger().error(LOG_TAG, "Exception occurred while getting tunnel configuration");
    } catch (MvpnException e) {
        MvpnLogger.getLogger().error(LOG_TAG, "Micro VPN exception occurred:" + e.getMessage());
    }
}

Messenger object should have a custom Handler that overrides Handler#handleMessage() method. When the tunnel starts successfully or fails to start, it sends start or failure Message using the input messenger object. Also, when NetScaler cookie expires, a Cookie expiry message is sent using this Messenger. If the value of msg.what is “0” (zero) then tunnel established successfully. Supported Codes (msg.what) are described in the following section:

Sample code for reference:

private final Handler handler = new Handler() {
public void handleMessage(Message msg) {
    super.handleMessage(msg);
    switch (msg.what) {
    case 0:
        MvpnLogger.getLogger().info(LOG_TAG, "Tunnel Started. Send requests now.");
        break;
    case 1:
        MvpnLogger.getLogger().info(LOG_TAG, "Session Expired. Start Tunnel Again.");
        break;
    case 9999:
        MvpnLogger.getLogger().info(LOG_TAG, "Tunnel Failed to start.");
        break;
    default:
        break;
    }
}
};

Error Codes (msg.what) for handleMessage:

  • 0 – Network Tunnel Started Successfully
  • 1 – Cookie Expired. You can invoke MicroVPNSDK.startTunnel(…) again to start network tunnel.
  • 9999 – Network Tunnel Failed to start

Enabling Webview for Tunneling

Note

This method call must be added right before calling webview.loadUrl(url).

MicroVPNSDK.enableWebViewObjectForNetworkTunnel(...) method is used to update a webview object before loading the webview. Once the network tunnel is established successfully, then MicroVPNSDK.enableWebViewObjectForNetworkTunnel(...) needs to be called every time before calling webView.loadUrl(url). This method returns the modified webview object that is enabled for tunneling. Since #startTunnel(…) is asynchronous call, Tunnel needs to be started before calling this api, otherwise it throws NetworkTunnelNotStartedException.

Note

Do not update the WebView or WebViewClient object after the #enabledWebViewObjectForNetworkTunnel(…) call. So, calling MicroVPNSDK.enableWebViewObjectForNetworkTunnel(…) right before webview.loadUrl(url) is the recommended approach.

WebView myWebView = findViewById(R.id.webview);
try {
    myWebView.setWebViewClient(new WebViewClient());
    webView = MicroVPNSDK.enableWebViewObjectForNetworkTunnel(this, webView);
    webView.loadUrl(url);
} catch(NetworkTunnelNotStartedException nse) {
    MvpnLogger.getLogger().error(LOG_TAG, nse.getMessage());
} catch(MvpnException e) {
    MvpnLogger.getLogger().error(LOG_TAG, e.getMessage());
}

Enabling OkHttp for Tunneling

Note

This method call must be added right before calling call.execute(...)

MicroVPNSDK.enableOkHttpClientObjectForNetworkTunnel(...) method is used to update an OkHttpClient object before doing a network call. Once the network tunnel is established successfully, then MicroVPNSDK.enableOkHttpClientObjectForNetworkTunnel(...) needs to be called every time before calling okHttpClient.newCall(request).execute(). This method returns the modified OkHttpClient object that is enabled for tunneling. Since #startTunnel(…) is asynchronous call, Tunnel needs to be started before calling this api, otherwise it throws NetworkTunnelNotStartedException.

Note

Do not update the OkHttpClient object after the #enableOkHttpClientObjectForNetworkTunnel (…) call. So, calling MicroVPNSDK.enableOkHttpClientObjectForNetworkTunnel (…) right before call.execute() is the recommended approach

try {
    OkHttpClient client = new OkHttpClient.Builder().build();
    Request request = new Request.Builder().url(url).build();
    client = (OkHttpClient) MicroVPNSDK.enableOkHttpClientObjectForNetworkTunnel(context, client);
    Response response = client.newCall(request).execute();
    responseHtml = response.body().string();
} catch(NetworkTunnelNotStartedException nse) {
    MvpnLogger.getLogger().error(LOG_TAG, nse.getMessage());
} catch(Exception e) {
    MvpnLogger.getLogger().error(LOG_TAG, e.getMessage());
}

Enabling URLConnection for Tunneling

MicroVPNSDK.createURLConnection(...) method is used to configure a URL object for tunneling through MVPN tunnel. This method returns the modified URLConnection object that is enabled for tunneling. Since #startTunnel(…) is asynchronous call, Tunnel needs to be started before calling this api, otherwise it throws NetworkTunnelNotStartedException.

StringBuilder response = new StringBuilder();
try {
    URL url = new URL(strUrl[0]);
    URLConnection urlConnection = MicroVPNSDK.createURLConnection(context, url);

    HttpURLConnection conn = (HttpURLConnection) urlConnection;
    int responseCode = conn.getResponseCode();
    InputStream inputStream;
    if (200 <= responseCode && responseCode <= 299) {
        inputStream = conn.getInputStream();
    } else {
        inputStream = conn.getErrorStream();
    }
    BufferedReader in = new BufferedReader(new InputStreamReader(inputStream));
    String currentLine;
    while ((currentLine = in.readLine()) != null) {
        response.append(currentLine);
    }
    in.close();

} catch (NetworkTunnelNotStartedException e) {
    MvpnLogger.getLogger().error(LOG_TAG, e.getMessage());
} catch(Exception e) {
    MvpnLogger.getLogger().error(LOG_TAG, e.getMessage());
}

Installing Test Project

Steps:

  1. Unzip mvpntestapp.zip file under SampleCode folder and open the project in Android Studio.
  2. Build the project through IDE or using command line ./gradlew clean build.
  3. After build is successful it generates mvpntestapp.mdx file under build/outputs/apk/release/.
  4. Upload the .mdx file to XMS console as an MDX app.
  5. Install Secure Hub 19.3.5+ in your android device.
  6. Enroll to your XenMobile environment.
  7. Install MvpnTestApp from Secure Hub Store page.
  8. Side load the mvpntestapp-release.apk file to your device. You can find the apk file under build/outputs/apk/release folder.
  9. Once MvpnTestApp is installed successfully, launch the app.
  10. Click Start Tunnel button to start Micro VPN Network Tunnel. Test App 1
  11. Enter a URL and click WebView Request send load the webview using Micro VPN Tunnel
  12. Click OkHttp Request to send an OkHttp request.
  13. Click URLConnection Request to send an URLConnection request. Test App 2