Finish remainder of documentation. (8b3cd5db) · Commits · e / os / android_hardware_interfaces

biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl

+36 −0

Original line number	Original line	Diff line number	Diff line
	@@ -19,13 +19,49 @@ package android.hardware.biometrics.fingerprint;
	@VintfStability		@VintfStability
	@Backing(type="byte")		@Backing(type="byte")
	enum AcquiredInfo {		enum AcquiredInfo {
			/**
			* A high quality fingerprint image was detected, no further user interaction is necessary.
			*/
	GOOD,		GOOD,

			/**
			* Not enough of a fingerprint was detected. Reposition the finger, or a longer swipe needed.
			*/
	PARTIAL,		PARTIAL,

			/**
			* Image doesn't contain enough detail for recognition.
			*/
	INSUFFICIENT,		INSUFFICIENT,

			/**
			* The sensor needs to be cleaned.
			*/
	SENSOR_DIRTY,		SENSOR_DIRTY,

			/**
			* For swipe-type sensors, the swipe was too slow and not enough data was collected.
			*/
	TOO_SLOW,		TOO_SLOW,

			/**
			* For swipe-type sensors, the swipe was too fast and not enough data was collected.
			*/
	TOO_FAST,		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,		START,

			/**
			* Vendor-specific acquisition message. See ISessionCallback#onAcquired vendorCode
			* documentation.
			*/
	VENDOR		VENDOR
	}		}

biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl

+7 −5

biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl

+110 −1

Original line number	Original line	Diff line number	Diff line
	@@ -80,7 +80,7 @@ interface ISession {
	*		*
	* When a finger is successfully added and before the framework is notified		* When a finger is successfully added and before the framework is notified
	* of remaining=0, the implementation MUST update and associate this		* 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.		* See ISession#getAuthenticatorId for more information.
	*		*
	* @param cookie An identifier used to track subsystem operations related		* @param cookie An identifier used to track subsystem operations related
	@@ -147,10 +147,75 @@ interface ISession {
	*/		*/
	ICancellationSignal authenticate(in int cookie, in long operationId);		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);		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);		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);		void removeEnrollments(in int cookie, in int[] enrollmentIds);

	/**		/**
	@@ -259,10 +324,54 @@ interface ISession {
	* Methods for notifying the under-display fingerprint sensor about external events.		* 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);		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);		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();		void onUiReady();
	}		}

biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl

+72 −3

Original line number	Original line	Diff line number	Diff line
	@@ -23,14 +23,48 @@ import android.hardware.keymaster.HardwareAuthToken;

	@VintfStability		@VintfStability
	interface ISessionCallback {		interface ISessionCallback {
			/**
			* Used to notify the framework of session state changes. See ISession for more information.
			*/
	void onStateChanged(in int cookie, in SessionState state);		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);		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);		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		* @param enrollmentId Unique stable identifier for the enrollment that's being added by this
	* ISession#enroll invocation.		* ISession#enroll invocation.
	@@ -39,6 +73,8 @@ interface ISessionCallback {
	void onEnrollmentProgress(in int enrollmentId, int remaining);		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		* 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		* 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		* Error::LOCKOUT occurred. The authentication lifecycle does NOT end when a fingerprint is
	@@ -53,6 +89,8 @@ interface ISessionCallback {
	void onAuthenticationSucceeded(in int enrollmentId, in HardwareAuthToken hat);		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		* 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		* 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		* Error::LOCKOUT occurred. The authentication lifecycle does NOT end when a fingerprint is
	@@ -60,19 +98,50 @@ interface ISessionCallback {
	*/		*/
	void onAuthenticationFailed();		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();		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);		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);		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);		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();		void onAuthenticatorIdInvalidated();
	}		}