public class RestrictionsManager extends Object
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(String, 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
and restrictionType
are mandatory.entries
and entryValues
are required if restrictionType
is choice
or multi-select
.defaultValue
is optional and its type depends on the
restrictionType
hidden
type must have a defaultValue
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>
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_PERMISSION_RESPONSE_RECEIVED
Broadcast intent delivered when a response is received for a permission request.
|
static String |
ACTION_REQUEST_LOCAL_APPROVAL
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 |
ACTION_REQUEST_PERMISSION
Broadcast intent sent to the Restrictions Provider to handle a permission request from
an app.
|
static String |
EXTRA_PACKAGE_NAME
The package name of the application making the request.
|
static String |
EXTRA_REQUEST_BUNDLE
The request bundle passed in the
ACTION_REQUEST_PERMISSION broadcast. |
static String |
EXTRA_REQUEST_ID
The request ID passed in the
ACTION_REQUEST_PERMISSION broadcast. |
static String |
EXTRA_REQUEST_TYPE
The request type passed in the
ACTION_REQUEST_PERMISSION broadcast. |
static String |
EXTRA_RESPONSE_BUNDLE
Contains a response from the administrator for specific request.
|
static String |
META_DATA_APP_RESTRICTIONS
Name of the meta-data entry in the manifest that points to the XML file containing the
application's available restrictions.
|
static String |
REQUEST_KEY_APPROVE_LABEL
Key for request approval button label contained in the request bundle.
|
static String |
REQUEST_KEY_DATA
Key for request data contained in the request bundle.
|
static String |
REQUEST_KEY_DENY_LABEL
Key for request rejection button label contained in the request bundle.
|
static String |
REQUEST_KEY_ICON
Key for request icon contained in the request bundle.
|
static String |
REQUEST_KEY_ID
Key for request ID contained in the request bundle.
|
static String |
REQUEST_KEY_MESSAGE
Key for request message contained in the request bundle.
|
static String |
REQUEST_KEY_NEW_REQUEST
Key for issuing a new request, contained in the request bundle.
|
static String |
REQUEST_KEY_TITLE
Key for request title contained in the request bundle.
|
static String |
REQUEST_TYPE_APPROVAL
Request type for a simple question, with a possible title and icon.
|
static String |
RESPONSE_KEY_ERROR_CODE
Key for the optional error code in the response bundle sent to the application.
|
static String |
RESPONSE_KEY_MESSAGE
Key for the optional message in the response bundle sent to the application.
|
static String |
RESPONSE_KEY_RESPONSE_TIMESTAMP
Key for the optional timestamp of when the administrator responded to the permission
request.
|
static String |
RESPONSE_KEY_RESULT
Key for the response result in the response bundle sent to the application, for a permission
request.
|
static int |
RESULT_APPROVED
Response result value indicating that the request was approved.
|
static int |
RESULT_DENIED
Response result value indicating that the request was denied.
|
static int |
RESULT_ERROR
Response result value indicating an error condition.
|
static int |
RESULT_ERROR_BAD_REQUEST
Error code indicating that there was a problem with the request.
|
static int |
RESULT_ERROR_INTERNAL
Error code indicating that there was an internal error.
|
static int |
RESULT_ERROR_NETWORK
Error code indicating that there was a problem with the network.
|
static int |
RESULT_NO_RESPONSE
Response result value indicating that the request has not received a response yet.
|
static int |
RESULT_UNKNOWN_REQUEST
Response result value indicating that the request is unknown, when it's not a new
request.
|
Constructor and Description |
---|
RestrictionsManager(Context context,
IRestrictionsManager service) |
public static final String ACTION_PERMISSION_RESPONSE_RECEIVED
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
.
public static final String ACTION_REQUEST_PERMISSION
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(java.lang.String, android.os.PersistableBundle)
.
The BroadcastReceiver must require the android.Manifest.permission#BIND_DEVICE_ADMIN
permission to ensure that only the system can send the broadcast.
public static final String ACTION_REQUEST_LOCAL_APPROVAL
Activity.startActivityForResult(android.content.Intent, int)
. On a successful
response, Activity.onActivityResult(int, int, android.content.Intent)
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.
createLocalApprovalIntent()
,
Constant Field Valuespublic static final String EXTRA_PACKAGE_NAME
Type: String
public static final String EXTRA_REQUEST_TYPE
ACTION_REQUEST_PERMISSION
broadcast.
Type: String
public static final String EXTRA_REQUEST_ID
ACTION_REQUEST_PERMISSION
broadcast.
Type: String
public static final String EXTRA_REQUEST_BUNDLE
ACTION_REQUEST_PERMISSION
broadcast.
Type: PersistableBundle
public static final String EXTRA_RESPONSE_BUNDLE
REQUEST_KEY_ID
: The request ID.RESPONSE_KEY_RESULT
: The response result.
Type: PersistableBundle
public static final String REQUEST_TYPE_APPROVAL
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
.
public static final String REQUEST_KEY_ID
App-generated request ID to identify the specific request when receiving
a response. This value is returned in the EXTRA_RESPONSE_BUNDLE
.
Type: String
public static final String REQUEST_KEY_DATA
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
public static final String REQUEST_KEY_TITLE
Optional, typically used as the title of any notification or dialog presented to the administrator who approves the request.
Type: String
public static final String REQUEST_KEY_MESSAGE
Required, shown as the actual message in a notification or dialog presented to the administrator who approves the request.
Type: String
public static final String REQUEST_KEY_ICON
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[]
public static final String REQUEST_KEY_APPROVE_LABEL
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
public static final String REQUEST_KEY_DENY_LABEL
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
public static final String REQUEST_KEY_NEW_REQUEST
Type: boolean
public static final String RESPONSE_KEY_RESULT
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
.
public static final int RESULT_APPROVED
public static final int RESULT_DENIED
public static final int RESULT_NO_RESPONSE
public static final int RESULT_UNKNOWN_REQUEST
public static final int RESULT_ERROR
RESPONSE_KEY_ERROR_CODE
. There might also be
an associated error message in the response bundle, for the key
RESPONSE_KEY_MESSAGE
.public static final int RESULT_ERROR_BAD_REQUEST
Stored in RESPONSE_KEY_ERROR_CODE
field in the response bundle.
public static final int RESULT_ERROR_NETWORK
Stored in RESPONSE_KEY_ERROR_CODE
field in the response bundle.
public static final int RESULT_ERROR_INTERNAL
Stored in RESPONSE_KEY_ERROR_CODE
field in the response bundle.
public static final String RESPONSE_KEY_ERROR_CODE
Type: int
Possible values: RESULT_ERROR_BAD_REQUEST
, RESULT_ERROR_NETWORK
or
RESULT_ERROR_INTERNAL
.
public static final String RESPONSE_KEY_MESSAGE
Type: String
public static final String RESPONSE_KEY_RESPONSE_TIMESTAMP
Type: long
public static final String META_DATA_APP_RESTRICTIONS
public RestrictionsManager(Context context, IRestrictionsManager service)
public Bundle getApplicationRestrictions()
public boolean hasRestrictionsProvider()
requestPermission(String, String, PersistableBundle)
is not available.public void requestPermission(String requestType, String requestId, PersistableBundle request)
requestType
- 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
- 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
- A PersistableBundle containing the data corresponding to the specified request
type. The keys for the data in the bundle depend on the request type.IllegalArgumentException
- if any of the required parameters are missing.public Intent createLocalApprovalIntent()
public void notifyPermissionResponse(String packageName, PersistableBundle response)
packageName
- the application to deliver the response to. Cannot be null.response
- the bundle containing the response status, request ID and other information.
Cannot be null.IllegalArgumentException
- if any of the required parameters are missing.public List<RestrictionEntry> getManifestRestrictions(String packageName)
packageName
- The application for which to fetch the restrictions list.public static Bundle convertRestrictionsToBundle(List<RestrictionEntry> entries)
entries
- list of restrictions