Fingerprint: Add post_enroll() API, adapt struct for binary compatibility, doc change.

Change-Id: If7e5738f921b0e91e46efc813d9f3c4bd1502832
Signed-off-by: Sasha Levitskiy <sanek@google.com>

1 files changed, 47 insertions, 35 deletions

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,6 +102,35 @@ typedef struct fingerprint_device {
     struct hw_device_t common;
 
     /*
+     * Client provided callback function to receive notifications.
+     * Do not set by hand, use the function above instead.
+     */
+    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:
+     * Generates a unique token to upper layers to indicate the start of an enrollment transaction.
+     * This token will be wrapped by security for verification and passed to enroll() for
+     * verification before enrollment will be allowed. This is to ensure adding a new fingerprint
+     * template was preceded by some kind of credential confirmation (e.g. device password).
+     *
+     * Function return: 0 if function failed
+     *                  otherwise, a uint64_t of token
+     */
+    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
@@ -112,23 +141,21 @@ typedef struct fingerprint_device {
      * 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.
+     *                  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);
 
     /*
-     * Fingerprint pre-enroll enroll request:
-     * Generates a unique token to upper layers to indicate the start of an enrollment transaction.
-     * This token will be wrapped by security for verification and passed to enroll() for
-     * verification before enrollment will be allowed. This is to ensure adding a new fingerprint
-     * template was preceded by some kind of credential confirmation (e.g. device password).
+     * 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 function failed
-     *                  otherwise, a uint64_t of token
+     * Function return: 0 if the request is accepted
+     *                  or a negative number in case of error, generally from the errno.h set.
      */
-    uint64_t (*pre_enroll)(struct fingerprint_device *dev);
+    int (*post_enroll)(struct fingerprint_device *dev);
 
     /*
      * get_authenticator_id:
@@ -136,17 +163,17 @@ typedef struct fingerprint_device {
      * 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 @@ typedef struct fingerprint_device {
      * 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 @@ typedef struct fingerprint_device {
      * 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 @@ typedef struct fingerprint_device {
      * 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 @@ typedef struct fingerprint_device {
      * 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 {