Fingerprint: Add post_enroll() API, adapt struct for binary compatibility, doc change.
Change-Id: If7e5738f921b0e91e46efc813d9f3c4bd1502832
Signed-off-by: Sasha Levitskiy <sanek@google.com>
diff --git a/include/hardware/fingerprint.h b/include/hardware/fingerprint.h
index fd0d8f3..075e18b 100644
--- a/include/hardware/fingerprint.h
+++ b/include/hardware/fingerprint.h
@@ -102,21 +102,21 @@
struct hw_device_t common;
/*
- * Fingerprint enroll request:
- * Switches the HAL state machine to collect and store a new fingerprint
- * template. Switches back as soon as enroll is complete
- * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
- * fingerprint_msg.data.enroll.samples_remaining == 0)
- * or after timeout_sec seconds.
- * The fingerprint template will be assigned to the group gid. User has a choice
- * to supply the gid or set it to 0 in which case a unique group id will be generated.
- *
- * Function return: 0 if enrollment process can be successfully started
- * -1 otherwise. A notify() function may be called
- * indicating the error condition.
+ * Client provided callback function to receive notifications.
+ * Do not set by hand, use the function above instead.
*/
- int (*enroll)(struct fingerprint_device *dev, const hw_auth_token_t *hat,
- uint32_t gid, uint32_t timeout_sec);
+ fingerprint_notify_t notify;
+
+ /*
+ * Set notification callback:
+ * Registers a user function that would receive notifications from the HAL
+ * The call will block if the HAL state machine is in busy state until HAL
+ * leaves the busy state.
+ *
+ * Function return: 0 if callback function is successfuly registered
+ * or a negative number in case of error, generally from the errno.h set.
+ */
+ int (*set_notify)(struct fingerprint_device *dev, fingerprint_notify_t notify);
/*
* Fingerprint pre-enroll enroll request:
@@ -131,22 +131,49 @@
uint64_t (*pre_enroll)(struct fingerprint_device *dev);
/*
+ * Fingerprint enroll request:
+ * Switches the HAL state machine to collect and store a new fingerprint
+ * template. Switches back as soon as enroll is complete
+ * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
+ * fingerprint_msg.data.enroll.samples_remaining == 0)
+ * or after timeout_sec seconds.
+ * The fingerprint template will be assigned to the group gid. User has a choice
+ * to supply the gid or set it to 0 in which case a unique group id will be generated.
+ *
+ * Function return: 0 if enrollment process can be successfully started
+ * or a negative number in case of error, generally from the errno.h set.
+ * A notify() function may be called indicating the error condition.
+ */
+ int (*enroll)(struct fingerprint_device *dev, const hw_auth_token_t *hat,
+ uint32_t gid, uint32_t timeout_sec);
+
+ /*
+ * Finishes the enroll operation and invalidates the pre_enroll() generated challenge.
+ * This will be called at the end of a multi-finger enrollment session to indicate
+ * that no more fingers will be added.
+ *
+ * Function return: 0 if the request is accepted
+ * or a negative number in case of error, generally from the errno.h set.
+ */
+ int (*post_enroll)(struct fingerprint_device *dev);
+
+ /*
* get_authenticator_id:
* Returns a token associated with the current fingerprint set. This value will
* change whenever a new fingerprint is enrolled, thus creating a new fingerprint
* set.
*
- * Function return: current authenticator id.
+ * Function return: current authenticator id or 0 if function failed.
*/
uint64_t (*get_authenticator_id)(struct fingerprint_device *dev);
/*
* Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED
* to all running clients. Switches the HAL state machine back to the idle state.
- * will indicate switch back to the scan mode.
+ * Unlike enroll_done() doesn't invalidate the pre_enroll() challenge.
*
* Function return: 0 if cancel request is accepted
- * -1 otherwise.
+ * or a negative number in case of error, generally from the errno.h set.
*/
int (*cancel)(struct fingerprint_device *dev);
@@ -165,9 +192,8 @@
* The caller of this function has a complete list of the templates when *max_size
* is the same as the function return.
*
- * Function return: Total number of fingerprint templates in the current
- storage directory.
- * -1 on error.
+ * Function return: Total number of fingerprint templates in the current storage directory.
+ * or a negative number in case of error, generally from the errno.h set.
*/
int (*enumerate)(struct fingerprint_device *dev, fingerprint_finger_id_t *results,
uint32_t *max_size);
@@ -181,7 +207,7 @@
* fingerprint_msg.data.removed.id indicating the template id removed.
*
* Function return: 0 if fingerprint template(s) can be successfully deleted
- * -1 otherwise.
+ * or a negative number in case of error, generally from the errno.h set.
*/
int (*remove)(struct fingerprint_device *dev, uint32_t gid, uint32_t fid);
@@ -192,7 +218,7 @@
* data directory.
*
* Function return: 0 on success
- * -1 if the group does not exist.
+ * or a negative number in case of error, generally from the errno.h set.
*/
int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid,
const char *store_path);
@@ -201,26 +227,12 @@
* Authenticates an operation identifed by operation_id
*
* Function return: 0 on success
- * -1 if the operation cannot be completed
+ * or a negative number in case of error, generally from the errno.h set.
*/
int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid);
- /*
- * Set notification callback:
- * Registers a user function that would receive notifications from the HAL
- * The call will block if the HAL state machine is in busy state until HAL
- * leaves the busy state.
- *
- * Function return: 0 if callback function is successfuly registered
- * -1 otherwise.
- */
- int (*set_notify)(struct fingerprint_device *dev, fingerprint_notify_t notify);
-
- /*
- * Client provided callback function to receive notifications.
- * Do not set by hand, use the function above instead.
- */
- fingerprint_notify_t notify;
+ /* Reserved for backward binary compatibility */
+ void *reserved[4];
} fingerprint_device_t;
typedef struct fingerprint_module {