PermissionManager

Contents

Introduction

PermissionManager provides an Android request permission in a VR scene. It is based on Android 6.0 (API 23) of request permission at runtime. APIs are listed below to let developers check the status and grant permission when needed.

PermissionManager Class

  • void getInstance()

Get the instance of PermissionManager

  • boolean isInitialized()

Report true/false of native permission service has been initialized.

  • boolean isPermissionGranted(String permission)

Report true/false to indicate if this permission has already been granted.

  • void setActivity(Activity at)

Before using PermissionManager, the instance of activity must be passed.

  • void setPackageName(String pn)

Before using PermissionManager, the package name of activity must be passed.

  • boolean shouldGrantPermission(String permission)

Report true to notify user if the corresponding permission request is going to trigger and show a permission dialog box.

Please check these before requestPermissions, and stop your controller updating if returns true.

  • boolean showDialogOnScene()

Report true if dialog box will show on the scene.

  • void requestPermissions(String[] permissions, PermissionCallback cb)

The major function of PermissionManager class, if shouldGrantPermission returns true, the developer must call this major function to request permission. This API will check status of permission show dialog box on the scene when permission is not granted. Before developer calls this API, it is necessary to implement the interface of PermissionCallback and pass its instance to PermissionManager. onRequestCompletedwithObject which will be called after users approve or deny to all requested permissions.

Developers can restart to update the controllers after receiving the callback.

  • void requestUsbPermission(UsbPermissionCallback cb)

This is the major function of requesting permission to access a USB device. This function will detect if there is any USB device plugged in. If a USB device is detected and the access permission is not granted, a request dialog will pop up to ask for the user’s allowance or denial. Before calling the function, it is necessary to implement the interface of UsbPermissionCallback and pass its instance to PermissionManager. The callback function will be called after the user grants or denies the requested USB device access permission. Currently only one USB device is supported. If there is more than one device plugged in, only the first device’s callback will be called.

  • void onPauseAndReturnFail()

Please call this function in onPause() in the app. If requesting permissions is still in progress, PermissionManager will call the callback to return the fail results.

  • void onResume()

Please call this function in onResume() in the app to reset the status of PermissionManager.

PermissionManager will send callback with all fails to the registered app when requestPermission is processing and it’s going to pause (the native service will also be stopped.) It’s recommended that the developer checks isInitialized/isPermissionGranted/shouldGrantPermission after onResume() to see if you need requestPermissions again.

  • void release()

This function should be called to release resources when an app terminates.

PermissionCallback Interface

  • void onRequestCompletedwithObject(GrantedResult gs)

The developer must implement the callback function to receive grant result data from the permission manager.

The Attribute of GrantedResult Class

  • String[] requestPermissions

The permissions which developer request

  • String[] result

The result of permission request

UsbPermissionCallback Interface

  • void onRequestCompletedwithObject(UsbGrantedResult gs)

This is the callback function of requesting the access permission of a USB device. Developers should implement the callback to receive the request result.

The Attribute of UsbGrantedResult Class

  • UsbDevice device

The USB device plugged in

  • boolean result

The result of requesting the access permission of a USB device

How to Get Permissions

  1. Copy wvr_permission_client.aar to libs folder in project
  2. In build.gradle add reference, e.g., compile (name:’wvr_permission_client’, ext:’aar’)
  3. Add permissions in AndroidManifest.xml, e.g., <uses-permission android:name=”android.permission.READ_EXTERNAL_STORAGE” />
  4. Prepare string array of permissions (must be declared in AndroidManifest.xml)
  5. Implement callback function to get notification from PermissionManager
  6. Get PermissionManager instance in onCreate().
  7. Call Instance.setActivity(Activity at) and Instance.setPackageName(String pn) after getting instance.
  8. Call Instance.onResume() in onResume()
  9. Call Instance.requestPermissions() with callback function after Instance.onResume() done.
  10. Use gaze or controller trigger to choose Deny or Allow
  11. Get grant result from PermissionManager
  12. Call Instance.onPauseAndReturnFail() in onPause()
  13. Call Instance.release() in onDestroy()

Sample Code for Getting Permissions

import com.htc.vr.permission.client.PermissionManager;
import com.htc.vr.permission.client.PermissionCallback;
import com.htc.vr.permission.client.GrantedResult;

private PermissionManager mPM;

// Implement callback function
private PermissionCallback cb = new PermissionCallback(){
    @Override
    public void onRequestCompletedwithObject(GrantedResult gs) {
        for (int i = 0 ; i < gs.result.length; i++) {
            Log.d(TAG, "RequestPermission : " + gs.requestPermissions[i] + ". Result = " + gs.result[i]);
        }
    }
};

@Override
protected void onCreate(Bundle bundle) {
    mPM = PermissionManager.getInstance();
    if (mPM != null) {
        mPM.setActivity(this);
        mPM.setPackageName(this.getPackageName());
    }
}

@Override
protected void onResume() {
    String[] request = new String[] {
        "android.permission.READ_CALENDAR",
        "android.permission.WRITE_CALENDAR",
        "android.permission.CAMERA",
        "android.permission.READ_CONTACTS",
        "android.permission.WRITE_CONTACTS",
        "android.permission.GET_ACCOUNTS"
    };

    if (mPM != null) {
        mPM.onResume();
        if (mPM.isInitialized()) {
            mPM.requestPermissions(request, cb);
        }
    }
}

@Override
protected void onPause() {
    if (mPM != null) {
        mPM.onPauseAndReturnFail();
    }
}

@Override
protected void onDestroy() {
    if(mPM != null) {
        mPM.release();
    }
}

How to Get USB Permission

  1. Copy wvr_permission_client.aar to libs folder in the project
  2. Add the reference in build.gradle, e.g., compile (name:’wvr_permission_client’, ext:’aar’)
  3. Add the necessary declaration in AndroidManifest.xml, e.g., <uses-feature android:name=”android.hardware.usb.host” />
  4. Implement the callback function to get the request result from PermissionManager
  5. Get PermissionManager instance in onCreate().
  6. Call Instance.setActivity(Activity at) and Instance.setPackageName(String pn) after getting instance.
  7. Call Instance.onResume() in onResume()
  8. Call Instance.requestUsbPermission() with callback function after Instance.onResume() done.
  9. The user allows or denies the request by controller or by gazing
  10. Get request result from PermissionManager
  11. Call Instance.onPauseAndReturnFail() in onPause()
  12. Call Instance.release() in onDestroy()

Sample Code for Getting USB Permission

import com.htc.vr.permission.client.PermissionManager;
import com.htc.vr.permission.client.UsbPermissionCallback;
import com.htc.vr.permission.client.UsbGrantedResult;

private PermissionManager mPM;

// Implement callback function
private UsbPermissionCallback cb = new UsbPermissionCallback(){
    @Override
    public void onRequestCompletedwithObject(UsbGrantedResult gs){
        Log.d(TAG, "usb callback: device=" + gs.device + ", result="+ gs.result);
    }
};

@Override
protected void onCreate(Bundle bundle) {
    mPM = PermissionManager.getInstance();
    if (mPM != null) {
        mPM.setActivity(this);
        mPM.setPackageName(this.getPackageName());
    }
}

@Override
protected void onResume() {
    if (mPM != null) {
        mPM.onResume();
        if (mPM.isInitialized()) {
            mPM.requestUsbPermission(cb);
        }
    }
}

@Override
protected void onPause() {
    if (mPM != null) {
        mPM.onPauseAndReturnFail();
    }
}

@Override
protected void onDestroy() {
    if (mPM != null) {
        mPM.release();
    }
}

Notices

In general case, Android does not allow non-specified USB devices to be permanently bound to applications. If developers need to specify this APP as default program to read specified USB devices, developer need to add the following settings in AndroidManifest.xml. This feature is only supported by SDK 5.2.0 or above

  • AndroidManifest.xml
<activity>
    <intent-filter>
        <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
    </intent-filter>
    <meta-data android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
        android:resource="@xml/device_filter" />
</activity>
  • device_filter.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <usb-device vendor-id="1234" product-id="5678" />
</resources>