include/hardware/fingerprint.h

   1 /*
   2  * Copyright (C) 2014 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H
  18 #define ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H
  19
  20 #define FINGERPRINT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
  21 #define FINGERPRINT_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
  22 #define FINGERPRINT_HARDWARE_MODULE_ID "fingerprint"
  23
  24 typedef enum fingerprint_msg_type {
  25     FINGERPRINT_ERROR = -1,
  26     FINGERPRINT_ACQUIRED = 1,
  27     FINGERPRINT_PROCESSED = 2,
  28     FINGERPRINT_TEMPLATE_ENROLLING = 3,
  29     FINGERPRINT_TEMPLATE_REMOVED = 4,
  30     FINGERPRINT_AUTHENTICATED = 5
  31 } fingerprint_msg_type_t;
  32
  33 typedef enum fingerprint_error {
  34     FINGERPRINT_ERROR_HW_UNAVAILABLE = 1,
  35     FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2,
  36     FINGERPRINT_ERROR_TIMEOUT = 3,
  37     FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */
  38     FINGERPRINT_ERROR_CANCELED = 5,
  39     FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint id can't be removed */
  40     FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */
  41 } fingerprint_error_t;
  42
  43 typedef enum fingerprint_acquired_info {
  44     FINGERPRINT_ACQUIRED_GOOD = 0,
  45     FINGERPRINT_ACQUIRED_PARTIAL = 1,
  46     FINGERPRINT_ACQUIRED_INSUFFICIENT = 2,
  47     FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3,
  48     FINGERPRINT_ACQUIRED_TOO_SLOW = 4,
  49     FINGERPRINT_ACQUIRED_TOO_FAST = 5,
  50     FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */
  51 } fingerprint_acquired_info_t;
  52
  53 typedef struct fingerprint_finger_id {
  54     uint32_t gid;
  55     uint32_t fid;
  56 } fingerprint_finger_id_t;
  57
  58 /* The progress indication may be augmented by a bitmap encoded indication
  59 * of what finger area is considered as collected.
  60 * Bit numbers mapped to physical location:
  61 *
  62 *             distal
  63 *        +--+--+--+--+--+
  64 *        | 4| 3| 2| 1| 0|
  65 *        | 9| 8| 7| 6| 5|
  66 * medial |14|13|12|11|10| lateral
  67 *        |19|18|17|16|15|
  68 *        |24|23|22|21|20|
  69 *        +--+--+--+--+--+
  70 *            proximal
  71 *
  72 */
  73 typedef uint32_t finger_map_bmp;
  74
  75 typedef enum fingerprint_enroll_msg_type {
  76     FINGERPRINT_ENROLL_MSG_NONE = 0,
  77     FINGERPRINT_ENROLL_MSG_PREDEFINED = 1,  /* TODO: define standard enroll cues */
  78     FINGERPRINT_ENROLL_MSG_BITMAP = 2,  /* typeof(fingerprint_enroll.msg) == *finger_map_bmp */
  79     FINGERPRINT_ENROLL_MSG_VENDOR = 3
  80 } fingerprint_enroll_msg_type_t;
  81
  82 typedef struct fingerprint_enroll {
  83     fingerprint_finger_id_t finger;
  84     /* samples_remaining goes from N (no data collected, but N scans needed)
  85      * to 0 (no more data is needed to build a template). */
  86     uint32_t samples_remaining;
  87     fingerprint_enroll_msg_type_t msg_type;
  88     size_t msg_size;
  89     void *msg;
  90 } fingerprint_enroll_t;
  91
  92 typedef struct fingerprint_removed {
  93     fingerprint_finger_id_t finger;
  94 } fingerprint_removed_t;
  95
  96 typedef struct fingerprint_acquired {
  97     fingerprint_acquired_info_t acquired_info; /* information about the image */
  98 } fingerprint_acquired_t;
  99
 100 typedef struct fingerprint_processed {
 101     fingerprint_finger_id_t finger; /* all 0s is a special case and means no match */
 102 } fingerprint_processed_t;
 103
 104 typedef struct fingerprint_authenticated {
 105     uint32_t user_id;
 106     uint32_t auth_id;
 107     uint32_t timestamp;
 108     uint32_t app_id;
 109     uint64_t crypto_op_id;
 110     uint8_t hmac[16];  /* 128-bit */
 111     uint32_t auth_token_size;
 112     uint8_t *auth_token;
 113 } fingerprint_authenticated_t;
 114
 115 typedef struct fingerprint_msg {
 116     fingerprint_msg_type_t type;
 117     union {
 118         fingerprint_error_t error;
 119         fingerprint_enroll_t enroll;
 120         fingerprint_removed_t removed;
 121         fingerprint_acquired_t acquired;
 122         fingerprint_processed_t processed;
 123         fingerprint_authenticated_t authenticated;
 124     } data;
 125 } fingerprint_msg_t;
 126
 127 /* Callback function type */
 128 typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
 129
 130 /* Synchronous operation */
 131 typedef struct fingerprint_device {
 132     /**
 133      * Common methods of the fingerprint device. This *must* be the first member
 134      * of fingerprint_device as users of this structure will cast a hw_device_t
 135      * to fingerprint_device pointer in contexts where it's known
 136      * the hw_device_t references a fingerprint_device.
 137      */
 138     struct hw_device_t common;
 139
 140     /*
 141      * Fingerprint enroll request:
 142      * Switches the HAL state machine to collect and store a new fingerprint
 143      * template. Switches back as soon as enroll is complete
 144      * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
 145      *  fingerprint_msg.data.enroll.samples_remaining == 0)
 146      * or after timeout_sec seconds.
 147      * The fingerprint template will be assigned to the group gid. User has a choice
 148      * to supply the gid or set it to 0 in which case a unique group id will be generated.
 149      *
 150      * Function return: 0 if enrollment process can be successfully started
 151      *                 -1 otherwise. A notify() function may be called
 152      *                    indicating the error condition.
 153      */
 154     int (*enroll)(struct fingerprint_device *dev, uint32_t gid, uint32_t timeout_sec);
 155
 156     /*
 157      * Cancel fingerprint enroll request:
 158      * Switches the HAL state machine back to accept a fingerprint scan mode.
 159      * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
 160      *  fingerprint_msg.data.enroll.samples_remaining == 0)
 161      * will indicate switch back to the scan mode.
 162      *
 163      * Function return: 0 if cancel request is accepted
 164      *                 -1 otherwise.
 165      */
 166     int (*enroll_cancel)(struct fingerprint_device *dev);
 167
 168     /*
 169      * Fingerprint remove request:
 170      * deletes a fingerprint template.
 171      * If the fingerprint id is 0 and the group is 0 then the entire template
 172      * database will be removed. A combinaiton of fingerprint id 0 and a valid
 173      * group id deletes all fingreprints in that group.
 174      * notify() will be called for each template deleted with
 175      * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and
 176      * fingerprint_msg.data.removed.id indicating each template id removed.
 177      *
 178      * Function return: 0 if fingerprint template(s) can be successfully deleted
 179      *                 -1 otherwise.
 180      */
 181     int (*remove)(struct fingerprint_device *dev, fingerprint_finger_id_t finger);
 182
 183     /*
 184      * Restricts the HAL operation to a set of fingerprints belonging to a
 185      * group provided. Gid of 0 signals global operation.
 186      *
 187      * Function return: 0 on success
 188      *                 -1 if the group does not exist.
 189      */
 190     int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid);
 191
 192     /*
 193      * Authenticates an operation identifed by operation_id
 194      *
 195      * Function return: 0 on success
 196      *                 -1 if the size is out of bounds.
 197      */
 198     int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid);
 199
 200     /*
 201      * Set notification callback:
 202      * Registers a user function that would receive notifications from the HAL
 203      * The call will block if the HAL state machine is in busy state until HAL
 204      * leaves the busy state.
 205      *
 206      * Function return: 0 if callback function is successfuly registered
 207      *                 -1 otherwise.
 208      */
 209     int (*set_notify)(struct fingerprint_device *dev,
 210                         fingerprint_notify_t notify);
 211
 212     /*
 213      * Client provided callback function to receive notifications.
 214      * Do not set by hand, use the function above instead.
 215      */
 216     fingerprint_notify_t notify;
 217
 218     /* Reserved for future use. Must be NULL. */
 219     void* reserved[8 - 4];
 220 } fingerprint_device_t;
 221
 222 typedef struct fingerprint_module {
 223     /**
 224      * Common methods of the fingerprint module. This *must* be the first member
 225      * of fingerprint_module as users of this structure will cast a hw_module_t
 226      * to fingerprint_module pointer in contexts where it's known
 227      * the hw_module_t references a fingerprint_module.
 228      */
 229     struct hw_module_t common;
 230 } fingerprint_module_t;
 231
 232 #endif  /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */