am 929e0a19: Add better documentation to fingerprint.h
* commit '929e0a194ed989af9b9de62126a962ebf9d191cc':
Add better documentation to fingerprint.h
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 @@
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;
