[[ AndroidPermissionsLCB ]] Added permission checking handlers to android-utils.

livecodemichael · livecodemichael · commit ee9fda05c97a · 2019-05-15T09:32:07.000+01:00
The android-utils lcb module has been updated to expose
LiveCode's android permission API. Three new handlers have been
added to the module that just wrap their equivalent engine
functions.
diff --git a/engine/src/mblandroiddc.cpp b/engine/src/mblandroiddc.cpp
@@ -2859,6 +2859,8 @@ void MCAndroidDisableOpenGLMode(void)
 
 static bool s_in_permission_dialog = false;
 static bool s_permission_granted = false;
+
+MC_DLLEXPORT_DEF
 bool MCAndroidCheckRuntimePermission(MCStringRef p_permission)
 {
     bool t_result;
@@ -2867,10 +2869,11 @@ bool MCAndroidCheckRuntimePermission(MCStringRef p_permission)
     
     while (s_in_permission_dialog)
         MCscreen -> wait(60.0, False, True);
-    
+
     return s_permission_granted;
 }
 
+MC_DLLEXPORT_DEF
 bool MCAndroidCheckPermissionExists(MCStringRef p_permission)
 {
     bool t_result;
@@ -2879,6 +2882,7 @@ bool MCAndroidCheckPermissionExists(MCStringRef p_permission)
     return t_result;
 }
 
+MC_DLLEXPORT_DEF
 bool MCAndroidHasPermission(MCStringRef p_permission)
 {
     bool t_result;
diff --git a/engine/src/mblandroidutil.h b/engine/src/mblandroidutil.h
@@ -63,8 +63,11 @@ void MCAndroidObjectCall(jobject p_object, const char *p_method, const char *p_s
 void MCAndroidObjectRemoteCall(jobject p_object, const char *p_method, const char *p_signature, void *p_return_value, ...);
 
 bool MCAndroidGetBuildInfo(MCStringRef t_key, MCStringRef &r_value);
+extern "C" MC_DLLEXPORT
 bool MCAndroidCheckRuntimePermission(MCStringRef p_permission);
+extern "C" MC_DLLEXPORT
 bool MCAndroidCheckPermissionExists(MCStringRef p_permission);
+extern "C" MC_DLLEXPORT
 bool MCAndroidHasPermission(MCStringRef p_permission);
 
 typedef struct _android_device_configuration
diff --git a/extensions/modules/android-utils/android-utils.lcb b/extensions/modules/android-utils/android-utils.lcb
@@ -33,7 +33,7 @@ metadata os is "android"
 
 private handler ColorComponentToInt(in pComponent as Real) returns Integer
     multiply pComponent by 255
-    round pComponent 
+    round pComponent
     return pComponent
 end handler
 
@@ -47,13 +47,13 @@ Parameters:
 pString: The color string
 
 Description:
-Use the <StringToAndroidColor> handler to convert a string representing 
+Use the <StringToAndroidColor> handler to convert a string representing
 a color to an integer that can be used with Android color APIs.
-*/	
+*/
 public handler StringToAndroidColor(in pString as String) returns Integer
     variable tColor as Color
     put stringToColor(pString) into tColor
-    
+
     variable tA as Integer
     variable tR as Integer
     variable tG as Integer
@@ -62,7 +62,7 @@ public handler StringToAndroidColor(in pString as String) returns Integer
     put ColorComponentToInt(the red of tColor) into tR
     put ColorComponentToInt(the green of tColor) into tG
     put ColorComponentToInt(the blue of tColor) into tB
-    
+
     return _JNI_GetColorFromARGB(tA,tR,tG,tB)
 end handler
 
@@ -84,9 +84,152 @@ Example:
 
 Description:
 Use the <ApplicationContext> handler to fetch the current application's
-Context object. 
+Context object.
 */
 public handler ApplicationContext() returns JObject
 	return _JNI_GetEngineContext(_JNI_GetAndroidEngine())
 end handler
+
+private foreign handler MCAndroidCheckRuntimePermission(in pPermission as String) \
+	returns CBool binds to "<builtin>"
+
+/**
+Summary:
+Displays a dialog showing a permission request for <pPermission>. If a user
+has already granted permission for <pPermission>, this function does nothing.
+
+Returns true if permission <pPermission> has been granted by the user.
+
+Parameters:
+pPermission (enum):
+The name of the permission to request.
+
+-   "android.permission.READ_CALENDAR": permission to allow an application to read the device's calendar.
+-   "android.permission.WRITE_CALENDAR": permission to allow an application to write to the device's calendar.
+-   "android.permission.CAMERA": permission to allow an application to access the device's camera.
+-   "android.permission.ACCESS_COARSE_LOCATION": permission to allow an application to access the device's coarse location.
+-   "android.permission.ACCESS_FINE_LOCATION": permission to allow an application to access the device's fine location.
+-   "android.permission.READ_CONTACTS": permission to allow an application to read data from the device's contacts.
+-   "android.permission.WRITE_CONTACTS": permission to allow an application to write date to the device's contacts.
+-   "android.permission.GET_ACCOUNTS": permission to allow an application to access to the list of accounts in the Accounts Service.
+-   "android.permission.RECORD_AUDIO": permission to allow an application to allow an application to record audio.
+-   "android.permission.READ_EXTERNAL_STORAGE": permission to allow an application to read data from the device's external storage.
+-   "android.permission.WRITE_EXTERNAL_STORAGE": permission to allow an application to write data to the device's external storage.
+-   "android.permission.READ_PHONE_STATE": permission to allow an application to access phone state, including the phone number of the device, current cellular network information, the status of any ongoing calls, and a list of any PhoneAccounts registered on the device.
+-   "android.permission.READ_PHONE_NUMBERS": permission to allow an application to access the device's phone number(s).
+-   "android.permission.CALL_PHONE": permission to allow an application to initiate a phone call without going through the Dialer user interface for the user to confirm the call.
+-   "android.permission.ANSWER_PHONE_CALLS": permission to allow an application to answer an incoming phone call.
+-   "android.permission.READ_CALL_LOG": permission to allow an application to read the user's call log.
+-   "android.permission.WRITE_CALL_LOG": permission to allow an application to write to the user's call log.
+-   "android.permission.ADD_VOICEMAIL": permission to allow an application to add voicemails into the system.
+-   "android.permission.USE_SIP": permission to allow an application to use SIP service.
+-   "android.permission.PROCESS_OUTGOING_CALLS": permission to allow an application to see the number being dialed during an outgoing call with the option to redirect the call to a different number or abort the call altogether.
+-   "android.permission.SEND_SMS": permission to allow an application to send SMS messages.
+-   "android.permission.RECEIVE_SMS": permission to allow an application to receive SMS messages
+-   "android.permission.READ_SMS": permission to allow an application to read SMS messages.
+-   "android.permission.RECEIVE_WAP_PUSH": permission to allow an application to receive WAP push messages.
+-   "android.permission.RECEIVE_MMS": permission to allow an application to receive MMS messages.
+-   "android.permission.BODY_SENSORS": permission to allow an application to access data from sensors that the user uses to measure what is happening inside his/her body, such as heart rate.
+
+Returns(boolean):
+True if permission has been granted, false otherwise.
+
+Description:
+Use the <AndroidRequestPermission> command to request permission for
+<pPermission> from the user.
+
+>*Note:* Permission names are case sensitive.
+*/
+public handler AndroidRequestPermission(in pPermission as String) returns Boolean
+	variable tHasPermission as Boolean
+	unsafe
+		MCAndroidCheckRuntimePermission(pPermission)
+		put MCAndroidHasPermission(pPermission) into tHasPermission
+	end unsafe
+	return tHasPermission
+end handler
+
+private foreign handler MCAndroidCheckPermissionExists(in pPermission as String) \
+	returns CBool binds to "<builtin>"
+
+/**
+Summary:
+Returns true if <pPermission> is a valid Android permission name
+
+Parameters:
+pPermission (string):
+The name of the permission to check.
+
+Returns(boolean):
+True if <pPermission> is a valid Android permission name, false otherwise.
+
+Description:
+Use the <AndroidPermissionExists> function to check if <pPermission> is a valid
+Android permission name.
+
+>*Note:* Permission names are case sensitive.
+*/
+public handler AndroidPermissionExists(in pPermission as String) returns Boolean
+	variable tPermissionExists as Boolean
+	unsafe
+		put MCAndroidCheckPermissionExists(pPermission) into tPermissionExists
+	end unsafe
+	return tPermissionExists
+end handler
+
+private foreign handler MCAndroidHasPermission(in pPermission as String) \
+	returns CBool binds to "<builtin>"
+
+/**
+Summary:
+Returns true if permission <pPermission> has been granted by the user.
+
+Parameters:
+pPermission (enum):
+The name of the permission to request.
+
+-   "android.permission.READ_CALENDAR": permission to allow an application to read the device's calendar.
+-   "android.permission.WRITE_CALENDAR": permission to allow an application to write to the device's calendar.
+-   "android.permission.CAMERA": permission to allow an application to access the device's camera.
+-   "android.permission.ACCESS_COARSE_LOCATION": permission to allow an application to access the device's coarse location.
+-   "android.permission.ACCESS_FINE_LOCATION": permission to allow an application to access the device's fine location.
+-   "android.permission.READ_CONTACTS": permission to allow an application to read data from the device's contacts.
+-   "android.permission.WRITE_CONTACTS": permission to allow an application to write date to the device's contacts.
+-   "android.permission.GET_ACCOUNTS": permission to allow an application to access to the list of accounts in the Accounts Service.
+-   "android.permission.RECORD_AUDIO": permission to allow an application to allow an application to record audio.
+-   "android.permission.READ_EXTERNAL_STORAGE": permission to allow an application to read data from the device's external storage.
+-   "android.permission.WRITE_EXTERNAL_STORAGE": permission to allow an application to write data to the device's external storage.
+-   "android.permission.READ_PHONE_STATE": permission to allow an application to access phone state, including the phone number of the device, current cellular network information, the status of any ongoing calls, and a list of any PhoneAccounts registered on the device.
+-   "android.permission.READ_PHONE_NUMBERS": permission to allow an application to access the device's phone number(s).
+-   "android.permission.CALL_PHONE": permission to allow an application to initiate a phone call without going through the Dialer user interface for the user to confirm the call.
+-   "android.permission.ANSWER_PHONE_CALLS": permission to allow an application to answer an incoming phone call.
+-   "android.permission.READ_CALL_LOG": permission to allow an application to read the user's call log.
+-   "android.permission.WRITE_CALL_LOG": permission to allow an application to write to the user's call log.
+-   "android.permission.ADD_VOICEMAIL": permission to allow an application to add voicemails into the system.
+-   "android.permission.USE_SIP": permission to allow an application to use SIP service.
+-   "android.permission.PROCESS_OUTGOING_CALLS": permission to allow an application to see the number being dialed during an outgoing call with the option to redirect the call to a different number or abort the call altogether.
+-   "android.permission.SEND_SMS": permission to allow an application to send SMS messages.
+-   "android.permission.RECEIVE_SMS": permission to allow an application to receive SMS messages
+-   "android.permission.READ_SMS": permission to allow an application to read SMS messages.
+-   "android.permission.RECEIVE_WAP_PUSH": permission to allow an application to receive WAP push messages.
+-   "android.permission.RECEIVE_MMS": permission to allow an application to receive MMS messages.
+-   "android.permission.BODY_SENSORS": permission to allow an application to access data from sensors that the user uses to measure what is happening inside his/her body, such as heart rate.
+
+Returns(boolean):
+True if permission has been granted, false otherwise.
+
+Description:
+Use the <AndroidHasPermission> function to find out if permission
+<pPermission> has been granted by the user.
+
+>*Note:* Permission names are case sensitive.
+*/
+public handler AndroidHasPermission(in pPermission as String) returns Boolean
+	variable tHasPermission as Boolean
+	unsafe
+		put MCAndroidHasPermission(pPermission) into tHasPermission
+	end unsafe
+	return tHasPermission
+end handler
+
 end module
diff --git a/extensions/modules/android-utils/notes/feature-android_permissions.md b/extensions/modules/android-utils/notes/feature-android_permissions.md
@@ -0,0 +1,15 @@
+# Android Permission Checking
+
+The ability to check Android permissions in LCB has been added to the android
+utility module.
+
+Use these handlers to check and request permissions before accessing resources
+(e.g. camera access).
+
+The following handler have been added:
+
+* `AndroidRequestPermission` - Display a dialog requesting a given permission.
+* `AndroidPermissionExists` - Check to see if a given permission name is valid.
+* `AndroidHasPermission` - Check to see if a given permission has been granted.
+
+See the dictionary for full details.

Original file line number	Diff line number	Diff line change
`@@ -2859,6 +2859,8 @@ void MCAndroidDisableOpenGLMode(void)`
`2859`	`2859`
`2860`	`2860`	`static bool s_in_permission_dialog = false;`
`2861`	`2861`	`static bool s_permission_granted = false;`
	`2862`	`+`
	`2863`	`+MC_DLLEXPORT_DEF`
`2862`	`2864`	`bool MCAndroidCheckRuntimePermission(MCStringRef p_permission)`
`2863`	`2865`	`{`
`2864`	`2866`	`bool t_result;`
`@@ -2867,10 +2869,11 @@ bool MCAndroidCheckRuntimePermission(MCStringRef p_permission)`
`2867`	`2869`
`2868`	`2870`	`while (s_in_permission_dialog)`
`2869`	`2871`	`MCscreen -> wait(60.0, False, True);`
`2870`		`-`
	`2872`	`+`
`2871`	`2873`	`return s_permission_granted;`
`2872`	`2874`	`}`
`2873`	`2875`
	`2876`	`+MC_DLLEXPORT_DEF`
`2874`	`2877`	`bool MCAndroidCheckPermissionExists(MCStringRef p_permission)`
`2875`	`2878`	`{`
`2876`	`2879`	`bool t_result;`
`@@ -2879,6 +2882,7 @@ bool MCAndroidCheckPermissionExists(MCStringRef p_permission)`
`2879`	`2882`	`return t_result;`
`2880`	`2883`	`}`
`2881`	`2884`
	`2885`	`+MC_DLLEXPORT_DEF`
`2882`	`2886`	`bool MCAndroidHasPermission(MCStringRef p_permission)`
`2883`	`2887`	`{`
`2884`	`2888`	`bool t_result;`