From a36ffbe0bbccbc2173589da1941dd39ee01a8004 Mon Sep 17 00:00:00 2001 From: Sasha Levitskiy Date: Wed, 24 Jun 2015 16:32:43 -0700 Subject: Fingerprint: Add post_enroll() API, adapt struct for binary compatibility, doc change. Change-Id: If7e5738f921b0e91e46efc813d9f3c4bd1502832 Signed-off-by: Sasha Levitskiy --- include/hardware/fingerprint.h | 82 ++++++++++++++++++++++++------------------ 1 file 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 { -- cgit v1.1