Class MicroVPNSDK

java.lang.Object
    com.citrix.mvpn.api.MicroVPNSDK

public class MicroVPNSDK
extends java.lang.Object
<!--NeedCopy-->

Field summary

Fields

Method summary

All methods

Method detail

initialize

public static void initialize(android.content.Context context)
<!--NeedCopy-->

This method initializes the SDK. A call to this method from the app is optional. The app doesn’t need to call this method explicitly because the startTunnel call initializes the micro VPN library internally.

Parameters

context - Application context.

startTunnel

public static void startTunnel(android.app.Activity activity, android.os.Messenger messenger)
<!--NeedCopy-->

This method must be called to start the network tunnel for apps managed using Citrix Endpoint Management. The app must invoke MicroVPNSDK.startTunnel(activity, messenger) method from an activity and pass that activity instance as an argument to this method. This method also takes a messenger object that is needed for asynchronous communication. The start tunnel results are sent back to the app using the messenger object.

Sample code:

    MicroVPNSDK.startTunnel(this, new Messenger(handler));
<!--NeedCopy-->

The messenger object must have a custom handler that overrides the Handler#handleMessage() method. When the tunnel starts successfully or fails to start, it sends a start or failure message using the input messenger object.

Error Codes (msg.what):

• 0 - Tunnel started successfully.
• 1 - Tunnel failed to start.
• 2 - Tunnel is already running.
• 3 - Session is expired. Start tunnel is required.
• 4 - App is wrapped in MDX mode.
• 5 - Network Access mode is not Tunneled - Web SSO. Tunnel can be started only in Tunneled - Web SSO mode for explicit SDK app.
• 6 - App is not managed. Unable to retrieve policies.
• 7 - No network connection.
• 8 = Invalid app configuration data.
• 9 = Invalid OAuth token.
• 10 = Application is in locked state.

    private final Handler handler = new Handler() {
        public void handleMessage(Message msg) {
            super.handleMessage(msg);
            ResponseStatusCode responseStatusCode = ResponseStatusCode.fromId(msg.what);
            switch (responseStatusCode)
            {
                case START_TUNNEL_SUCCESS:
                   Log.i(TAG, "Tunnel started successfully.");
                   networkTunnelRunning = true;
                   sessionExpired = false;
                   break;
               case START_TUNNEL_FAILED:
                   Log.e(TAG, "Failed to start tunnel.");
                   networkTunnelRunning = false;
                   break;
               case TUNNEL_ALREADY_RUNNING:
                   Log.i(TAG, "Tunnel is already running.");
                   networkTunnelRunning = true;
                   sessionExpired = false;
                   break;
               case SESSION_EXPIRED:
                   Log.i(TAG, "Session Expired.");
                   networkTunnelRunning = false;
                   sessionExpired = true;
                   break;
               case FOUND_LEGACY_MODE:
                   Log.e(TAG, "Cannot start tunnel for Legacy ManagementMode.");
                   networkTunnelRunning = false;
                   sessionExpired = false;
                   break;
               case FOUND_NON_WEBSSO_MODE:
                   Log.e(TAG, "Cannot start tunnel for NetworkAccess mode other than Tunneled - Web SSO.");
                   networkTunnelRunning = false;
                   sessionExpired = false;
                   break;
               case FOUND_NON_MANAGED_APP:
                   Log.e(TAG, "Could not retrieve policies. \n This could be because of the following reasons: \n\t 1. SecureHub is not installed.\n\t 2. SecureHub enrollment is not completed.\n\t 3. App is not managed through CEM.");
                   networkTunnelRunning = false;
                   sessionExpired = false;
                   break;
               case NO_NETWORK_CONNECTION:
                   Log.e(TAG, "Failed to start tunnel. No Network.");
                   networkTunnelRunning = false;
                   sessionExpired = false;
                   break;
               case INVALID_APP_CONFIGURATION_DATA:
                   Log.e(TAG, "Invalid App Configuration Data.");
                   appConfigDataValid = false;
                   break;
               case INVALID_OAUTH_TOKEN:
                   Log.e(TAG, "Invalid OAuth Token.");
                   oauthTokenValid = false;
                   break;
               case APP_LOCKED:
                   Log.e("Failed to start tunnel. App is in locked state.");
                   break;
               default:
                   super.handleMessage(msg);
                   break;
            }
        }
    };
<!--NeedCopy-->

Parameters

• activity - App activity that tries to start the tunnel.
• messenger - Messenger object that is used to return response message back to the app.

Throws

java.lang.IllegalArgumentException when activity or messenger is null

startTunnel

public static void startTunnel(android.content.Context context, android.os.Messenger messenger)
<!--NeedCopy-->

This method can be used to start the network tunnel when the app starts. It can be used to start the tunnel if a valid session exists. Otherwise, it fails to start the tunnel.

Parameters

• context - Context of the application that tries to start the tunnel
• messenger - Messenger object that is used to return a response message back to the app.

Throws

java.lang.IllegalArgumentException when the context or messenger is null.

createURLConnection

public static java.net.URLConnection createURLConnection(android.content.Context context, java.net.URL url) throws NetworkTunnelNotStartedException, ClientConfigurationException
<!--NeedCopy-->

This method is used to configure a URL object for tunneling through micro VPN. This method returns the modified URLConnection object that is enabled for tunneling. It throws the NetworkTunnelNotStartedException exception when called before starting the network tunnel. This method does not validate if the Citrix Gateway cookie has expired or not. So, after sending the actual network request, if it finds that the Citrix Gateway session has expired, the tunnel sends the response header X-Citrix-Session-Expired = true. You can call the utility method ResponseValidator.isNetScalerCookieExpired(response) to validate the response.

Sample code:

    try {
        URL url = new URL(strUrl[0]);
        URLConnection urlConnection = MicroVPNSDK.createURLConnection((Context)delegate, 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) {
        Log.e(LOG_TAG, e.getMessage(), e);
    } catch(MvpnException e) {
        Log.e(LOG_TAG, e.getMessage(), e);
    }
<!--NeedCopy-->

Parameters

• context - Context of the application that tries to start the tunnel.
• url - URL object that is enabled for network tunneling.

Returns

URLConnection object enabled for micro VPN tunnel.

Throws

NetworkTunnelNotStartedException when the app tries to call this method before starting the network tunnel.

ClientConfigurationException when the WebView object cannot be modified.

enableOkHttpClientObjectForNetworkTunnel

public static java.lang.Object enableOkHttpClientObjectForNetworkTunnel(android.content.Context context, java.lang.Object okHttpClient) throws NetworkTunnelNotStartedException, ClientConfigurationException         
<!--NeedCopy-->

This method is used to update an OkHttpClient object before the OkHttp network call. After the network tunnel is established successfully, the MicroVPNSDK.enableOkHttpClientObjectForNetworkTunnel(…) must be called before making the actual network request okHttpClient.newCall(request).execute(). This method returns the modified OkHttpClient object that is enabled for tunneling. If this method is called before starting the network tunnel, it throws the NetworkTunnelNotStartedException exception. This method does not validate if the Citrix Gateway cookie has expired or not. So, after sending the actual network request, if it finds that the Citrix Gateway session has expired, then the tunnel sends the response header X-Citrix-Session-Expired” = true. You can call the utility method ResponseValidator.isNetScalerCookieExpired(response) to validate the response.

Sample code:

    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) {
        Log.e(LOG_TAG, nse.getMessage(), nse);
    } catch(MvpnException e) {
        Log.e(LOG_TAG, e.getMessage(), e);
    }
<!--NeedCopy-->

Parameters

• context - Context of the application that tries to start the tunnel.
• okHttpClient - OkHttpClient object that is enabled for network tunneling.

Returns

The modified OkHttpClient object.

Throws

NetworkTunnelNotStartedException when the app tries to call this method before starting the network tunnel.

ClientConfigurationException when the WebView object cannot be modified.

enableWebViewObjectForNetworkTunnel

public static android.webkit.WebView enableWebViewObjectForNetworkTunnel(android.content.Context context, android.webkit.WebView webView) throws NetworkTunnelNotStartedException, ClientConfigurationException
<!--NeedCopy-->

This method updates WebView for tunneling through micro VPN. After the network tunnel is established successfully, the MicroVPNSDK.enableWebViewObjectForNetworkTunnel(…) method must be called before calling the webView.loadUrl(url) method. This method returns the modified WebView object that is enabled for tunneling. If this method is called before starting the network tunnel, it throws the NetworkTunnelNotStartedException exception. This method does not validate if the Citrix Gateway cookie has expired or not. So, after sending the actual network request, if it finds that the Citrix Gateway session has expired, the tunnel sends the response header X-Citrix-Session-Expired = true. You can call utility method ResponseValidator.isNetScalerCookieExpired(response) to validate the response.

Sample code:

    WebView webView = findViewById(R.id.webview);
    try {
        webView = MicroVPNSDK.enableWebViewObjectForNetworkTunnel(this, webView);
        webView.loadUrl(url);
    } catch(NetworkTunnelNotStartedException nse) {
        Log.e(LOG_TAG, nse.getMessage(), nse);
    } catch(MvpnException e) {
        Log.e(LOG_TAG, e.getMessage(), e);
    }
<!--NeedCopy-->

Parameters

• context - Context of the application that tries to start the tunnel.
• webView - WebView object that is to be enabled for network tunneling.

Returns

Modified WebView object.

Throws

NetworkTunnelNotStartedException when the app tries to call this method before starting the network tunnel.

ClientConfigurationException when the WebView object cannot be modified.

enableWebViewObjectForNetworkTunnel

public static android.webkit.WebView enableWebViewObjectForNetworkTunnel(android.content.Context context, android.webkit.WebView webView, android.webkit.WebViewClient webViewClient) throws NetworkTunnelNotStartedException, ClientConfigurationException
<!--NeedCopy-->

This method updates WebView for tunneling through the micro VPN. After the network tunnel is established successfully, the MicroVPNSDK.enableWebViewObjectForNetworkTunnel(…) needs to be called before calling webView.loadUrl(url). This method returns the modified WebView object that is enabled for tunneling. If this method is called before starting the network tunnel then it throws the NetworkTunnelNotStartedException exception. This method does not validate if the Citrix Gateway cookie has expired or not. So, after sending the actual network request, if it finds that the Citrix Gateway session has expired, the tunnel sends the response header X-Citrix-Session-Expired = true. You can call the utility method ResponseValidator.isNetScalerCookieExpired(response) to validate the response.

Sample code:

    WebView webView = findViewById(R.id.webview);
    WebViewClient webViewClient = new WebViewClient();
    try {
        webView = MicroVPNSDK.enableWebViewObjectForNetworkTunnel(this, webView, webViewClient);
        webView.loadUrl(url);
    } catch(NetworkTunnelNotStartedException nse) {
        Log.e(LOG_TAG, nse.getMessage(), nse);
    } catch(MvpnException e) {
        Log.e(LOG_TAG, e.getMessage(), e);
    }
<!--NeedCopy-->

Parameters

• context - Context of the application that tries to start the tunnel.
• WebView - WebView object that is enabled for network tunneling.
• webViewClient - WebViewClient object that is enabled for network tunneling. This can also be a custom WebView client object.

Returns

Modified WebView object.

Throws

NetworkTunnelNotStartedException when the app tries to call this method before starting network tunnel.

ClientConfigurationException when the WebView object cannot be modified.

isNetworkTunnelRunning

public static boolean isNetworkTunnelRunning(android.content.Context context)
<!--NeedCopy-->

This method checks if the network tunnel is running. It returns true if the tunnel is running and the socket is listening.

Parameters

context - Context of the application that starts the tunnel.

Returns

True if the network tunnel is running.

stopTunnel

public static boolean stopTunnel(android.content.Context context)
<!--NeedCopy-->

This method returns true if the tunnel has stopped successfully. This method must be called from the same process that starts the tunnel.

Parameters

context - Context of the application that starts the tunnel.

Returns

True if the tunnel has stopped successfully.