2 * Copyright (C) 2014 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H
18 #define ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H
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"
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;
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_t;
40 typedef enum fingerprint_acquired_info {
41 FINGERPRINT_ACQUIRED_GOOD = 0,
42 FINGERPRINT_ACQUIRED_PARTIAL = 1,
43 FINGERPRINT_ACQUIRED_INSUFFICIENT = 2,
44 FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3,
45 FINGERPRINT_ACQUIRED_TOO_SLOW = 4,
46 FINGERPRINT_ACQUIRED_TOO_FAST = 5,
47 FINGERPRINT_ACQUIRED_VENDOR_DEFINED = 6
48 } fingerprint_acquired_info_t;
50 typedef struct fingerprint_finger_id {
53 } fingerprint_finger_id_t;
55 /* The progress indication may be augmented by a bitmap encoded indication
56 * of what finger area is considered as collected.
57 * Bit numbers mapped to physical location:
63 * medial |14|13|12|11|10| lateral
70 typedef uint32_t finger_map_bmp;
72 typedef enum fingerprint_enroll_msg_type {
73 FINGERPRINT_ENROLL_MSG_NONE = 0,
74 FINGERPRINT_ENROLL_MSG_PREDEFINED = 1, /* TODO: define standard enroll cues */
75 FINGERPRINT_ENROLL_MSG_BITMAP = 2, /* typeof(fingerprint_enroll.msg) == *finger_map_bmp */
76 FINGERPRINT_ENROLL_MSG_VENDOR = 3
77 } fingerprint_enroll_msg_type_t;
79 typedef struct fingerprint_enroll {
80 fingerprint_finger_id_t finger;
81 uint32_t samples_remaining;
82 /* samples_remaining goes from N (no data collected, but N scans needed)
83 * to 0 (no more data is needed to build a template). */
84 fingerprint_enroll_msg_type_t msg_type;
87 } fingerprint_enroll_t;
89 typedef struct fingerprint_removed {
90 fingerprint_finger_id_t finger;
91 } fingerprint_removed_t;
93 typedef struct fingerprint_acquired {
94 fingerprint_acquired_info_t acquired_info; /* information about the image */
95 } fingerprint_acquired_t;
97 typedef struct fingerprint_processed {
98 fingerprint_finger_id_t finger; /* all 0s is a special case and means no match */
99 } fingerprint_processed_t;
101 typedef struct fingerprint_authenticated {
106 uint64_t crypto_op_id;
107 uint8_t hmac[16]; /* 128-bit */
108 uint32_t auth_token_size;
110 } fingerprint_authenticated_t;
112 typedef struct fingerprint_msg {
113 fingerprint_msg_type_t type;
115 fingerprint_error_t error;
116 fingerprint_enroll_t enroll;
117 fingerprint_removed_t removed;
118 fingerprint_acquired_t acquired;
119 fingerprint_processed_t processed;
120 fingerprint_authenticated_t authenticated;
124 /* Callback function type */
125 typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
127 /* Synchronous operation */
128 typedef struct fingerprint_device {
130 * Common methods of the fingerprint device. This *must* be the first member
131 * of fingerprint_device as users of this structure will cast a hw_device_t
132 * to fingerprint_device pointer in contexts where it's known
133 * the hw_device_t references a fingerprint_device.
135 struct hw_device_t common;
138 * Fingerprint enroll request:
139 * Switches the HAL state machine to collect and store a new fingerprint
140 * template. Switches back as soon as enroll is complete
141 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
142 * fingerprint_msg.data.enroll.samples_remaining == 0)
143 * or after timeout_sec seconds.
144 * The fingerprint template will be assigned to the group gid. User has a choice
145 * to supply the gid or set it to 0 in which case a unique group id will be generated.
147 * Function return: 0 if enrollment process can be successfully started
148 * -1 otherwise. A notify() function may be called
149 * indicating the error condition.
151 int (*enroll)(struct fingerprint_device *dev, uint32_t gid, uint32_t timeout_sec);
154 * Cancel fingerprint enroll request:
155 * Switches the HAL state machine back to accept a fingerprint scan mode.
156 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
157 * fingerprint_msg.data.enroll.samples_remaining == 0)
158 * will indicate switch back to the scan mode.
160 * Function return: 0 if cancel request is accepted
163 int (*enroll_cancel)(struct fingerprint_device *dev);
166 * Fingerprint remove request:
167 * deletes a fingerprint template.
168 * If the fingerprint id is 0 and the group is 0 then the entire template
169 * database will be removed. A combinaiton of fingerprint id 0 and a valid
170 * group id deletes all fingreprints in that group.
171 * notify() will be called for each template deleted with
172 * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and
173 * fingerprint_msg.data.removed.id indicating each template id removed.
175 * Function return: 0 if fingerprint template(s) can be successfully deleted
178 int (*remove)(struct fingerprint_device *dev, fingerprint_finger_id_t finger);
181 * Restricts the HAL operation to a set of fingerprints belonging to a
182 * group provided. Gid of 0 signals global operation.
184 * Function return: 0 on success
185 * -1 if the group does not exist.
187 int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid);
190 * Authenticates an operation identifed by operation_id
192 * Function return: 0 on success
193 * -1 if the size is out of bounds.
195 int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id);
198 * Set notification callback:
199 * Registers a user function that would receive notifications from the HAL
200 * The call will block if the HAL state machine is in busy state until HAL
201 * leaves the busy state.
203 * Function return: 0 if callback function is successfuly registered
206 int (*set_notify)(struct fingerprint_device *dev,
207 fingerprint_notify_t notify);
210 * Client provided callback function to receive notifications.
211 * Do not set by hand, use the function above instead.
213 fingerprint_notify_t notify;
215 /* Reserved for future use. Must be NULL. */
216 void* reserved[8 - 4];
217 } fingerprint_device_t;
219 typedef struct fingerprint_module {
221 * Common methods of the fingerprint module. This *must* be the first member
222 * of fingerprint_module as users of this structure will cast a hw_module_t
223 * to fingerprint_module pointer in contexts where it's known
224 * the hw_module_t references a fingerprint_module.
226 struct hw_module_t common;
227 } fingerprint_module_t;
229 #endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */