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_HARDWARE_MODULE_ID "fingerprint" 22 23 typedef enum fingerprint_msg_type { 24 FINGERPRINT_ERROR = -1, 25 FINGERPRINT_ACQUIRED = 1, 26 FINGERPRINT_PROCESSED = 2, 27 FINGERPRINT_TEMPLATE_ENROLLING = 3, 28 FINGERPRINT_TEMPLATE_REMOVED = 4 29 } fingerprint_msg_type_t; 30 31 typedef enum fingerprint_error { 32 FINGERPRINT_ERROR_HW_UNAVAILABLE = 1, 33 FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2, 34 FINGERPRINT_ERROR_TIMEOUT = 3, 35 FINGERPRINT_ERROR_NO_SPACE = 4 /* No space available to store a template */ 36 } fingerprint_error_t; 37 38 typedef enum fingerprint_acquired_info { 39 FINGERPRINT_ACQUIRED_GOOD = 0, 40 FINGERPRINT_ACQUIRED_PARTIAL = 1, 41 FINGERPRINT_ACQUIRED_INSUFFICIENT = 2, 42 FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 4, 43 FINGERPRINT_ACQUIRED_TOO_SLOW = 8, 44 FINGERPRINT_ACQUIRED_TOO_FAST = 16 45 } fingerprint_acquired_info_t; 46 47 typedef struct fingerprint_enroll { 48 uint32_t id; 49 /* samples_remaining goes from N (no data collected, but N scans needed) 50 * to 0 (no more data is needed to build a template). 51 * The progress indication may be augmented by a bitmap encoded indication 52 * of finger area that needs to be presented by the user. 53 * Bit numbers mapped to physical location: 54 * 55 * distal 56 * +-+-+-+ 57 * |2|1|0| 58 * |5|4|3| 59 * medial |8|7|6| lateral 60 * |b|a|9| 61 * |e|d|c| 62 * +-+-+-+ 63 * proximal 64 * 65 */ 66 uint16_t data_collected_bmp; 67 uint16_t samples_remaining; 68 } fingerprint_enroll_t; 69 70 typedef struct fingerprint_removed { 71 uint32_t id; 72 } fingerprint_removed_t; 73 74 typedef struct fingerprint_acquired { 75 fingerprint_acquired_info_t acquired_info; /* information about the image */ 76 } fingerprint_acquired_t; 77 78 typedef struct fingerprint_processed { 79 uint32_t id; /* 0 is a special id and means no match */ 80 } fingerprint_processed_t; 81 82 typedef struct fingerprint_msg { 83 fingerprint_msg_type_t type; 84 union { 85 uint64_t raw; 86 fingerprint_error_t error; 87 fingerprint_enroll_t enroll; 88 fingerprint_removed_t removed; 89 fingerprint_acquired_t acquired; 90 fingerprint_processed_t processed; 91 } data; 92 } fingerprint_msg_t; 93 94 /* Callback function type */ 95 typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg); 96 97 /* Synchronous operation */ 98 typedef struct fingerprint_device { 99 /** 100 * Common methods of the fingerprint device. This *must* be the first member 101 * of fingerprint_device as users of this structure will cast a hw_device_t 102 * to fingerprint_device pointer in contexts where it's known 103 * the hw_device_t references a fingerprint_device. 104 */ 105 struct hw_device_t common; 106 107 /* 108 * Fingerprint enroll request: 109 * Switches the HAL state machine to collect and store a new fingerprint 110 * template. Switches back as soon as enroll is complete 111 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING && 112 * fingerprint_msg.data.enroll.samples_remaining == 0) 113 * or after timeout_sec seconds. 114 * 115 * Function return: 0 if enrollment process can be successfully started 116 * -1 otherwise. A notify() function may be called 117 * indicating the error condition. 118 */ 119 int (*enroll)(struct fingerprint_device *dev, uint32_t timeout_sec); 120 121 /* 122 * Cancel fingerprint enroll request: 123 * Switches the HAL state machine back to accept a fingerprint scan mode. 124 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING && 125 * fingerprint_msg.data.enroll.samples_remaining == 0) 126 * will indicate switch back to the scan mode. 127 * 128 * Function return: 0 if cancel request is accepted 129 * -1 otherwise. 130 */ 131 int (*enroll_cancel)(struct fingerprint_device *dev); 132 133 /* 134 * Fingerprint remove request: 135 * deletes a fingerprint template. 136 * If the fingerprint id is 0 the entire template database will be removed. 137 * notify() will be called for each template deleted with 138 * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and 139 * fingerprint_msg.data.removed.id indicating each template id removed. 140 * 141 * Function return: 0 if fingerprint template(s) can be successfully deleted 142 * -1 otherwise. 143 */ 144 int (*remove)(struct fingerprint_device *dev, uint32_t fingerprint_id); 145 146 /* 147 * Set notification callback: 148 * Registers a user function that would receive notifications from the HAL 149 * The call will block if the HAL state machine is in busy state until HAL 150 * leaves the busy state. 151 * 152 * Function return: 0 if callback function is successfuly registered 153 * -1 otherwise. 154 */ 155 int (*set_notify)(struct fingerprint_device *dev, 156 fingerprint_notify_t notify); 157 158 /* 159 * Client provided callback function to receive notifications. 160 * Do not set by hand, use the function above instead. 161 */ 162 fingerprint_notify_t notify; 163 164 /* Reserved for future use. Must be NULL. */ 165 void* reserved[8 - 4]; 166 } fingerprint_device_t; 167 168 typedef struct fingerprint_module { 169 /** 170 * Common methods of the fingerprint module. This *must* be the first member 171 * of fingerprint_module as users of this structure will cast a hw_module_t 172 * to fingerprint_module pointer in contexts where it's known 173 * the hw_module_t references a fingerprint_module. 174 */ 175 struct hw_module_t common; 176 } fingerprint_module_t; 177 178 #endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */ 179