/*
 * Copyright (C) 2013 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.content;

import android.annotation.ArrayRes;
import android.os.Parcel;
import android.os.Parcelable;

import java.util.Arrays;
import java.util.Objects;

Applications can expose restrictions for a restricted user on a multiuser device. The administrator can configure these restrictions that will then be applied to the restricted user. Each RestrictionsEntry is one configurable restriction.

Any application that chooses to expose such restrictions does so by implementing a receiver that handles the Intent.ACTION_GET_RESTRICTION_ENTRIES action. The receiver then returns a result bundle that contains an entry called "restrictions", whose value is an ArrayList.
/** * Applications can expose restrictions for a restricted user on a * multiuser device. The administrator can configure these restrictions that will then be * applied to the restricted user. Each RestrictionsEntry is one configurable restriction. * <p/> * Any application that chooses to expose such restrictions does so by implementing a * receiver that handles the {@link Intent#ACTION_GET_RESTRICTION_ENTRIES} action. * The receiver then returns a result bundle that contains an entry called "restrictions", whose * value is an ArrayList<RestrictionsEntry>. */
public class RestrictionEntry implements Parcelable {
Hidden restriction type. Use this type for information that needs to be transferred across but shouldn't be presented to the user in the UI. Stores a single String value.
/** * Hidden restriction type. Use this type for information that needs to be transferred * across but shouldn't be presented to the user in the UI. Stores a single String value. */
public static final int TYPE_NULL = 0;
Restriction of type "bool". Use this for storing a boolean value, typically presented as a checkbox in the UI.
/** * Restriction of type "bool". Use this for storing a boolean value, typically presented as * a checkbox in the UI. */
public static final int TYPE_BOOLEAN = 1;
Restriction of type "choice". Use this for storing a string value, typically presented as a single-select list. Call setChoiceEntries(String[]) and setChoiceValues(String[]) to set the localized list entries to present to the user and the corresponding values, respectively.
/** * Restriction of type "choice". Use this for storing a string value, typically presented as * a single-select list. Call {@link #setChoiceEntries(String[])} and * {@link #setChoiceValues(String[])} to set the localized list entries to present to the user * and the corresponding values, respectively. */
public static final int TYPE_CHOICE = 2;
Internal restriction type. Use this for storing a string value, typically presented as a single-select list. Call setChoiceEntries(String[]) and setChoiceValues(String[]) to set the localized list entries to present to the user and the corresponding values, respectively. The presentation could imply that values in lower array indices are included when a particular value is chosen.
@hide
/** * Internal restriction type. Use this for storing a string value, typically presented as * a single-select list. Call {@link #setChoiceEntries(String[])} and * {@link #setChoiceValues(String[])} to set the localized list entries to present to the user * and the corresponding values, respectively. * The presentation could imply that values in lower array indices are included when a * particular value is chosen. * @hide */
public static final int TYPE_CHOICE_LEVEL = 3;
Restriction of type "multi-select". Use this for presenting a multi-select list where more than one entry can be selected, such as for choosing specific titles to white-list. Call setChoiceEntries(String[]) and setChoiceValues(String[]) to set the localized list entries to present to the user and the corresponding values, respectively. Use getAllSelectedStrings() and setAllSelectedStrings(String[]) to manipulate the selections.
/** * Restriction of type "multi-select". Use this for presenting a multi-select list where more * than one entry can be selected, such as for choosing specific titles to white-list. * Call {@link #setChoiceEntries(String[])} and * {@link #setChoiceValues(String[])} to set the localized list entries to present to the user * and the corresponding values, respectively. * Use {@link #getAllSelectedStrings()} and {@link #setAllSelectedStrings(String[])} to * manipulate the selections. */
public static final int TYPE_MULTI_SELECT = 4;
Restriction of type "integer". Use this for storing an integer value. The range of values is from Integer.MIN_VALUE to Integer.MAX_VALUE.
/** * Restriction of type "integer". Use this for storing an integer value. The range of values * is from {@link Integer#MIN_VALUE} to {@link Integer#MAX_VALUE}. */
public static final int TYPE_INTEGER = 5;
Restriction of type "string". Use this for storing a string value.
See Also:
/** * Restriction of type "string". Use this for storing a string value. * @see #setSelectedString * @see #getSelectedString */
public static final int TYPE_STRING = 6;
Restriction of type "bundle". Use this for storing bundles of restrictions
/** * Restriction of type "bundle". Use this for storing {@link android.os.Bundle bundles} of * restrictions */
public static final int TYPE_BUNDLE = 7;
Restriction of type "bundle_array". Use this for storing arrays of bundles of restrictions
/** * Restriction of type "bundle_array". Use this for storing arrays of * {@link android.os.Bundle bundles} of restrictions */
public static final int TYPE_BUNDLE_ARRAY = 8;
The type of restriction.
/** The type of restriction. */
private int mType;
The unique key that identifies the restriction.
/** The unique key that identifies the restriction. */
private String mKey;
The user-visible title of the restriction.
/** The user-visible title of the restriction. */
private String mTitle;
The user-visible secondary description of the restriction.
/** The user-visible secondary description of the restriction. */
private String mDescription;
The user-visible set of choices used for single-select and multi-select lists.
/** The user-visible set of choices used for single-select and multi-select lists. */
private String[] mChoiceEntries;
The values corresponding to the user-visible choices. The value(s) of this entry will one or more of these, returned by getAllSelectedStrings() and getSelectedString().
/** The values corresponding to the user-visible choices. The value(s) of this entry will * one or more of these, returned by {@link #getAllSelectedStrings()} and * {@link #getSelectedString()}. */
private String[] mChoiceValues; /* The chosen value, whose content depends on the type of the restriction. */ private String mCurrentValue; /* List of selected choices in the multi-select case. */ private String[] mCurrentValues;
List of nested restrictions. Used by bundle and bundle_array restrictions.
/** * List of nested restrictions. Used by {@link #TYPE_BUNDLE bundle} and * {@link #TYPE_BUNDLE_ARRAY bundle_array} restrictions. */
private RestrictionEntry[] mRestrictions;
Constructor for specifying the type and key, with no initial value;
Params:
  • type – the restriction type.
  • key – the unique key for this restriction
/** * Constructor for specifying the type and key, with no initial value; * * @param type the restriction type. * @param key the unique key for this restriction */
public RestrictionEntry(int type, String key) { mType = type; mKey = key; }
Constructor for TYPE_CHOICE type.
Params:
  • key – the unique key for this restriction
  • selectedString – the current value
/** * Constructor for {@link #TYPE_CHOICE} type. * @param key the unique key for this restriction * @param selectedString the current value */
public RestrictionEntry(String key, String selectedString) { this.mKey = key; this.mType = TYPE_CHOICE; this.mCurrentValue = selectedString; }
Constructor for TYPE_BOOLEAN type.
Params:
  • key – the unique key for this restriction
  • selectedState – whether this restriction is selected or not
/** * Constructor for {@link #TYPE_BOOLEAN} type. * @param key the unique key for this restriction * @param selectedState whether this restriction is selected or not */
public RestrictionEntry(String key, boolean selectedState) { this.mKey = key; this.mType = TYPE_BOOLEAN; setSelectedState(selectedState); }
Constructor for TYPE_MULTI_SELECT type.
Params:
  • key – the unique key for this restriction
  • selectedStrings – the list of values that are currently selected
/** * Constructor for {@link #TYPE_MULTI_SELECT} type. * @param key the unique key for this restriction * @param selectedStrings the list of values that are currently selected */
public RestrictionEntry(String key, String[] selectedStrings) { this.mKey = key; this.mType = TYPE_MULTI_SELECT; this.mCurrentValues = selectedStrings; }
Constructor for TYPE_INTEGER type.
Params:
  • key – the unique key for this restriction
  • selectedInt – the integer value of the restriction
/** * Constructor for {@link #TYPE_INTEGER} type. * @param key the unique key for this restriction * @param selectedInt the integer value of the restriction */
public RestrictionEntry(String key, int selectedInt) { mKey = key; mType = TYPE_INTEGER; setIntValue(selectedInt); }
Constructor for TYPE_BUNDLE/TYPE_BUNDLE_ARRAY type.
Params:
  • key – the unique key for this restriction
  • restrictionEntries – array of nested restriction entries. If the entry, being created represents a bundle-array, restrictionEntries array may only contain elements of type bundle.
  • isBundleArray – true if this restriction represents bundle-array type, otherwise the type will be set to bundle.
/** * Constructor for {@link #TYPE_BUNDLE}/{@link #TYPE_BUNDLE_ARRAY} type. * @param key the unique key for this restriction * @param restrictionEntries array of nested restriction entries. If the entry, being created * represents a {@link #TYPE_BUNDLE_ARRAY bundle-array}, {@code restrictionEntries} array may * only contain elements of type {@link #TYPE_BUNDLE bundle}. * @param isBundleArray true if this restriction represents * {@link #TYPE_BUNDLE_ARRAY bundle-array} type, otherwise the type will be set to * {@link #TYPE_BUNDLE bundle}. */
private RestrictionEntry(String key, RestrictionEntry[] restrictionEntries, boolean isBundleArray) { mKey = key; if (isBundleArray) { mType = TYPE_BUNDLE_ARRAY; if (restrictionEntries != null) { for (RestrictionEntry restriction : restrictionEntries) { if (restriction.getType() != TYPE_BUNDLE) { throw new IllegalArgumentException("bundle_array restriction can only have " + "nested restriction entries of type bundle"); } } } } else { mType = TYPE_BUNDLE; } setRestrictions(restrictionEntries); }
Creates an entry of type TYPE_BUNDLE.
Params:
  • key – the unique key for this restriction
  • restrictionEntries – array of nested restriction entries.
Returns:the newly created restriction
/** * Creates an entry of type {@link #TYPE_BUNDLE}. * @param key the unique key for this restriction * @param restrictionEntries array of nested restriction entries. * @return the newly created restriction */
public static RestrictionEntry createBundleEntry(String key, RestrictionEntry[] restrictionEntries) { return new RestrictionEntry(key, restrictionEntries, false); }
Creates an entry of type TYPE_BUNDLE_ARRAY.
Params:
  • key – the unique key for this restriction
  • restrictionEntries – array of nested restriction entries. The array may only contain elements of type bundle.
Returns:the newly created restriction
/** * Creates an entry of type {@link #TYPE_BUNDLE_ARRAY}. * @param key the unique key for this restriction * @param restrictionEntries array of nested restriction entries. The array may only contain * elements of type {@link #TYPE_BUNDLE bundle}. * @return the newly created restriction */
public static RestrictionEntry createBundleArrayEntry(String key, RestrictionEntry[] restrictionEntries) { return new RestrictionEntry(key, restrictionEntries, true); }
Sets the type for this restriction.
Params:
  • type – the type for this restriction.
/** * Sets the type for this restriction. * @param type the type for this restriction. */
public void setType(int type) { this.mType = type; }
Returns the type for this restriction.
Returns:the type for this restriction
/** * Returns the type for this restriction. * @return the type for this restriction */
public int getType() { return mType; }
Returns the currently selected string value.
Returns:the currently selected value, which can be null for types that aren't for holding single string values.
/** * Returns the currently selected string value. * @return the currently selected value, which can be null for types that aren't for holding * single string values. */
public String getSelectedString() { return mCurrentValue; }
Returns the list of currently selected values.
Returns:the list of current selections, if type is TYPE_MULTI_SELECT, null otherwise.
/** * Returns the list of currently selected values. * @return the list of current selections, if type is {@link #TYPE_MULTI_SELECT}, * null otherwise. */
public String[] getAllSelectedStrings() { return mCurrentValues; }
Returns the current selected state for an entry of type TYPE_BOOLEAN.
Returns:the current selected state of the entry.
/** * Returns the current selected state for an entry of type {@link #TYPE_BOOLEAN}. * @return the current selected state of the entry. */
public boolean getSelectedState() { return Boolean.parseBoolean(mCurrentValue); }
Returns the value of the entry as an integer when the type is TYPE_INTEGER.
Returns:the integer value of the entry.
/** * Returns the value of the entry as an integer when the type is {@link #TYPE_INTEGER}. * @return the integer value of the entry. */
public int getIntValue() { return Integer.parseInt(mCurrentValue); }
Sets the integer value of the entry when the type is TYPE_INTEGER.
Params:
  • value – the integer value to set.
/** * Sets the integer value of the entry when the type is {@link #TYPE_INTEGER}. * @param value the integer value to set. */
public void setIntValue(int value) { mCurrentValue = Integer.toString(value); }
Sets the string value to use as the selected value for this restriction. This value will be persisted by the system for later use by the application.
Params:
  • selectedString – the string value to select.
/** * Sets the string value to use as the selected value for this restriction. This value will * be persisted by the system for later use by the application. * @param selectedString the string value to select. */
public void setSelectedString(String selectedString) { mCurrentValue = selectedString; }
Sets the current selected state for an entry of type TYPE_BOOLEAN. This value will be persisted by the system for later use by the application.
Params:
  • state – the current selected state
/** * Sets the current selected state for an entry of type {@link #TYPE_BOOLEAN}. This value will * be persisted by the system for later use by the application. * @param state the current selected state */
public void setSelectedState(boolean state) { mCurrentValue = Boolean.toString(state); }
Sets the current list of selected values for an entry of type TYPE_MULTI_SELECT. These values will be persisted by the system for later use by the application.
Params:
  • allSelectedStrings – the current list of selected values.
/** * Sets the current list of selected values for an entry of type {@link #TYPE_MULTI_SELECT}. * These values will be persisted by the system for later use by the application. * @param allSelectedStrings the current list of selected values. */
public void setAllSelectedStrings(String[] allSelectedStrings) { mCurrentValues = allSelectedStrings; }
Sets a list of string values that can be selected by the user. If no user-visible entries are set by a call to setChoiceEntries(String[]), these values will be the ones shown to the user. Values will be chosen from this list as the user's selection and the selected values can be retrieved by a call to getAllSelectedStrings(), or getSelectedString(), depending on whether it is a multi-select type or choice type. This method is not relevant for types other than TYPE_CHOICE, and TYPE_MULTI_SELECT.
Params:
  • choiceValues – an array of Strings which will be the selected values for the user's selections.
See Also:
/** * Sets a list of string values that can be selected by the user. If no user-visible entries * are set by a call to {@link #setChoiceEntries(String[])}, these values will be the ones * shown to the user. Values will be chosen from this list as the user's selection and the * selected values can be retrieved by a call to {@link #getAllSelectedStrings()}, or * {@link #getSelectedString()}, depending on whether it is a multi-select type or choice type. * This method is not relevant for types other than * {@link #TYPE_CHOICE}, and {@link #TYPE_MULTI_SELECT}. * @param choiceValues an array of Strings which will be the selected values for the user's * selections. * @see #getChoiceValues() * @see #getAllSelectedStrings() */
public void setChoiceValues(String[] choiceValues) { mChoiceValues = choiceValues; }
Sets a list of string values that can be selected by the user, similar to setChoiceValues(String[]).
Params:
  • context – the application context for retrieving the resources.
  • stringArrayResId – the resource id for a string array containing the possible values.
See Also:
/** * Sets a list of string values that can be selected by the user, similar to * {@link #setChoiceValues(String[])}. * @param context the application context for retrieving the resources. * @param stringArrayResId the resource id for a string array containing the possible values. * @see #setChoiceValues(String[]) */
public void setChoiceValues(Context context, @ArrayRes int stringArrayResId) { mChoiceValues = context.getResources().getStringArray(stringArrayResId); }
Returns array of possible restriction entries that this entry may contain.
/** * Returns array of possible restriction entries that this entry may contain. */
public RestrictionEntry[] getRestrictions() { return mRestrictions; }
Sets an array of possible restriction entries, that this entry may contain.

This method is only relevant for types TYPE_BUNDLE and TYPE_BUNDLE_ARRAY

/** * Sets an array of possible restriction entries, that this entry may contain. * <p>This method is only relevant for types {@link #TYPE_BUNDLE} and * {@link #TYPE_BUNDLE_ARRAY} */
public void setRestrictions(RestrictionEntry[] restrictions) { mRestrictions = restrictions; }
Returns the list of possible string values set earlier.
Returns:the list of possible values.
/** * Returns the list of possible string values set earlier. * @return the list of possible values. */
public String[] getChoiceValues() { return mChoiceValues; }
Sets a list of strings that will be presented as choices to the user. When the user selects one or more of these choices, the corresponding value from the possible values are stored as the selected strings. The size of this array must match the size of the array set in setChoiceValues(String[]). This method is not relevant for types other than TYPE_CHOICE, and TYPE_MULTI_SELECT.
Params:
  • choiceEntries – the list of user-visible choices.
See Also:
/** * Sets a list of strings that will be presented as choices to the user. When the * user selects one or more of these choices, the corresponding value from the possible values * are stored as the selected strings. The size of this array must match the size of the array * set in {@link #setChoiceValues(String[])}. This method is not relevant for types other * than {@link #TYPE_CHOICE}, and {@link #TYPE_MULTI_SELECT}. * @param choiceEntries the list of user-visible choices. * @see #setChoiceValues(String[]) */
public void setChoiceEntries(String[] choiceEntries) { mChoiceEntries = choiceEntries; }
Sets a list of strings that will be presented as choices to the user. This is similar to setChoiceEntries(String[]).
Params:
  • context – the application context, used for retrieving the resources.
  • stringArrayResId – the resource id of a string array containing the possible entries.
/** Sets a list of strings that will be presented as choices to the user. This is similar to * {@link #setChoiceEntries(String[])}. * @param context the application context, used for retrieving the resources. * @param stringArrayResId the resource id of a string array containing the possible entries. */
public void setChoiceEntries(Context context, @ArrayRes int stringArrayResId) { mChoiceEntries = context.getResources().getStringArray(stringArrayResId); }
Returns the list of strings, set earlier, that will be presented as choices to the user.
Returns:the list of choices presented to the user.
/** * Returns the list of strings, set earlier, that will be presented as choices to the user. * @return the list of choices presented to the user. */
public String[] getChoiceEntries() { return mChoiceEntries; }
Returns the provided user-visible description of the entry, if any.
Returns:the user-visible description, null if none was set earlier.
/** * Returns the provided user-visible description of the entry, if any. * @return the user-visible description, null if none was set earlier. */
public String getDescription() { return mDescription; }
Sets the user-visible description of the entry, as a possible sub-text for the title. You can use this to describe the entry in more detail or to display the current state of the restriction.
Params:
  • description – the user-visible description string.
/** * Sets the user-visible description of the entry, as a possible sub-text for the title. * You can use this to describe the entry in more detail or to display the current state of * the restriction. * @param description the user-visible description string. */
public void setDescription(String description) { this.mDescription = description; }
This is the unique key for the restriction entry.
Returns:the key for the restriction.
/** * This is the unique key for the restriction entry. * @return the key for the restriction. */
public String getKey() { return mKey; }
Returns the user-visible title for the entry, if any.
Returns:the user-visible title for the entry, null if none was set earlier.
/** * Returns the user-visible title for the entry, if any. * @return the user-visible title for the entry, null if none was set earlier. */
public String getTitle() { return mTitle; }
Sets the user-visible title for the entry.
Params:
  • title – the user-visible title for the entry.
/** * Sets the user-visible title for the entry. * @param title the user-visible title for the entry. */
public void setTitle(String title) { this.mTitle = title; } @Override public boolean equals(Object o) { if (o == this) return true; if (!(o instanceof RestrictionEntry)) return false; final RestrictionEntry other = (RestrictionEntry) o; if (mType != other.mType || !mKey.equals(other.mKey)) { return false; } if (mCurrentValues == null && other.mCurrentValues == null && mRestrictions == null && other.mRestrictions == null && Objects.equals(mCurrentValue, other.mCurrentValue)) { return true; } if (mCurrentValue == null && other.mCurrentValue == null && mRestrictions == null && other.mRestrictions == null && Arrays.equals(mCurrentValues, other.mCurrentValues)) { return true; } if (mCurrentValue == null && other.mCurrentValue == null && mCurrentValue == null && other.mCurrentValue == null && Arrays.equals(mRestrictions, other.mRestrictions)) { return true; } return false; } @Override public int hashCode() { int result = 17; result = 31 * result + mKey.hashCode(); if (mCurrentValue != null) { result = 31 * result + mCurrentValue.hashCode(); } else if (mCurrentValues != null) { for (String value : mCurrentValues) { if (value != null) { result = 31 * result + value.hashCode(); } } } else if (mRestrictions != null) { result = 31 * result + Arrays.hashCode(mRestrictions); } return result; } public RestrictionEntry(Parcel in) { mType = in.readInt(); mKey = in.readString(); mTitle = in.readString(); mDescription = in.readString(); mChoiceEntries = in.readStringArray(); mChoiceValues = in.readStringArray(); mCurrentValue = in.readString(); mCurrentValues = in.readStringArray(); Parcelable[] parcelables = in.readParcelableArray(null); if (parcelables != null) { mRestrictions = new RestrictionEntry[parcelables.length]; for (int i = 0; i < parcelables.length; i++) { mRestrictions[i] = (RestrictionEntry) parcelables[i]; } } } @Override public int describeContents() { return 0; } @Override public void writeToParcel(Parcel dest, int flags) { dest.writeInt(mType); dest.writeString(mKey); dest.writeString(mTitle); dest.writeString(mDescription); dest.writeStringArray(mChoiceEntries); dest.writeStringArray(mChoiceValues); dest.writeString(mCurrentValue); dest.writeStringArray(mCurrentValues); dest.writeParcelableArray(mRestrictions, 0); } public static final Creator<RestrictionEntry> CREATOR = new Creator<RestrictionEntry>() { public RestrictionEntry createFromParcel(Parcel source) { return new RestrictionEntry(source); } public RestrictionEntry[] newArray(int size) { return new RestrictionEntry[size]; } }; @Override public String toString() { return "RestrictionEntry{" + "mType=" + mType + ", mKey='" + mKey + '\'' + ", mTitle='" + mTitle + '\'' + ", mDescription='" + mDescription + '\'' + ", mChoiceEntries=" + Arrays.toString(mChoiceEntries) + ", mChoiceValues=" + Arrays.toString(mChoiceValues) + ", mCurrentValue='" + mCurrentValue + '\'' + ", mCurrentValues=" + Arrays.toString(mCurrentValues) + ", mRestrictions=" + Arrays.toString(mRestrictions) + '}'; } }