RestrictionsManager
open class RestrictionsManager
kotlin.Any | |
↳ | android.content.RestrictionsManager |
Provides a mechanism for apps to query restrictions imposed by an entity that manages the user. Apps can also send permission requests to a local or remote device administrator to override default app-specific restrictions or any other operation that needs explicit authorization from the administrator.
Apps can expose a set of restrictions via an XML file specified in the manifest.
If the user has an active Restrictions Provider, dynamic requests can be made in addition to the statically imposed restrictions. Dynamic requests are app-specific and can be expressed via a predefined set of request types.
The RestrictionsManager forwards the dynamic requests to the active Restrictions Provider. The Restrictions Provider can respond back to requests by calling notifyPermissionResponse(java.lang.String,android.os.PersistableBundle)
, when a response is received from the administrator of the device or user. The response is relayed back to the application via a protected broadcast, ACTION_PERMISSION_RESPONSE_RECEIVED
.
Static restrictions are specified by an XML file referenced by a meta-data attribute in the manifest. This enables applications as well as any web administration consoles to be able to read the list of available restrictions from the apk.
The syntax of the XML format is as follows:
<?xml version="1.0" encoding="utf-8"?> <restrictions xmlns:android="http://schemas.android.com/apk/res/android" > <restriction android:key="string" android:title="string resource" android:restrictionType=["bool" | "string" | "integer" | "choice" | "multi-select" | "hidden" | "bundle" | "bundle_array"] android:description="string resource" android:entries="string-array resource" android:entryValues="string-array resource" android:defaultValue="reference" > <restriction ... /> ... </restriction> <restriction ... /> ... </restrictions>
The attributes for each restriction depend on the restriction type.
key
,title
andrestrictionType
are mandatory.entries
andentryValues
are required ifrestrictionType
ischoice
ormulti-select
.defaultValue
is optional and its type depends on therestrictionType
hidden
type must have adefaultValue
and will not be shown to the administrator. It can be used to pass along data that cannot be modified, such as a version code.description
is meant to describe the restriction in more detail to the administrator controlling the values, if the title is not sufficient.
Only restrictions of type bundle
and bundle_array
can have one or multiple nested restriction elements.
In your manifest's application
section, add the meta-data tag to point to the restrictions XML file as shown below:
<application ... > <meta-data android:name="android.content.APP_RESTRICTIONS" android:resource="@xml/app_restrictions" /> ... </application>
Summary
Constants | |
---|---|
static String |
Broadcast intent delivered when a response is received for a permission request. |
static String |
Activity intent that is optionally implemented by the Restrictions Provider package to challenge for an administrator PIN or password locally on the device. |
static String |
Broadcast intent sent to the Restrictions Provider to handle a permission request from an app. |
static String |
The package name of the application making the request. |
static String |
The request bundle passed in the |
static String |
The request ID passed in the |
static String |
The request type passed in the |
static String |
Contains a response from the administrator for specific request. |
static String |
Name of the meta-data entry in the manifest that points to the XML file containing the application's available restrictions. |
static String |
Key for request approval button label contained in the request bundle. |
static String |
Key for request data contained in the request bundle. |
static String |
Key for request rejection button label contained in the request bundle. |
static String |
Key for request icon contained in the request bundle. |
static String |
Key for request ID contained in the request bundle. |
static String |
Key for request message contained in the request bundle. |
static String |
Key for issuing a new request, contained in the request bundle. |
static String |
Key for request title contained in the request bundle. |
static String |
Request type for a simple question, with a possible title and icon. |
static String |
Key for the optional error code in the response bundle sent to the application. |
static String |
Key for the optional message in the response bundle sent to the application. |
static String |
Key for the optional timestamp of when the administrator responded to the permission request. |
static String |
Key for the response result in the response bundle sent to the application, for a permission request. |
static Int |
Response result value indicating that the request was approved. |
static Int |
Response result value indicating that the request was denied. |
static Int |
Response result value indicating an error condition. |
static Int |
Error code indicating that there was a problem with the request. |
static Int |
Error code indicating that there was an internal error. |
static Int |
Error code indicating that there was a problem with the network. |
static Int |
Response result value indicating that the request has not received a response yet. |
static Int |
Response result value indicating that the request is unknown, when it's not a new request. |
Public methods | |
---|---|
open static Bundle! |
convertRestrictionsToBundle(entries: MutableList<RestrictionEntry!>!) Converts a list of restrictions to the corresponding bundle, using the following mapping: |
open Intent! | |
open Bundle! |
Returns any available set of application-specific restrictions applicable to this application. |
open MutableList<Bundle!> |
Returns a |
open MutableList<RestrictionEntry!>! |
getManifestRestrictions(packageName: String!) Parse and return the list of restrictions defined in the manifest for the specified package, if any. |
open Boolean |
Called by an application to check if there is an active Restrictions Provider. |
open Unit |
notifyPermissionResponse(packageName: String!, response: PersistableBundle!) Called by the Restrictions Provider to deliver a response to an application. |
open Unit |
requestPermission(requestType: String!, requestId: String!, request: PersistableBundle!) Called by an application to request permission for an operation. |
Constants
ACTION_PERMISSION_RESPONSE_RECEIVED
static val ACTION_PERMISSION_RESPONSE_RECEIVED: String
Broadcast intent delivered when a response is received for a permission request. The application should not interrupt the user by coming to the foreground if it isn't currently in the foreground. It can either post a notification informing the user of the response or wait until the next time the user launches the app.
For instance, if the user requested permission to make an in-app purchase, the app can post a notification that the request had been approved or denied.
The broadcast Intent carries the following extra: EXTRA_RESPONSE_BUNDLE
.
Value: "android.content.action.PERMISSION_RESPONSE_RECEIVED"
ACTION_REQUEST_LOCAL_APPROVAL
static val ACTION_REQUEST_LOCAL_APPROVAL: String
Activity intent that is optionally implemented by the Restrictions Provider package to challenge for an administrator PIN or password locally on the device. Apps will call this intent using android.app.Activity#startActivityForResult. On a successful response, android.app.Activity#onActivityResult will return a resultCode of Activity#RESULT_OK
.
The intent must contain EXTRA_REQUEST_BUNDLE
as an extra and the bundle must contain at least REQUEST_KEY_MESSAGE
for the activity to display.
Value: "android.content.action.REQUEST_LOCAL_APPROVAL"
See Also
ACTION_REQUEST_PERMISSION
static val ACTION_REQUEST_PERMISSION: String
Broadcast intent sent to the Restrictions Provider to handle a permission request from an app. It will have the following extras: EXTRA_PACKAGE_NAME
, EXTRA_REQUEST_TYPE
, EXTRA_REQUEST_ID
and EXTRA_REQUEST_BUNDLE
. The Restrictions Provider will handle the request and respond back to the RestrictionsManager, when a response is available, by calling notifyPermissionResponse
.
The BroadcastReceiver must require the android.Manifest.permission#BIND_DEVICE_ADMIN
permission to ensure that only the system can send the broadcast.
Value: "android.content.action.REQUEST_PERMISSION"
EXTRA_PACKAGE_NAME
static val EXTRA_PACKAGE_NAME: String
The package name of the application making the request.
Type: String
Value: "android.content.extra.PACKAGE_NAME"
EXTRA_REQUEST_BUNDLE
static val EXTRA_REQUEST_BUNDLE: String
The request bundle passed in the ACTION_REQUEST_PERMISSION
broadcast.
Type: PersistableBundle
Value: "android.content.extra.REQUEST_BUNDLE"
EXTRA_REQUEST_ID
static val EXTRA_REQUEST_ID: String
The request ID passed in the ACTION_REQUEST_PERMISSION
broadcast.
Type: String
Value: "android.content.extra.REQUEST_ID"
EXTRA_REQUEST_TYPE
static val EXTRA_REQUEST_TYPE: String
The request type passed in the ACTION_REQUEST_PERMISSION
broadcast.
Type: String
Value: "android.content.extra.REQUEST_TYPE"
EXTRA_RESPONSE_BUNDLE
static val EXTRA_RESPONSE_BUNDLE: String
Contains a response from the administrator for specific request. The bundle contains the following information, at least:
REQUEST_KEY_ID
: The request ID.RESPONSE_KEY_RESULT
: The response result.
Type: PersistableBundle
Value: "android.content.extra.RESPONSE_BUNDLE"
META_DATA_APP_RESTRICTIONS
static val META_DATA_APP_RESTRICTIONS: String
Name of the meta-data entry in the manifest that points to the XML file containing the application's available restrictions.
Value: "android.content.APP_RESTRICTIONS"
See Also
REQUEST_KEY_APPROVE_LABEL
static val REQUEST_KEY_APPROVE_LABEL: String
Key for request approval button label contained in the request bundle.
Optional, may be shown as a label on the positive button in a dialog or notification presented to the administrator who approves the request.
Type: String
Value: "android.request.approve_label"
REQUEST_KEY_DATA
static val REQUEST_KEY_DATA: String
Key for request data contained in the request bundle.
Optional, typically used to identify the specific data that is being referred to, such as the unique identifier for a movie or book. This is not used for display purposes and is more like a cookie. This value is returned in the EXTRA_RESPONSE_BUNDLE
.
Type: String
Value: "android.request.data"
REQUEST_KEY_DENY_LABEL
static val REQUEST_KEY_DENY_LABEL: String
Key for request rejection button label contained in the request bundle.
Optional, may be shown as a label on the negative button in a dialog or notification presented to the administrator who approves the request.
Type: String
Value: "android.request.deny_label"
REQUEST_KEY_ICON
static val REQUEST_KEY_ICON: String
Key for request icon contained in the request bundle.
Optional, shown alongside the request message presented to the administrator who approves the request. The content must be a compressed image such as a PNG or JPEG, as a byte array.
Type: byte[]
Value: "android.request.icon"
REQUEST_KEY_ID
static val REQUEST_KEY_ID: String
Key for request ID contained in the request bundle.
App-generated request ID to identify the specific request when receiving a response. This value is returned in the EXTRA_RESPONSE_BUNDLE
.
Type: String
Value: "android.request.id"
REQUEST_KEY_MESSAGE
static val REQUEST_KEY_MESSAGE: String
Key for request message contained in the request bundle.
Required, shown as the actual message in a notification or dialog presented to the administrator who approves the request.
Type: String
Value: "android.request.mesg"
REQUEST_KEY_NEW_REQUEST
static val REQUEST_KEY_NEW_REQUEST: String
Key for issuing a new request, contained in the request bundle. If this is set to true, the Restrictions Provider must make a new request. If it is false or not specified, then the Restrictions Provider can return a cached response that has the same requestId, if available. If there's no cached response, it will issue a new one to the administrator.
Type: boolean
Value: "android.request.new_request"
REQUEST_KEY_TITLE
static val REQUEST_KEY_TITLE: String
Key for request title contained in the request bundle.
Optional, typically used as the title of any notification or dialog presented to the administrator who approves the request.
Type: String
Value: "android.request.title"
REQUEST_TYPE_APPROVAL
static val REQUEST_TYPE_APPROVAL: String
Request type for a simple question, with a possible title and icon.
Required keys are: REQUEST_KEY_MESSAGE
Optional keys are REQUEST_KEY_DATA
, REQUEST_KEY_ICON
, REQUEST_KEY_TITLE
, REQUEST_KEY_APPROVE_LABEL
and REQUEST_KEY_DENY_LABEL
.
Value: "android.request.type.approval"
RESPONSE_KEY_ERROR_CODE
static val RESPONSE_KEY_ERROR_CODE: String
Key for the optional error code in the response bundle sent to the application.
Type: int
Possible values: RESULT_ERROR_BAD_REQUEST
, RESULT_ERROR_NETWORK
or RESULT_ERROR_INTERNAL
.
Value: "android.response.errorcode"
RESPONSE_KEY_MESSAGE
static val RESPONSE_KEY_MESSAGE: String
Key for the optional message in the response bundle sent to the application.
Type: String
Value: "android.response.msg"
RESPONSE_KEY_RESPONSE_TIMESTAMP
static val RESPONSE_KEY_RESPONSE_TIMESTAMP: String
Key for the optional timestamp of when the administrator responded to the permission request. It is an represented in milliseconds since January 1, 1970 00:00:00.0 UTC.
Type: long
Value: "android.response.timestamp"
RESPONSE_KEY_RESULT
static val RESPONSE_KEY_RESULT: String
Key for the response result in the response bundle sent to the application, for a permission request. It indicates the status of the request. In some cases an additional message might be available in RESPONSE_KEY_MESSAGE
, to be displayed to the user.
Type: int
Possible values: RESULT_APPROVED
, RESULT_DENIED
, RESULT_NO_RESPONSE
, RESULT_UNKNOWN_REQUEST
or RESULT_ERROR
.
Value: "android.response.result"
RESULT_APPROVED
static val RESULT_APPROVED: Int
Response result value indicating that the request was approved.
Value: 1
RESULT_DENIED
static val RESULT_DENIED: Int
Response result value indicating that the request was denied.
Value: 2
RESULT_ERROR
static val RESULT_ERROR: Int
Response result value indicating an error condition. Additional error code might be available in the response bundle, for the key RESPONSE_KEY_ERROR_CODE
. There might also be an associated error message in the response bundle, for the key RESPONSE_KEY_MESSAGE
.
Value: 5
RESULT_ERROR_BAD_REQUEST
static val RESULT_ERROR_BAD_REQUEST: Int
Error code indicating that there was a problem with the request.
Stored in RESPONSE_KEY_ERROR_CODE
field in the response bundle.
Value: 1
RESULT_ERROR_INTERNAL
static val RESULT_ERROR_INTERNAL: Int
Error code indicating that there was an internal error.
Stored in RESPONSE_KEY_ERROR_CODE
field in the response bundle.
Value: 3
RESULT_ERROR_NETWORK
static val RESULT_ERROR_NETWORK: Int
Error code indicating that there was a problem with the network.
Stored in RESPONSE_KEY_ERROR_CODE
field in the response bundle.
Value: 2
RESULT_NO_RESPONSE
static val RESULT_NO_RESPONSE: Int
Response result value indicating that the request has not received a response yet.
Value: 3
RESULT_UNKNOWN_REQUEST
static val RESULT_UNKNOWN_REQUEST: Int
Response result value indicating that the request is unknown, when it's not a new request.
Value: 4
Public methods
convertRestrictionsToBundle
open static fun convertRestrictionsToBundle(entries: MutableList<RestrictionEntry!>!): Bundle!
Converts a list of restrictions to the corresponding bundle, using the following mapping:
Parameters | |
---|---|
entries |
MutableList<RestrictionEntry!>!: list of restrictions |
getApplicationRestrictions
open fun getApplicationRestrictions(): Bundle!
Returns any available set of application-specific restrictions applicable to this application.
Return | |
---|---|
Bundle! |
the application restrictions as a Bundle. Returns null if there are no restrictions.
Starting from Android version |
getApplicationRestrictionsPerAdmin
open fun getApplicationRestrictionsPerAdmin(): MutableList<Bundle!>
Returns a List
containing a Bundle
for each managing agent that has set restrictions for the current application, the bundle contains any application restrictions set for the current package. The order of the items in the list is not guaranteed to remain stable between multiple calls.
Starting from Android version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE
, it is possible for there to be multiple managing apps on the device with the ability to set restrictions, e.g. an Enterprise Device Policy Controller (DPC) and a Supervision admin.
Each Bundle
consists of key-value pairs, as defined by the application, where the types of values may be:
boolean
int
String
orString[]
- From
android.os.Build.VERSION_CODES#M
,Bundle
orBundle[]
NOTE: The method performs disk I/O and shouldn't be called on the main thread
This method may take several seconds to complete, so it should only be called from a worker thread.
Return | |
---|---|
MutableList<Bundle!> |
a List of Bundle containing the restrictions set by admins for that package. Returns an empty List if there are no saved restrictions. This value cannot be null . |
getManifestRestrictions
open fun getManifestRestrictions(packageName: String!): MutableList<RestrictionEntry!>!
Parse and return the list of restrictions defined in the manifest for the specified package, if any.
Parameters | |
---|---|
packageName |
String!: The application for which to fetch the restrictions list. |
Return | |
---|---|
MutableList<RestrictionEntry!>! |
The list of RestrictionEntry objects created from the XML file specified in the manifest, or null if none was specified. |
hasRestrictionsProvider
open fun hasRestrictionsProvider(): Boolean
Called by an application to check if there is an active Restrictions Provider. If there isn't, requestPermission(java.lang.String,java.lang.String,android.os.PersistableBundle)
is not available.
Return | |
---|---|
Boolean |
whether there is an active Restrictions Provider. |
notifyPermissionResponse
open fun notifyPermissionResponse(
packageName: String!,
response: PersistableBundle!
): Unit
Called by the Restrictions Provider to deliver a response to an application.
Parameters | |
---|---|
packageName |
String!: the application to deliver the response to. Cannot be null. |
response |
PersistableBundle!: the bundle containing the response status, request ID and other information. Cannot be null. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if any of the required parameters are missing. |
requestPermission
open fun requestPermission(
requestType: String!,
requestId: String!,
request: PersistableBundle!
): Unit
Called by an application to request permission for an operation. The contents of the request are passed in a Bundle that contains several pieces of data depending on the chosen request type.
Parameters | |
---|---|
requestType |
String!: The type of request. The type could be one of the predefined types specified here or a custom type that the specific Restrictions Provider might understand. For custom types, the type name should be namespaced to avoid collisions with predefined types and types specified by other Restrictions Providers. |
requestId |
String!: A unique id generated by the app that contains sufficient information to identify the parameters of the request when it receives the id in the response. |
request |
PersistableBundle!: A PersistableBundle containing the data corresponding to the specified request type. The keys for the data in the bundle depend on the request type. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if any of the required parameters are missing. |