/*
 * Copyright (C) 2017 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.fingerprint@2.1;

import IBiometricsFingerprintClientCallback;

interface IBiometricsFingerprint {
  /**
   * Set notification callback:
   * Registers a user function that must receive notifications from the HAL
   * This call must block if the HAL state machine is in busy state until HAL
   * leaves the busy state.
   *
   * @return deviceId is a unique handle for this fingerprint device
   */
  @callflow(next={"setActiveGroup"})
  @entry
  setNotify(IBiometricsFingerprintClientCallback clientCallback)
      generates (uint64_t deviceId);

  /**
   * Fingerprint pre-enroll enroll request:
   * Generates a unique token to upper layers to indicate the start of
   * an enrollment transaction. pre-enroll and post-enroll specify
   * a pin/password cleared time window where enrollment is allowed.
   * Pre-enroll only generates a challenge, a full hardwareAuthToken is
   * generated by trustzone after verifying a pin/password/swipe. This is to
   * ensure adding a new fingerprint template was preceded by some kind of
   * credential confirmation (e.g. device password).
   *
   * @return 0 if function failed, a uint64_t of challenge otherwise.
   */
  @callflow(next={"enroll", "postEnroll"})
  preEnroll() generates (uint64_t authChallenge);

  /**
   * Fingerprint enroll request:
   * Switches the HAL state machine to collect and store a new fingerprint
   * template. Switches back as soon as enroll is complete, signalled by
   * (fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
   *  fingerprintMsg.data.enroll.samplesRemaining == 0)
   * or after timeoutSec seconds.
   * The fingerprint template must be assigned to the group gid.
   *
   * @param hat a valid Hardware Authentication Token (HAT), generated
   * as a result of a preEnroll() call.
   * @param gid a framework defined fingerprint set (group) id.
   * @param timeoutSec a timeout in seconds.
   *
   * @return debugErrno is a value the framework logs in case it is not 0.
   *
   * A notify() function may be called with a more detailed error structure.
   */
  @callflow(next={"cancel", "enroll", "postEnroll", "remove"})
  enroll(uint8_t[69] hat, uint32_t gid, uint32_t timeoutSec)
      generates (RequestStatus debugErrno);

  /**
   * Finishes the enroll operation and invalidates the preEnroll() generated
   * challenge. This must be called at the end of a multi-finger enrollment
   * session to indicate that no more fingers may be added.
   *
   * @return debugErrno is a value the framework logs in case it is not 0.
   */
  @callflow(next={"authenticate", "setActiveGroup", "enumerate", "remove"})
  postEnroll() generates (RequestStatus debugErrno);

  /**
   * getAuthenticatorId:
   * Returns a token associated with the current fingerprint set. This value
   * must change whenever a new fingerprint is enrolled, thus creating a new
   * fingerprint set.
   *
   * @return getAuthenticatorIdRet current authenticator id, 0 if function
   * failed.
   */
  @callflow(next={"authenticate"})
  getAuthenticatorId() generates (uint64_t AuthenticatorId);

  /**
   * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED
   * to all running clients. Switches the HAL state machine back to the idle
   * state. Unlike enrollDone() doesn't invalidate the preEnroll() challenge.
   *
   * @return debugErrno is a value the framework logs in case it is not 0.
   */
  @callflow(next={"authenticate", "enroll", "enumerate", "remove",
    "setActiveGroup"})
  cancel() generates (RequestStatus debugErrno);

  /**
   * Enumerate all the fingerprint templates found in the directory set by
   * setActiveGroup():
   * For each template found a notify() must be called with:
   * fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENUMERATED
   * fingerprintMsg.data.enumerated.finger indicating a template id
   * fingerprintMsg.data.enumerated.remainingTemplates indicating how many more
   * enumeration messages to expect.
   *
   * @return debugErrno is a value the framework logs in case it is not 0.
   */
  @callflow(next={"remove", "enroll", "authenticate", "setActiveGroup"})
  enumerate() generates (RequestStatus debugErrno);

  /**
   * Fingerprint remove request:
   * Deletes fingerprint template(s).
   * Works only within the path set by setActiveGroup().
   * For each template found a notify() must be called with:
   * fingerprintMsg.type == FINGERPRINT_TEMPLATE_REMOVED
   * fingerprintMsg.data.removed.finger indicating the template id deleted
   * fingerprintMsg.data.removed.remainingTemplates indicating how many more
   * templates must be deleted by this operation.
   *
   * @param gid group id must match the last group set by setActiveGroup().
   * @param fid template id to delete or 0 to delete all templates within the
   * current group.
   *
   * @return debugErrno is a value the framework logs in case it is not 0.
   */
  @callflow(next={"enumerate", "authenticate", "cancel", "getAuthenticatorId",
    "setActiveGroup"})
  remove(uint32_t gid, uint32_t fid) generates (RequestStatus debugErrno);

  /**
   * Restricts the HAL operation to a set of fingerprints belonging to a group
   * provided. The caller must provide a path to a storage location within the
   * user's data directory.
   *
   * @param gid the fingerprint group (set) id.
   * @param storePath filesystem path to the template storage directory.
   *
   * @return debugErrno is a value the framework logs in case it is not 0.
   */
  @callflow(next={"authenticate", "preEnroll", "enumerate", "remove"})
  setActiveGroup(uint32_t gid, string storePath)
      generates (RequestStatus debugErrno);

  /**
   * Authenticates an operation identified by operationId
   *
   * @param operationId operation id.
   * @param gid fingerprint group id.
   *
   * @return debugErrno is a value the framework logs in case it is not 0.
   */
  @callflow(next={"cancel", "preEnroll", "remove"})
  authenticate(uint64_t operationId, uint32_t gid)
      generates (RequestStatus debugErrno);
};