From 929e0a194ed989af9b9de62126a962ebf9d191cc Mon Sep 17 00:00:00 2001 From: Jim Miller Date: Fri, 24 Jul 2015 18:25:40 -0700 Subject: Add better documentation to fingerprint.h Some vendors are confused by the use of errors vs acquired messages This adds documentation on how they should be used. Fixes bug 22728578 Change-Id: I5e6a8f7b159ec331a59202fa64b7320e43661429 --- include/hardware/fingerprint.h | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/include/hardware/fingerprint.h b/include/hardware/fingerprint.h index 075e18b..ac88c10 100644 --- a/include/hardware/fingerprint.h +++ b/include/hardware/fingerprint.h @@ -31,23 +31,41 @@ typedef enum fingerprint_msg_type { FINGERPRINT_AUTHENTICATED = 5 } fingerprint_msg_type_t; +/* + * Fingerprint errors are meant to tell the framework to terminate the current operation and ask + * for the user to correct the situation. These will almost always result in messaging and user + * interaction to correct the problem. + * + * For example, FINGERPRINT_ERROR_CANCELED should follow any acquisition message that results in + * a situation where the current operation can't continue without user interaction. For example, + * if the sensor is dirty during enrollment and no further enrollment progress can be made, + * send FINGERPRINT_ACQUIRED_IMAGER_DIRTY followed by FINGERPRINT_ERROR_CANCELED. + */ typedef enum fingerprint_error { - FINGERPRINT_ERROR_HW_UNAVAILABLE = 1, - FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2, - FINGERPRINT_ERROR_TIMEOUT = 3, + FINGERPRINT_ERROR_HW_UNAVAILABLE = 1, /* The hardware has an error that can't be resolved. */ + FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2, /* Bad data; operation can't continue */ + FINGERPRINT_ERROR_TIMEOUT = 3, /* The operation has timed out waiting for user input. */ FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */ - FINGERPRINT_ERROR_CANCELED = 5, - FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint id can't be removed */ + FINGERPRINT_ERROR_CANCELED = 5, /* The current operation can't proceed. See above. */ + FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint with given id can't be removed */ FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */ } fingerprint_error_t; +/* + * Fingerprint acquisition info is meant as feedback for the current operation. Anything but + * FINGERPRINT_ACQUIRED_GOOD will be shown to the user as feedback on how to take action on the + * current operation. For example, FINGERPRINT_ACQUIRED_IMAGER_DIRTY can be used to tell the user + * to clean the sensor. If this will cause the current operation to fail, an additional + * FINGERPRINT_ERROR_CANCELED can be sent to stop the operation in progress (e.g. enrollment). + * In general, these messages will result in a "Try again" message. + */ typedef enum fingerprint_acquired_info { FINGERPRINT_ACQUIRED_GOOD = 0, - FINGERPRINT_ACQUIRED_PARTIAL = 1, - FINGERPRINT_ACQUIRED_INSUFFICIENT = 2, - FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3, - FINGERPRINT_ACQUIRED_TOO_SLOW = 4, - FINGERPRINT_ACQUIRED_TOO_FAST = 5, + FINGERPRINT_ACQUIRED_PARTIAL = 1, /* sensor needs more data, i.e. longer swipe. */ + FINGERPRINT_ACQUIRED_INSUFFICIENT = 2, /* image doesn't contain enough detail for recognition*/ + FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3, /* sensor needs to be cleaned */ + FINGERPRINT_ACQUIRED_TOO_SLOW = 4, /* mostly swipe-type sensors; not enough data collected */ + FINGERPRINT_ACQUIRED_TOO_FAST = 5, /* for swipe and area sensors; tell user to slow down*/ FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */ } fingerprint_acquired_info_t; -- cgit v1.1