content: /*
   * Copyright (C) 2018 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.hardware.biometrics;
  
  import android.annotation.CallbackExecutor;
  import android.annotation.NonNull;
  import android.os.CancellationSignal;
  import android.os.Parcelable;
  
  import java.util.concurrent.Executor;
  
  /**
   * This is the common interface that all biometric authentication classes should implement.
   * @hide
   */
  public interface BiometricAuthenticator {
  
      /**
       * No biometric methods or nothing has been enrolled.
       * Move/expose these in BiometricPrompt if we ever want to allow applications to "blacklist"
       * modalities when calling authenticate().
       * @hide
       */
      int TYPE_NONE = 0;
      /**
       * Constant representing fingerprint.
       * @hide
       */
      int TYPE_FINGERPRINT = 1 << 0;
  
      /**
       * Constant representing iris.
       * @hide
       */
      int TYPE_IRIS = 1 << 1;
  
      /**
       * Constant representing face.
       * @hide
       */
      int TYPE_FACE = 1 << 2;
  
      /**
       * Container for biometric data
       * @hide
       */
      abstract class Identifier implements Parcelable {
          private CharSequence mName;
          private int mBiometricId;
          private long mDeviceId; // physical device this is associated with
  
          public Identifier() {}
  
          public Identifier(CharSequence name, int biometricId, long deviceId) {
              mName = name;
              mBiometricId = biometricId;
              mDeviceId = deviceId;
          }
  
          /**
           * Gets the human-readable name for the given biometric.
           * @return name given to the biometric
           */
          public CharSequence getName() {
              return mName;
          }
  
          /**
           * Gets the device-specific biometric id.  Used by Settings to map a name to a specific
           * biometric template.
           */
          public int getBiometricId() {
              return mBiometricId;
          }
  
          /**
           * Device this biometric belongs to.
           */
          public long getDeviceId() {
              return mDeviceId;
          }
  
          public void setName(CharSequence name) {
              mName = name;
          }
  
          public void setDeviceId(long deviceId) {
              mDeviceId = deviceId;
          }
      }
  
      /**
       * Container for callback data from {@link BiometricAuthenticator#authenticate(
       * CancellationSignal, Executor, AuthenticationCallback)} and
       * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
       * AuthenticationCallback)}
       */
      class AuthenticationResult {
          private Identifier mIdentifier;
          private CryptoObject mCryptoObject;
          private int mUserId;
  
          /**
           * @hide
           */
          public AuthenticationResult() { }
  
          /**
           * Authentication result
           * @param crypto
           * @param identifier
           * @param userId
           * @hide
           */
          public AuthenticationResult(CryptoObject crypto, Identifier identifier,
                  int userId) {
              mCryptoObject = crypto;
              mIdentifier = identifier;
              mUserId = userId;
          }
  
          /**
           * Obtain the crypto object associated with this transaction
           * @return crypto object provided to {@link BiometricAuthenticator#authenticate(
           * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}
           */
          public CryptoObject getCryptoObject() {
              return mCryptoObject;
          }
  
          /**
           * Obtain the biometric identifier associated with this operation. Applications are strongly
           * discouraged from associating specific identifiers with specific applications or
           * operations.
           * @hide
           */
          public Identifier getId() {
              return mIdentifier;
          }
  
          /**
           * Obtain the userId for which this biometric was authenticated.
           * @hide
           */
          public int getUserId() {
              return mUserId;
          }
      };
  
      /**
       * Callback structure provided to {@link BiometricAuthenticator#authenticate(CancellationSignal,
       * Executor, AuthenticationCallback)} or {@link BiometricAuthenticator#authenticate(
       * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}. Users must provide
       * an implementation of this for listening to biometric events.
       */
      abstract class AuthenticationCallback {
          /**
           * Called when an unrecoverable error has been encountered and the operation is complete.
           * No further actions will be made on this object.
           * @param errorCode An integer identifying the error message
           * @param errString A human-readable error string that can be shown on an UI
           */
          public void onAuthenticationError(int errorCode, CharSequence errString) {}
  
          /**
           * Called when a recoverable error has been encountered during authentication. The help
           * string is provided to give the user guidance for what went wrong, such as "Sensor dirty,
           * please clean it."
           * @param helpCode An integer identifying the error message
           * @param helpString A human-readable string that can be shown on an UI
           */
          public void onAuthenticationHelp(int helpCode, CharSequence helpString) {}
  
          /**
           * Called when a biometric is valid but not recognized.
           */
          public void onAuthenticationFailed() {}
  
          /**
           * Called when a biometric has been acquired, but hasn't been processed yet.
           * @hide
           */
          public void onAuthenticationAcquired(int acquireInfo) {}
      };
  
      /**
       * @return true if the biometric hardware is detected.
       */
      default boolean isHardwareDetected() {
          throw new UnsupportedOperationException("Stub!");
      }
  
      /**
       * @return true if the user has enrolled templates for this biometric.
       */
      default boolean hasEnrolledTemplates() {
          throw new UnsupportedOperationException("Stub!");
      }
  
      /**
       * @return true if the user has enrolled templates for this biometric.
       */
      default boolean hasEnrolledTemplates(int userId) {
          throw new UnsupportedOperationException("Stub!");
      }
  
      /**
       * Sets the active user. This is meant to be used to select the current profile
       * to allow separate templates for work profile.
       */
      default void setActiveUser(int userId) {
          throw new UnsupportedOperationException("Stub!");
      }
  
      /**
       * This call warms up the hardware and starts scanning for valid biometrics. It terminates
       * when {@link AuthenticationCallback#onAuthenticationError(int,
       * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
       * AuthenticationResult)} is called, at which point the crypto object becomes invalid. This
       * operation can be canceled by using the provided cancel object. The application wil receive
       * authentication errors through {@link AuthenticationCallback}. Calling
       * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
       * AuthenticationCallback)} while an existing authentication attempt is occurring will stop
       * the previous client and start a new authentication. The interrupted client will receive a
       * cancelled notification through {@link AuthenticationCallback#onAuthenticationError(int,
       * CharSequence)}.
       *
       * @throws IllegalArgumentException If any of the arguments are null
       *
       * @param crypto Object associated with the call
       * @param cancel An object that can be used to cancel authentication
       * @param executor An executor to handle callback events
       * @param callback An object to receive authentication events
       */
      default void authenticate(@NonNull CryptoObject crypto,
              @NonNull CancellationSignal cancel,
              @NonNull @CallbackExecutor Executor executor,
              @NonNull AuthenticationCallback callback) {
          throw new UnsupportedOperationException("Stub!");
      }
  
      /**
       * This call warms up the hardware and starts scanning for valid biometrics. It terminates
       * when {@link AuthenticationCallback#onAuthenticationError(int,
       * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
       * AuthenticationResult)} is called. This operation can be canceled by using the provided cancel
       * object. The application wil receive authentication errors through
       * {@link AuthenticationCallback}. Calling {@link BiometricAuthenticator#authenticate(
       * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)} while an existing
       * authentication attempt is occurring will stop the previous client and start a new
       * authentication. The interrupted client will receive a cancelled notification through
       * {@link AuthenticationCallback#onAuthenticationError(int, CharSequence)}.
       *
       * @throws IllegalArgumentException If any of the arguments are null
       *
       * @param cancel An object that can be used to cancel authentication
       * @param executor An executor to handle callback events
       * @param callback An object to receive authentication events
       */
      default void authenticate(@NonNull CancellationSignal cancel,
              @NonNull @CallbackExecutor Executor executor,
              @NonNull AuthenticationCallback callback) {
          throw new UnsupportedOperationException("Stub!");
      }
  }
  