com.ansca.corona.permissions

Class PermissionsServices

java.lang.Object

com.ansca.corona.ApplicationContextProvider

com.ansca.corona.permissions.PermissionsServices

public class PermissionsServices
extends ApplicationContextProvider

Provides methods and fields used to easily work with Android permissions, both in the AndroidManifest.xml, and at runtime on Android 6 and above devices.

All methods in this class are thread safe and can be called from any thread.

Added in daily build 2016.2828.

See Also:

ApplicationContextProvider

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PermissionsServices.Permission API Level independent constants for dangerous Android permissions supported by Corona, sorted by permission groups.
static class	PermissionsServices.PermissionGroup API Level independent constants for supported permission-group names.

Constructor Summary

Constructors

Constructor and Description
PermissionsServices(android.content.Context context) Creates an object that provides easy access to the application's permissions.

Method Summary

Methods

Modifier and Type	Method and Description
String[]	findAllPermissionsInManifestForGroup(String permissionGroup) Searches the AndroidManifest.xml for all permissions within the desired permission group.
String	findPermissionInManifestForGroup(String permissionGroup) Searches the AndroidManifest.xml for a permission within the desired permission group.
String	getPAAppPermissionNameFromAndroidPermission(String permission) Gets the Platform-Agnostic App Permission name for the given Android permission.
String	getPAAppPermissionNameFromPermissionGroup(String permissionGroup) Gets the Platform-Agnostic App Permission name for the given Permission Group name.
String	getPermissionGroupFromPAAppPermissionName(String pAAppPermissionName) Gets the Permission Group name for the given Platform-Agnostic App Permission name.
String	getPermissionGroupFromPermission(String permission) Gets the permission group for the desired permission.
PermissionState	getPermissionStateFor(String permission) Determines the current state of the desired permission and returns it.
PermissionState	getPermissionStateForSupportedGroup(String permissionGroup) Determines the current state of the desired permission group supported by Corona and returns it.
String[]	getRequestedPermissions() Grabs all the requested permissions in the AndroidManifest.xml.
String[]	getRequestedPermissionsInState(PermissionState permissionState) Gets all the requested permissions in the AndroidManifest.xml in the desired state.
String[]	getRequestedPermissionsInStateForGroup(PermissionState permissionState, String permissionGroup) Gets all the requested permissions in the AndroidManifest.xml in the desired state for the desired Permission Group.
String[]	getSupportedPermissionGroups() Returns a String array of all dangerous-level permissions groups supported by Corona.
boolean	isPAAppPermissionName(String name) Determines if this name corresponds to the name of a Platform-Agnostic App Permission.
boolean	isPartOfPAAppPermission(String permission) Determines if this Android permission is part of a Platform-Agnostic App Permission.
boolean	isPermissionInManifest(String permission) Determines if the desired Android permission is in the AndroidManifest.xml.
boolean	isSupportedPermissionGroupName(String name) Determines if this name corresponds to the name of a dangerous-level Android Permission Group supported by Corona.
void	requestAllDeniedPermissionsInGroup(String permissionGroup, CoronaActivity.OnRequestPermissionsResultHandler resultHandler) Requests all permissions that are currently denied in the desired permission group.
void	requestPermissions(PermissionsSettings settings, CoronaActivity.OnRequestPermissionsResultHandler resultHandler) Requests the desired permissions, gathering data about which permissions are requested.
boolean	shouldNeverAskAgain(String permission) Determines if the user has requested the desired permission never be asked for again.
void	showPermissionGroupMissingFromManifestAlert(String permissionGroup) Displays a native alert stating that the AndroidManifest.xml doesn't contain any permissions from the desired permission group.
void	showPermissionMissingFromManifestAlert(String permission, String message) Displays a native alert stating that this permission is missing from the AndroidManifest.xml.

Methods inherited from class com.ansca.corona.ApplicationContextProvider

getApplicationContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PermissionsServices

public PermissionsServices(android.content.Context context)

Creates an object that provides easy access to the application's permissions.

Parameters:

context - Reference to an Android created context used to access the input device system. Note: Setting this to null will cause an exception to be thrown.

Method Detail

findAllPermissionsInManifestForGroup

public String[] findAllPermissionsInManifestForGroup(String permissionGroup)

Searches the AndroidManifest.xml for all permissions within the desired permission group.

Parameters:

permissionGroup - The permission group we're looking for the presence of.

Returns:

Returns all permissions in the AndroidManifest.xml that match the desired permission group.

Returns null if no permission in the desired permission group is in the AndroidManifest.xml or we're in an invalid environment.

findPermissionInManifestForGroup

public String findPermissionInManifestForGroup(String permissionGroup)

Searches the AndroidManifest.xml for a permission within the desired permission group.

Parameters:

permissionGroup - The permission group we're looking for the presence of.

Returns:

Returns the first permission in the AndroidManifest.xml that matches the desired permission group.

Returns null if no permission in the desired permission group is in the AndroidManifest.xml or we're in an invalid environment.

getPermissionStateFor

public PermissionState getPermissionStateFor(String permission)

Determines the current state of the desired permission and returns it.

Parameters:

permission - The permission we want the current state of.

Returns:

Returns a PermissionState enum depicting what state the desired permission is in.

Returns null if we are in an invalid environemnt.

getPermissionStateForSupportedGroup

public PermissionState getPermissionStateForSupportedGroup(String permissionGroup)

Determines the current state of the desired permission group supported by Corona and returns it.

Parameters:

permissionGroup - The permission group we want the current state of.

Returns:

Returns a PermissionState enum depicting what state the desired permission group is in.

Will return PermissionState.GRANTED if all requested permissions in that group are granted.

If any of the requested permissions in the desired permission group are denied, then this method will return PermissionState.DENIED.

Will return PermissionState.MISSING if this group isn't supported by Corona or for this version of Android.

Returns null if we are in an invalid environemnt.

getPermissionGroupFromPermission

public String getPermissionGroupFromPermission(String permission)

Gets the permission group for the desired permission.

Parameters:

permission - The permission whose group we want.

Returns:

Returns the permission group for the desired permission.

Returns null if this permission doesn't belong to a group, is not defined on this device, or we're in an invalid environment.

getPermissionGroupFromPAAppPermissionName

public String getPermissionGroupFromPAAppPermissionName(String pAAppPermissionName)

Gets the Permission Group name for the given Platform-Agnostic App Permission name.

Parameters:

pAAppPermissionName - The Platform-Agnostic App Permission name to convert to a Permission Group name.

Returns:

Returns the Permission Group name for the given Platform-Agnostic App Permission.

Returns null if there's no permission group for this Platform-Agnostic App Permission.

getPAAppPermissionNameFromPermissionGroup

public String getPAAppPermissionNameFromPermissionGroup(String permissionGroup)

Gets the Platform-Agnostic App Permission name for the given Permission Group name.

Parameters:

permissionGroup - The Permission Group name to convert to a Platform-Agnostic App Permission name.

Returns:

Returns the Platform-Agnostic App Permission name for the given Permission Group name.

Returns null if there's no Platform-Agnostic App Permission name for this Permission Group name.

getPAAppPermissionNameFromAndroidPermission

public String getPAAppPermissionNameFromAndroidPermission(String permission)

Gets the Platform-Agnostic App Permission name for the given Android permission.

Parameters:

permission - The Android permission to convert to a Platform-Agnostic App Permission name.

Returns:

Returns the Platform-Agnostic App Permission name for the given Android permission.

Returns null if there's no Platform-Agnostic App Permission for this Android permission.

getRequestedPermissions

public String[] getRequestedPermissions()

Grabs all the requested permissions in the AndroidManifest.xml. These are all the tags.

Returns:

Returns a String array with the name of each found in the AndroidManifest.xml.

Returns null if no tags are in the AndroidManifest.xml or we're in an invalid environment.

getRequestedPermissionsInState

public String[] getRequestedPermissionsInState(PermissionState permissionState)

Gets all the requested permissions in the AndroidManifest.xml in the desired state.

Note: "Requested Permissions" are those defined in the AndroidManifest.xml. As such, calling this method with the argument "PermissionState.MISSING" is invalid.

Parameters:

permissionState - A PermissionState corresponding to the state of the requested permissions we wish to fetch.

Returns:

Returns a String array containing all the requested permissions in the desired state.

Returns null if given invalid arguments, in an invalid environemnt, or unable to get PackageInfo from the Android PackageManager.

getRequestedPermissionsInStateForGroup

public String[] getRequestedPermissionsInStateForGroup(PermissionState permissionState,
                                              String permissionGroup)

Gets all the requested permissions in the AndroidManifest.xml in the desired state for the desired Permission Group.

Note: "Requested Permissions" are those defined in the AndroidManifest.xml. As such, calling this method with the argument "PermissionState.MISSING" is invalid.

Parameters:

permissionState - A PermissionState corresponding to the state of the requested permissions we wish to fetch.

permissionGroup - The Permission Group for which we want to get all the Android permissions in the AndroidManifest.xml.

Returns:

Returns a String array containing all the requested permissions in the desired state for the desired Permission Group.

Returns null if given invalid arguments, in an invalid environemnt, or unable to get PackageInfo from the Android PackageManager.

getSupportedPermissionGroups

public String[] getSupportedPermissionGroups()

Returns a String array of all dangerous-level permissions groups supported by Corona.

isPartOfPAAppPermission

public boolean isPartOfPAAppPermission(String permission)

Determines if this Android permission is part of a Platform-Agnostic App Permission.

Parameters:

permission - The Android permission to check.

Returns:

Returns whether this Android permission is part of a Platform-Agnostic App Permission.

isPAAppPermissionName

public boolean isPAAppPermissionName(String name)

Determines if this name corresponds to the name of a Platform-Agnostic App Permission.

Parameters:

name - The name we're checking.

Returns:

Returns true if this name corresponds to the name of a Platform-Agnostic App Permission.

isSupportedPermissionGroupName

public boolean isSupportedPermissionGroupName(String name)

Determines if this name corresponds to the name of a dangerous-level Android Permission Group supported by Corona.

Parameters:

name - The name we're checking.

Returns:

Returns true if this name corresponds to the name of a dangerous-level Android Permission Group supported by Corona.

isPermissionInManifest

public boolean isPermissionInManifest(String permission)

Determines if the desired Android permission is in the AndroidManifest.xml.

Parameters:

permission - The Android permission we're looking for.

Returns:

Returns true if the desired permission was found in the AndroidManifest.xml; false otherwise.

requestPermissions

public final void requestPermissions(PermissionsSettings settings,
                      CoronaActivity.OnRequestPermissionsResultHandler resultHandler)

Requests the desired permissions, gathering data about which permissions are requested.

Wraps Activity.requestPermissions().

Parameters:

settings - The PermissionsSettings used for this request. Cannot be null!

resultHandler - The OnRequestPermissionsResultHandler that will be used to handle this permissions request.

requestAllDeniedPermissionsInGroup

public void requestAllDeniedPermissionsInGroup(String permissionGroup,
                                      CoronaActivity.OnRequestPermissionsResultHandler resultHandler)

Requests all permissions that are currently denied in the desired permission group.

Parameters:

permissionGroup - The Permission Group we want to request all denied permissions for.

resultHandler - The OnRequestPermissionsResultHandler that will be used to handle this permissions request.

shouldNeverAskAgain

public boolean shouldNeverAskAgain(String permission)

Determines if the user has requested the desired permission never be asked for again.

Parameters:

permission - The Android permission we want to know if it should never be requested again.

Returns:

Returns true if the user has requested the desired permission never be asked for again, we're not on an Android 6 and above device, or we're in an invalid environment. False otherwise.

showPermissionMissingFromManifestAlert

public void showPermissionMissingFromManifestAlert(String permission,
                                          String message)

Displays a native alert stating that this permission is missing from the AndroidManifest.xml.

Parameters:

permission - The name of the permission that's missing.

message - A message to explain why the action can't be performed.

showPermissionGroupMissingFromManifestAlert

public void showPermissionGroupMissingFromManifestAlert(String permissionGroup)

Displays a native alert stating that the AndroidManifest.xml doesn't contain any permissions from the desired permission group.

Parameters:

permissionGroup - The name of the permission group that's there's no permissions for.