diff --git a/core/api/current.txt b/core/api/current.txt index e2f388a99ab34..dabb27d1a6e4a 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -17723,9 +17723,7 @@ package android.hardware.biometrics { public class BiometricManager { method @Deprecated @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public int canAuthenticate(); method @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public int canAuthenticate(int); - method @Nullable @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public CharSequence getButtonLabel(int); - method @Nullable @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public CharSequence getPromptMessage(int); - method @Nullable @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public CharSequence getSettingName(int); + method @NonNull @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public android.hardware.biometrics.BiometricManager.Strings getStrings(int); field public static final int BIOMETRIC_ERROR_HW_UNAVAILABLE = 1; // 0x1 field public static final int BIOMETRIC_ERROR_NONE_ENROLLED = 11; // 0xb field public static final int BIOMETRIC_ERROR_NO_HARDWARE = 12; // 0xc @@ -17739,6 +17737,12 @@ package android.hardware.biometrics { field public static final int DEVICE_CREDENTIAL = 32768; // 0x8000 } + public static class BiometricManager.Strings { + method @Nullable @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public CharSequence getButtonLabel(); + method @Nullable @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public CharSequence getPromptMessage(); + method @Nullable @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public CharSequence getSettingName(); + } + public class BiometricPrompt { method @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public void authenticate(@NonNull android.hardware.biometrics.BiometricPrompt.CryptoObject, @NonNull android.os.CancellationSignal, @NonNull java.util.concurrent.Executor, @NonNull android.hardware.biometrics.BiometricPrompt.AuthenticationCallback); method @RequiresPermission(android.Manifest.permission.USE_BIOMETRIC) public void authenticate(@NonNull android.os.CancellationSignal, @NonNull java.util.concurrent.Executor, @NonNull android.hardware.biometrics.BiometricPrompt.AuthenticationCallback); diff --git a/core/java/android/hardware/biometrics/BiometricManager.java b/core/java/android/hardware/biometrics/BiometricManager.java index 304b2afc1adbc..0dbd9e4c83aca 100644 --- a/core/java/android/hardware/biometrics/BiometricManager.java +++ b/core/java/android/hardware/biometrics/BiometricManager.java @@ -188,6 +188,140 @@ public class BiometricManager { int DEVICE_CREDENTIAL = 1 << 15; } + /** + * Provides localized strings for an application that uses {@link BiometricPrompt} to + * authenticate the user. + */ + public static class Strings { + @NonNull private final Context mContext; + @NonNull private final IAuthService mService; + @Authenticators.Types int mAuthenticators; + + @Nullable CharSequence mButtonLabel; + @Nullable CharSequence mPromptMessage; + @Nullable CharSequence mSettingName; + + private Strings(@NonNull Context context, @NonNull IAuthService service, + @Authenticators.Types int authenticators) { + mContext = context; + mService = service; + mAuthenticators = authenticators; + } + + /** + * Provides a localized string that can be used as the label for a button that invokes + * {@link BiometricPrompt}. + * + *

When possible, this method should use the given authenticator requirements to more + * precisely specify the authentication type that will be used. For example, if + * Class 3 biometric authentication is requested on a device with a + * Class 3 fingerprint sensor and a Class 2 face sensor, + * the returned string should indicate that fingerprint authentication will be used. + * + *

This method should also try to specify which authentication method(s) will be used in + * practice when multiple authenticators meet the given requirements. For example, if + * biometric authentication is requested on a device with both face and fingerprint sensors + * but the user has selected face as their preferred method, the returned string should + * indicate that face authentication will be used. + * + *

This method may return {@code null} if none of the requested authenticator types are + * available, but this should not be relied upon for checking the status of + * authenticators. Instead, use {@link #canAuthenticate(int)}. + * + * @return The label for a button that invokes {@link BiometricPrompt} for authentication. + */ + @RequiresPermission(USE_BIOMETRIC) + @Nullable + public CharSequence getButtonLabel() { + if (mButtonLabel == null) { + final int userId = mContext.getUserId(); + final String opPackageName = mContext.getOpPackageName(); + try { + mButtonLabel = mService.getButtonLabel(userId, opPackageName, mAuthenticators); + } catch (RemoteException e) { + throw e.rethrowFromSystemServer(); + } + } + return mButtonLabel; + } + + /** + * Provides a localized string that can be shown while the user is authenticating with + * {@link BiometricPrompt}. + * + *

When possible, this method should use the given authenticator requirements to more + * precisely specify the authentication type that will be used. For example, if + * Class 3 biometric authentication is requested on a device with a + * Class 3 fingerprint sensor and a Class 2 face sensor, + * the returned string should indicate that fingerprint authentication will be used. + * + *

This method should also try to specify which authentication method(s) will be used in + * practice when multiple authenticators meet the given requirements. For example, if + * biometric authentication is requested on a device with both face and fingerprint sensors + * but the user has selected face as their preferred method, the returned string should + * indicate that face authentication will be used. + * + *

This method may return {@code null} if none of the requested authenticator types are + * available, but this should not be relied upon for checking the status of + * authenticators. Instead, use {@link #canAuthenticate(int)}. + * + * @return The label for a button that invokes {@link BiometricPrompt} for authentication. + */ + @RequiresPermission(USE_BIOMETRIC) + @Nullable + public CharSequence getPromptMessage() { + if (mPromptMessage == null) { + final int userId = mContext.getUserId(); + final String opPackageName = mContext.getOpPackageName(); + try { + return mService.getPromptMessage(userId, opPackageName, mAuthenticators); + } catch (RemoteException e) { + throw e.rethrowFromSystemServer(); + } + } + return mPromptMessage; + } + + /** + * Provides a localized string that can be shown as the title for an app setting that + * enables authentication with {@link BiometricPrompt}. + * + *

When possible, this method should use the given authenticator requirements to more + * precisely specify the authentication type that will be used. For example, if + * Class 3 biometric authentication is requested on a device with a + * Class 3 fingerprint sensor and a Class 2 face sensor, + * the returned string should indicate that fingerprint authentication will be used. + * + *

This method should not try to specify which authentication method(s) will be + * used in practice when multiple authenticators meet the given requirements. For example, + * if biometric authentication is requested on a device with both face and fingerprint + * sensors, the returned string should indicate that either face or fingerprint + * authentication may be used, regardless of whether the user has enrolled or selected + * either as their preferred method. + * + *

This method may return {@code null} if none of the requested authenticator types are + * supported by the system, but this should not be relied upon for checking the + * status of authenticators. Instead, use {@link #canAuthenticate(int)} or + * {@link android.content.pm.PackageManager#hasSystemFeature(String)}. + * + * @return The label for a button that invokes {@link BiometricPrompt} for authentication. + */ + @RequiresPermission(USE_BIOMETRIC) + @Nullable + public CharSequence getSettingName() { + if (mSettingName == null) { + final int userId = mContext.getUserId(); + final String opPackageName = mContext.getOpPackageName(); + try { + return mService.getSettingName(userId, opPackageName, mAuthenticators); + } catch (RemoteException e) { + throw e.rethrowFromSystemServer(); + } + } + return mSettingName; + } + } + @NonNull private final Context mContext; @NonNull private final IAuthService mService; @@ -326,6 +460,20 @@ public class BiometricManager { } } + /** + * Produces an instance of the {@link Strings} class, which provides localized strings for an + * application, given a set of allowed authenticator types. + * + * @param authenticators A bit field representing the types of {@link Authenticators} that may + * be used for authentication. + * @return A {@link Strings} collection for the given allowed authenticator types. + */ + @RequiresPermission(USE_BIOMETRIC) + @NonNull + public Strings getStrings(@Authenticators.Types int authenticators) { + return new Strings(mContext, mService, authenticators); + } + /** * @hide * @param userId @@ -432,116 +580,5 @@ public class BiometricManager { } } } - - /** - * Provides a localized string that may be used as the label for a button that invokes - * {@link BiometricPrompt}. - * - *

When possible, this method should use the given authenticator requirements to more - * precisely specify the authentication type that will be used. For example, if - * Class 3 biometric authentication is requested on a device with a - * Class 3 fingerprint sensor and a Class 2 face sensor, the - * returned string should indicate that fingerprint authentication will be used. - * - *

This method should also try to specify which authentication method(s) will be used in - * practice when multiple authenticators meet the given requirements. For example, if biometric - * authentication is requested on a device with both face and fingerprint sensors but the user - * has selected face as their preferred method, the returned string should indicate that face - * authentication will be used. - * - * @param authenticators A bit field representing the types of {@link Authenticators} that may - * be used for authentication. - * @return The label for a button that invokes {@link BiometricPrompt} for authentication. - */ - @RequiresPermission(USE_BIOMETRIC) - @Nullable - public CharSequence getButtonLabel(@Authenticators.Types int authenticators) { - if (mService != null) { - final int userId = mContext.getUserId(); - final String opPackageName = mContext.getOpPackageName(); - try { - return mService.getButtonLabel(userId, opPackageName, authenticators); - } catch (RemoteException e) { - throw e.rethrowFromSystemServer(); - } - } else { - Slog.w(TAG, "getButtonLabel(): Service not connected"); - return null; - } - } - - /** - * Provides a localized string that may be shown while the user is authenticating with - * {@link BiometricPrompt}. - * - *

When possible, this method should use the given authenticator requirements to more - * precisely specify the authentication type that will be used. For example, if - * Class 3 biometric authentication is requested on a device with a - * Class 3 fingerprint sensor and a Class 2 face sensor, the - * returned string should indicate that fingerprint authentication will be used. - * - *

This method should also try to specify which authentication method(s) will be used in - * practice when multiple authenticators meet the given requirements. For example, if biometric - * authentication is requested on a device with both face and fingerprint sensors but the user - * has selected face as their preferred method, the returned string should indicate that face - * authentication will be used. - * - * @param authenticators A bit field representing the types of {@link Authenticators} that may - * be used for authentication. - * @return The label for a button that invokes {@link BiometricPrompt} for authentication. - */ - @RequiresPermission(USE_BIOMETRIC) - @Nullable - public CharSequence getPromptMessage(@Authenticators.Types int authenticators) { - if (mService != null) { - final int userId = mContext.getUserId(); - final String opPackageName = mContext.getOpPackageName(); - try { - return mService.getPromptMessage(userId, opPackageName, authenticators); - } catch (RemoteException e) { - throw e.rethrowFromSystemServer(); - } - } else { - Slog.w(TAG, "getPromptMessage(): Service not connected"); - return null; - } - } - - /** - * Provides a localized string that may be shown as the title for an app setting that enables - * biometric authentication. - * - *

When possible, this method should use the given authenticator requirements to more - * precisely specify the authentication type that will be used. For example, if - * Class 3 biometric authentication is requested on a device with a - * Class 3 fingerprint sensor and a Class 2 face sensor, the - * returned string should indicate that fingerprint authentication will be used. - * - *

This method should not try to specify which authentication method(s) will be used - * in practice when multiple authenticators meet the given requirements. For example, if - * biometric authentication is requested on a device with both face and fingerprint sensors, the - * returned string should indicate that either face or fingerprint authentication may be used, - * regardless of whether the user has enrolled or selected either as their preferred method. - * - * @param authenticators A bit field representing the types of {@link Authenticators} that may - * be used for authentication. - * @return The label for a button that invokes {@link BiometricPrompt} for authentication. - */ - @RequiresPermission(USE_BIOMETRIC) - @Nullable - public CharSequence getSettingName(@Authenticators.Types int authenticators) { - if (mService != null) { - final int userId = mContext.getUserId(); - final String opPackageName = mContext.getOpPackageName(); - try { - return mService.getSettingName(userId, opPackageName, authenticators); - } catch (RemoteException e) { - throw e.rethrowFromSystemServer(); - } - } else { - Slog.w(TAG, "getSettingName(): Service not connected"); - return null; - } - } }