Docs: Javadoc comment fixups for secure passcode reset methods.
Exceptions corrected for methods and cross references linked up.
Clarification about resetPassword() and work profiles.
Staged at: go/dac-stage/reference/android/app/admin/DevicePolicyManager.html
Test: make ds-docs with output staged and visually checked in DevicePolicyManager page
Bug: 38026339
Change-Id: I3346144193061fad7988c92e0d4be4b341ef7410
diff --git a/core/java/android/app/admin/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java
index d8da8c5..32a64b0 100644
--- a/core/java/android/app/admin/DevicePolicyManager.java
+++ b/core/java/android/app/admin/DevicePolicyManager.java
@@ -2707,13 +2707,14 @@
}
/**
- * Flag for {@link #resetPassword}: don't allow other admins to change
- * the password again until the user has entered it.
+ * Flag for {@link #resetPasswordWithToken} and {@link #resetPassword}: don't allow other admins
+ * to change the password again until the user has entered it.
*/
public static final int RESET_PASSWORD_REQUIRE_ENTRY = 0x0001;
/**
- * Flag for {@link #resetPassword}: don't ask for user credentials on device boot.
+ * Flag for {@link #resetPasswordWithToken} and {@link #resetPassword}: don't ask for user
+ * credentials on device boot.
* If the flag is set, the device can be booted without asking for user password.
* The absence of this flag does not change the current boot requirements. This flag
* can be set by the device owner only. If the app is not the device owner, the flag
@@ -2723,8 +2724,8 @@
public static final int RESET_PASSWORD_DO_NOT_ASK_CREDENTIALS_ON_BOOT = 0x0002;
/**
- * Force a new device unlock password (the password needed to access the entire device, not for
- * individual accounts) on the user. This takes effect immediately.
+ * Force a new password for device unlock (the password needed to access the entire device) or
+ * the work profile challenge on the current user. This takes effect immediately.
* <p>
* <em>For device owner and profile owners targeting SDK level
* {@link android.os.Build.VERSION_CODES#O} or above, this API is no longer available and will
@@ -2762,7 +2763,6 @@
* @throws SecurityException if the calling application does not own an active administrator
* that uses {@link DeviceAdminInfo#USES_POLICY_RESET_PASSWORD}
* @throws IllegalStateException if the calling user is locked or has a managed profile.
- * @throws IllegalArgumentException if the password does not meet system requirements.
*/
public boolean resetPassword(String password, int flags) {
throwIfParentInstance("resetPassword");
@@ -2804,8 +2804,8 @@
* @param token a secure token a least 32-byte long, which must be generated by a
* cryptographically strong random number generator.
* @return true if the operation is successful, false otherwise.
+ * @throws SecurityException if admin is not a device or profile owner.
* @throws IllegalArgumentException if the supplied token is invalid.
- * @throws SecurityException
*/
public boolean setResetPasswordToken(ComponentName admin, byte[] token) {
throwIfParentInstance("setResetPasswordToken");
@@ -2824,6 +2824,7 @@
*
* @param admin Which {@link DeviceAdminReceiver} this request is associated with.
* @return true if the operation is successful, false otherwise.
+ * @throws SecurityException if admin is not a device or profile owner.
*/
public boolean clearResetPasswordToken(ComponentName admin) {
throwIfParentInstance("clearResetPasswordToken");
@@ -2842,6 +2843,7 @@
*
* @param admin Which {@link DeviceAdminReceiver} this request is associated with.
* @return true if the token is active, false otherwise.
+ * @throws SecurityException if admin is not a device or profile owner.
* @throws IllegalStateException if no token has been set.
*/
public boolean isResetPasswordTokenActive(ComponentName admin) {
@@ -2867,24 +2869,23 @@
* The given password must be sufficient for the current password quality and length constraints
* as returned by {@link #getPasswordQuality(ComponentName)} and
* {@link #getPasswordMinimumLength(ComponentName)}; if it does not meet these constraints, then
- * it will be rejected and false returned. Note that the password may be a stronger quality
- * (containing alphanumeric characters when the requested quality is only numeric), in which
- * case the currently active quality will be increased to match.
+ * it will be rejected and false returned. Note that the password may be a stronger quality, for
+ * example, a password containing alphanumeric characters when the requested quality is only
+ * numeric.
* <p>
- * Calling with a null or empty password will clear any existing PIN, pattern or password if the
- * current password constraints allow it.
+ * Calling with a {@code null} or empty password will clear any existing PIN, pattern or
+ * password if the current password constraints allow it.
*
* @param admin Which {@link DeviceAdminReceiver} this request is associated with.
- * @param password The new password for the user. Null or empty clears the password.
- * @param token the password reset token previously provisioned by #setResetPasswordToken.
+ * @param password The new password for the user. {@code null} or empty clears the password.
+ * @param token the password reset token previously provisioned by
+ * {@link #setResetPasswordToken}.
* @param flags May be 0 or combination of {@link #RESET_PASSWORD_REQUIRE_ENTRY} and
- * {@link #RESET_PASSWORD_DO_NOT_ASK_CREDENTIALS_ON_BOOT}.
+ * {@link #RESET_PASSWORD_DO_NOT_ASK_CREDENTIALS_ON_BOOT}.
* @return Returns true if the password was applied, or false if it is not acceptable for the
* current constraints.
- * @throws SecurityException if the calling application does not own an active administrator
- * that uses {@link DeviceAdminInfo#USES_POLICY_RESET_PASSWORD}
+ * @throws SecurityException if admin is not a device or profile owner.
* @throws IllegalStateException if the provided token is not valid.
- * @throws IllegalArgumentException if the password does not meet system requirements.
*/
public boolean resetPasswordWithToken(@NonNull ComponentName admin, String password,
byte[] token, int flags) {