Finish remainder of documentation.
Note that this doesn't mean documentation is done, it just means that
previously undocumented areas now at least have some documentation.
Bug: 168843220
Test: Builds
Change-Id: I92db9b228d46b3925d3f7ae56698f7c52a0ae1bf
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
index 8cb7833..a3259f6 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
@@ -19,13 +19,49 @@
@VintfStability
@Backing(type="byte")
enum AcquiredInfo {
+ /**
+ * A high quality fingerprint image was detected, no further user interaction is necessary.
+ */
GOOD,
+
+ /**
+ * Not enough of a fingerprint was detected. Reposition the finger, or a longer swipe needed.
+ */
PARTIAL,
+
+ /**
+ * Image doesn't contain enough detail for recognition.
+ */
INSUFFICIENT,
+
+ /**
+ * The sensor needs to be cleaned.
+ */
SENSOR_DIRTY,
+
+ /**
+ * For swipe-type sensors, the swipe was too slow and not enough data was collected.
+ */
TOO_SLOW,
+
+ /**
+ * For swipe-type sensors, the swipe was too fast and not enough data was collected.
+ */
TOO_FAST,
+
+ /**
+ * This message represents the earliest message sent at the beginning of the authentication
+ * pipeline. It is expected to be used to measure latency. For example, in a camera-based
+ * authentication system it's expected to be sent prior to camera initialization. Note this
+ * should be sent whenever authentication is started or restarted. The framework may measure
+ * latency based on the time between the last START message and the onAuthenticated callback.
+ */
START,
+
+ /**
+ * Vendor-specific acquisition message. See ISessionCallback#onAcquired vendorCode
+ * documentation.
+ */
VENDOR
}
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
index 4b31a38..43cb20f 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
@@ -22,9 +22,9 @@
* Notifies the framework that the user has just entered the Error::LOCKOUT state. This must be
* sent in the following scenarios:
* 1) The user just attempted authentication and was rejected, resulting in a timed lockout.
- * 2) The framework just created a session for a sensorId/userId pair that has not been
+ * 2) The framework just created a session for a (sensorId, userId) pair that has not been
* created since the HAL started (e.g. there is no active or idle session for this
- * sensorId/userId pair.
+ * (sensorId, userId) pair.
*
* @param sensorId Sensor for which the user is locked out.
* @param userId User for which the sensor is locked out.
@@ -36,9 +36,9 @@
* Notifies the framework that the user has just entered the Error::LOCKOUT_PERMANENT state.
* This must be sent in the following scenarios:
* 1) The user just attempted authentication and was rejected, resulting in a permanent lockout.
- * 2) The framework just created a session for a sensorId/userId pair that has not been
+ * 2) The framework just created a session for a (sensorId, userId) pair that has not been
* created since the HAL started (e.g. there is no active or idle session for this
- * sensorId/userId pair.
+ * (sensorId, userId) pair.
*
* @param sensorId Sensor for which the user is locked out.
* @param userId User for which the sensor is locked out.
@@ -46,11 +46,13 @@
void onLockoutPermanent(in int sensorId, in int userId);
/**
- * Notifies the framework that lockout has been cleared for this sensorId/userId pair. This
+ * Notifies the framework that lockout has been cleared for this (sensorId, userId) pair. This
* can happen in the following scenarios:
* 1) A timed lockout has ended (e.g. original durationMillis specified in #onLockoutTimed
* has expired.
* 2) See ISession#resetLockout.
+ * 3) The (sensorId, userId) pair is not in any lockout state, and the user successfully
+ * authenticated with a fingerprint.
*
* @param sensorId Sensor for which the user's lockout is cleared.
* @param userId User for the sensor's lockout is cleared.
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
index 5fa56e0..946027b 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
@@ -80,7 +80,7 @@
*
* When a finger is successfully added and before the framework is notified
* of remaining=0, the implementation MUST update and associate this
- * (sensorId, user) pair with a new new entropy-encoded random identifier.
+ * (sensorId, userId) pair with a new new entropy-encoded random identifier.
* See ISession#getAuthenticatorId for more information.
*
* @param cookie An identifier used to track subsystem operations related
@@ -147,10 +147,75 @@
*/
ICancellationSignal authenticate(in int cookie, in long operationId);
+ /**
+ * detectInteraction:
+ *
+ * A request to start looking for fingerprints without performing matching.
+ *
+ * Once the HAL is able to start processing this request, it must notify the framework via
+ * ISessionCallback#onStateChanged with SessionState::DETECTING_INTERACTION.
+ *
+ * The framework will use this method in cases where determing user presence is required, but
+ * identifying/authentication is not. For example, when the device is encrypted (first boot) or
+ * in lockdown mode.
+ *
+ * At any point during detectInteraction, if a non-recoverable error occurs, the HAL must notify
+ * the framework via ISessionCallback#onError with the applicable error, and then send
+ * ISessionCallback#onStateChanged(cookie, SessionState::IDLING) if no subsequent operation is
+ * in the queue.
+ *
+ * The implementation must only check for a fingerprint-like image was detected (e.g. to
+ * minimize interactions due to non-fingerprint objects), and the lockout counter must not
+ * be modified.
+ *
+ * Upon detecting any fingerprint, the implementation must invoke
+ * ISessionCallback#onInteractionDetected.
+ *
+ * The lifecycle of this operation ends when either
+ * 1) Any fingerprint is detected and the framework is notified via
+ * ISessionCallback#onInteractiondetected
+ * 2) The operation was cancelled by the framework (see ICancellationSignal)
+ * 3) The HAL ends the operation, for example when a subsequent operation pre-empts this one.
+ *
+ * Note that if the operation is canceled, the implementation must notify the framework via
+ * ISessionCallback#onError with Error::CANCELED.
+ *
+ * @param cookie An identifier used to track subsystem operations related to this call path.
+ * The framework will guarantee that it is unique per ISession.
+ */
ICancellationSignal detectInteraction(in int cookie);
+ /*
+ * enumerateEnrollments:
+ *
+ * A request to enumerate (list) the enrollments for this (sensorId, userId) pair. The
+ * framework typically uses this to ensure that its cache is in sync with the HAL.
+ *
+ * Once the HAL is able to start processing this request, it must notify the framework via
+ * ISessionCallback#onStateChanged with SessionState::ENUMERATING_ENROLLMENTS.
+ *
+ * The implementation must then notify the framework with a list of enrollments applicable
+ * for the current session via ISessionCallback#onEnrollmentsEnumerated.
+ *
+ * @param cookie An identifier used to track subsystem operations related to this call path.
+ * The framework will guarantee that it is unique per ISession.
+ */
void enumerateEnrollments(in int cookie);
+ /**
+ * removeEnrollments:
+ *
+ * A request to remove the enrollments for this (sensorId, userId) pair.
+ *
+ * Once the HAL is able to start processing this request, it must notify the framework via
+ * ISessionCallback#onStateChanged with SessionState::REMOVING_ENROLLMENTS.
+ *
+ * After removing the enrollmentIds from everywhere necessary (filesystem, secure subsystems,
+ * etc), the implementation must notify the framework via ISessionCallback#onEnrollmentsRemoved.
+ *
+ * @param cookie An identifier used to track subsystem operations related to this call path.
+ * The framework will guarantee that it is unique per ISession.
+ */
void removeEnrollments(in int cookie, in int[] enrollmentIds);
/**
@@ -259,10 +324,54 @@
* Methods for notifying the under-display fingerprint sensor about external events.
*/
+ /**
+ * onPointerDown:
+ *
+ * This method only applies to sensors that are configured as
+ * FingerprintSensorType::UNDER_DISPLAY_*. If invoked erroneously by the framework for sensors
+ * of other types, the HAL must treat this as a no-op and return immediately.
+ *
+ * For sensors of type FingerprintSensorType::UNDER_DISPLAY_*, this method is used to notify the
+ * HAL of display touches. This method can be invoked when the session is in one of the
+ * following states: SessionState::ENROLLING, SessionState::AUTHENTICATING, or
+ * SessionState::DETECTING_INTERACTION.
+ *
+ * Note that the framework will only invoke this method if the event occurred on the display
+ * on which this sensor is located.
+ *
+ * Note that for sensors which require illumination such as
+ * FingerprintSensorType::UNDER_DISPLAY_OPTICAL, and where illumination is handled below
+ * the framework, this is a good time to start illuminating.
+ *
+ * @param pointerId See android.view.MotionEvent#getPointerId
+ * @param x The distance in pixels from the left edge of the display.
+ * @param y The distance in pixels from the top edge of the display.
+ * @param minor See android.view.MotionEvent#getTouchMinor
+ * @param major See android.view.MotionEvent#getTouchMajor
+ */
void onPointerDown(in int pointerId, in int x, in int y, in float minor, in float major);
+ /**
+ * onPointerUp:
+ *
+ * This method only applies to sensors that are configured as
+ * FingerprintSensorType::UNDER_DISPLAY_*. If invoked for sensors of other types, the HAL must
+ * treat this as a no-op and return immediately.
+ *
+ * @param pointerId See android.view.MotionEvent#getPointerId
+ */
void onPointerUp(in int pointerId);
+ /*
+ * onUiReady:
+ *
+ * This method only applies to sensors that are configured as
+ * FingerprintSensorType::UNDER_DISPLAY_OPTICAL. If invoked for sensors of other types, the HAL
+ * must treat this as a no-op and return immediately.
+ *
+ * For FingerprintSensorType::UNDER_DISPLAY_OPTICAL where illumination is handled above the
+ * HAL, the framework will invoke this method to notify that the illumination has started.
+ */
void onUiReady();
}
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
index 7130520..81a87a8 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
@@ -23,14 +23,48 @@
@VintfStability
interface ISessionCallback {
+ /**
+ * Used to notify the framework of session state changes. See ISession for more information.
+ */
void onStateChanged(in int cookie, in SessionState state);
+ /**
+ * This method must only be used to notify the framework during the following states:
+ * 1) SessionState::ENROLLING
+ * 2) SessionState::AUTHENTICATING
+ * 3) SessionState::DETECTING_INTERACTION
+ *
+ * These messages may be used to provide user guidance multiple times if necessary per
+ * operation.
+ *
+ * @param info See the AcquiredInfo enum.
+ * @param vendorCode Only valid if info == AcquiredInfo::VENDOR.
+ */
void onAcquired(in AcquiredInfo info, in int vendorCode);
+ /**
+ * This method must only be used to notify the framework during the following states:
+ * 1) SessionState::ENROLLING
+ * 2) SessionState::AUTHENTICATING
+ * 3) SessionState::DETECTING_INTERACTION
+ * 4) SessionState::INVALIDATING_AUTHENTICATOR_ID
+ * 5) SessionState::RESETTING_LOCKOUT
+ *
+ * These messages may be used to notify the framework or user that a non-recoverable error
+ * has occurred. The operation is finished, and the HAL must proceed with the next operation
+ * or return to SessionState::IDLING if the queue is empty.
+ *
+ * Note that cancellation (see common::ICancellationSignal) and preemption most be followed with
+ * an Error::CANCELED message.
+ *
+ * @param error See the Error enum.
+ * @param vendorCode Only valid if error == Error::VENDOR.
+ */
void onError(in Error error, in int vendorCode);
/**
- * Used to notify the framework of enrollment progress. Enrollment completes when remaining==0,
+ * This method must only be used to notify the framework during the following state:
+ * 1) SessionState::ENROLLING
*
* @param enrollmentId Unique stable identifier for the enrollment that's being added by this
* ISession#enroll invocation.
@@ -39,6 +73,8 @@
void onEnrollmentProgress(in int enrollmentId, int remaining);
/**
+ * This method must only be used to notify the framework during SessionState::AUTHENTICATING.
+ *
* Used to notify the framework upon successful authentication. Note that the authentication
* lifecycle ends when either 1) a fingerprint is accepted, or 2) an error such as
* Error::LOCKOUT occurred. The authentication lifecycle does NOT end when a fingerprint is
@@ -53,6 +89,8 @@
void onAuthenticationSucceeded(in int enrollmentId, in HardwareAuthToken hat);
/**
+ * This method must only be used to notify the framework during SessionState::AUTHENTICATING.
+ *
* Used to notify the framework upon rejected attempts. Note that the authentication
* lifecycle ends when either 1) a fingerprint is accepted, or 2) an error such as
* Error::LOCKOUT occurred. The authentication lifecycle does NOT end when a fingerprint is
@@ -60,19 +98,50 @@
*/
void onAuthenticationFailed();
+ /**
+ * This method must only be used to notify the framework during
+ * SessionState::DETECTING_INTERACTION
+ *
+ * Notifies the framework that user interaction occurred. See ISession#detectInteraction.
+ */
void onInteractionDetected();
+ /**
+ * This method must only be used to notify the framework during
+ * SessionState::ENUMERATING_ENROLLMENTS.
+ *
+ * Notifies the framework of the current enrollments. See ISession#enumerateEnrollments.
+ *
+ * @param enrollmentIds A list of enrollments for the session's (userId, sensorId) pair.
+ */
void onEnrollmentsEnumerated(in int[] enrollmentIds);
+ /**
+ * This method must only be used to notify the framework during
+ * SessionState::REMOVING_ENROLLMENTS.
+ *
+ * Notifies the framework that the specified enrollments are removed.
+ *
+ * @param enrollmentIds The enrollments that were removed.
+ */
void onEnrollmentsRemoved(in int[] enrollmentIds);
/**
- * A callback invoked when ISession#getAuthenticatorId is invoked.
+ * This method must only be used to notify the framework during
+ * SessionState::GETTING_AUTHENTICATOR_ID.
+ *
+ * Notifies the framework with the authenticatorId corresponding to this session's
+ * (userId, sensorId) pair.
+ *
+ * @param authenticatorId See the above documentation.
*/
void onAuthenticatorIdRetrieved(in long authenticatorId);
/**
- * A callback invoked when ISession#invalidateAuthenticatorId has completed.
+ * This method must only be used to notify the framework during
+ * SessionState::INVALIDATING_AUTHENTICATOR_ID.
+ *
+ * See ISession#invalidateAuthenticatorId for more information.
*/
void onAuthenticatorIdInvalidated();
}