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 #include <hardware/hw_auth_token.h>
22 #define FINGERPRINT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
23 #define FINGERPRINT_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
24 #define FINGERPRINT_HARDWARE_MODULE_ID "fingerprint"
26 typedef enum fingerprint_msg_type {
27 FINGERPRINT_ERROR = -1,
28 FINGERPRINT_ACQUIRED = 1,
29 FINGERPRINT_TEMPLATE_ENROLLING = 3,
30 FINGERPRINT_TEMPLATE_REMOVED = 4,
31 FINGERPRINT_AUTHENTICATED = 5
32 } fingerprint_msg_type_t;
34 typedef enum fingerprint_error {
35 FINGERPRINT_ERROR_HW_UNAVAILABLE = 1,
36 FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2,
37 FINGERPRINT_ERROR_TIMEOUT = 3,
38 FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */
39 FINGERPRINT_ERROR_CANCELED = 5,
40 FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint id can't be removed */
41 FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */
42 } fingerprint_error_t;
44 typedef enum fingerprint_acquired_info {
45 FINGERPRINT_ACQUIRED_GOOD = 0,
46 FINGERPRINT_ACQUIRED_PARTIAL = 1,
47 FINGERPRINT_ACQUIRED_INSUFFICIENT = 2,
48 FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3,
49 FINGERPRINT_ACQUIRED_TOO_SLOW = 4,
50 FINGERPRINT_ACQUIRED_TOO_FAST = 5,
51 FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */
52 } fingerprint_acquired_info_t;
54 typedef struct fingerprint_finger_id {
57 } fingerprint_finger_id_t;
59 /* The progress indication may be augmented by a bitmap encoded indication
60 * of what finger area is considered as collected.
61 * Bit numbers mapped to physical location:
67 * medial |14|13|12|11|10| lateral
74 typedef uint32_t finger_map_bmp;
76 typedef enum fingerprint_enroll_msg_type {
77 FINGERPRINT_ENROLL_MSG_NONE = 0,
78 FINGERPRINT_ENROLL_MSG_PREDEFINED = 1, /* TODO: define standard enroll cues */
79 FINGERPRINT_ENROLL_MSG_BITMAP = 2, /* typeof(fingerprint_enroll.msg) == *finger_map_bmp */
80 FINGERPRINT_ENROLL_MSG_VENDOR = 3
81 } fingerprint_enroll_msg_type_t;
83 typedef struct fingerprint_enroll {
84 fingerprint_finger_id_t finger;
85 /* samples_remaining goes from N (no data collected, but N scans needed)
86 * to 0 (no more data is needed to build a template). */
87 uint32_t samples_remaining;
88 fingerprint_enroll_msg_type_t msg_type;
91 } fingerprint_enroll_t;
93 typedef struct fingerprint_removed {
94 fingerprint_finger_id_t finger;
95 } fingerprint_removed_t;
97 typedef struct fingerprint_acquired {
98 fingerprint_acquired_info_t acquired_info; /* information about the image */
99 } fingerprint_acquired_t;
101 typedef struct fingerprint_authenticated {
102 fingerprint_finger_id_t finger;
104 } fingerprint_authenticated_t;
106 typedef struct fingerprint_msg {
107 fingerprint_msg_type_t type;
109 fingerprint_error_t error;
110 fingerprint_enroll_t enroll;
111 fingerprint_removed_t removed;
112 fingerprint_acquired_t acquired;
113 fingerprint_authenticated_t authenticated;
117 /* Callback function type */
118 typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
120 /* Synchronous operation */
121 typedef struct fingerprint_device {
123 * Common methods of the fingerprint device. This *must* be the first member
124 * of fingerprint_device as users of this structure will cast a hw_device_t
125 * to fingerprint_device pointer in contexts where it's known
126 * the hw_device_t references a fingerprint_device.
128 struct hw_device_t common;
131 * Fingerprint enroll request:
132 * Switches the HAL state machine to collect and store a new fingerprint
133 * template. Switches back as soon as enroll is complete
134 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
135 * fingerprint_msg.data.enroll.samples_remaining == 0)
136 * or after timeout_sec seconds.
137 * The fingerprint template will be assigned to the group gid. User has a choice
138 * to supply the gid or set it to 0 in which case a unique group id will be generated.
140 * Function return: 0 if enrollment process can be successfully started
141 * -1 otherwise. A notify() function may be called
142 * indicating the error condition.
144 int (*enroll)(struct fingerprint_device *dev, const hw_auth_token_t *hat,
145 uint32_t gid, uint32_t timeout_sec);
148 * Fingerprint pre-enroll enroll request:
149 * Generates a unique token to upper layers to indicate the start of an enrollment transaction.
150 * This token will be wrapped by security for verification and passed to enroll() for
151 * verification before enrollment will be allowed. This is to ensure adding a new fingerprint
152 * template was preceded by some kind of credential confirmation (e.g. device password).
154 * Function return: 0 if function failed
155 * otherwise, a uint64_t of token
157 uint64_t (*pre_enroll)(struct fingerprint_device *dev);
160 * get_authenticator_id:
161 * Returns a token associated with the current fingerprint set. This value will
162 * change whenever a new fingerprint is enrolled, thus creating a new fingerprint
165 * Function return: current authenticator id.
167 uint64_t (*get_authenticator_id)(struct fingerprint_device *dev);
170 * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED
171 * to all running clients. Switches the HAL state machine back to the idle state.
172 * will indicate switch back to the scan mode.
174 * Function return: 0 if cancel request is accepted
177 int (*cancel)(struct fingerprint_device *dev);
180 * Enumerate all the fingerprint templates found in the directory set by
182 * This is a synchronous call. The function takes:
183 * - A pointer to an array of fingerprint_finger_id_t.
184 * - The size of the array provided, in fingerprint_finger_id_t elements.
185 * Max_size is a bi-directional parameter and returns the actual number
186 * of elements copied to the caller supplied array.
187 * In the absence of errors the function returns the total number of templates
188 * in the user directory.
189 * If the caller has no good guess on the size of the array he should call this
190 * function witn *max_size == 0 and use the return value for the array allocation.
191 * The caller of this function has a complete list of the templates when *max_size
192 * is the same as the function return.
194 * Function return: Total number of fingerprint templates in the current
198 int (*enumerate)(struct fingerprint_device *dev, fingerprint_finger_id_t *results,
202 * Fingerprint remove request:
203 * deletes a fingerprint template.
204 * If the fingerprint id is 0 and the group is 0 then the entire template
205 * database will be removed. A combinaiton of fingerprint id 0 and a valid
206 * group id deletes all fingreprints in that group.
207 * notify() will be called for each template deleted with
208 * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and
209 * fingerprint_msg.data.removed.id indicating each template id removed.
211 * Function return: 0 if fingerprint template(s) can be successfully deleted
214 int (*remove)(struct fingerprint_device *dev, fingerprint_finger_id_t finger);
217 * Restricts the HAL operation to a set of fingerprints belonging to a
219 * The caller must provide a path to a storage location within the user's
222 * Function return: 0 on success
223 * -1 if the group does not exist.
225 int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid,
226 const char *store_path);
229 * Authenticates an operation identifed by operation_id
231 * Function return: 0 on success
232 * -1 if the operation cannot be completed
234 int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid);
237 * Set notification callback:
238 * Registers a user function that would receive notifications from the HAL
239 * The call will block if the HAL state machine is in busy state until HAL
240 * leaves the busy state.
242 * Function return: 0 if callback function is successfuly registered
245 int (*set_notify)(struct fingerprint_device *dev, fingerprint_notify_t notify);
248 * Client provided callback function to receive notifications.
249 * Do not set by hand, use the function above instead.
251 fingerprint_notify_t notify;
252 } fingerprint_device_t;
254 typedef struct fingerprint_module {
256 * Common methods of the fingerprint module. This *must* be the first member
257 * of fingerprint_module as users of this structure will cast a hw_module_t
258 * to fingerprint_module pointer in contexts where it's known
259 * the hw_module_t references a fingerprint_module.
261 struct hw_module_t common;
262 } fingerprint_module_t;
264 #endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */