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_HARDWARE_MODULE_ID "fingerprint"
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;
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;
38 typedef enum fingerprint_scan_info {
39 FINGERPRINT_SCAN_GOOD = 0,
40 FINGERPRINT_SCAN_PARTIAL = 1,
41 FINGERPRINT_SCAN_INSUFFICIENT = 2,
42 FINGERPRINT_SCAN_IMAGER_DIRTY = 4,
43 FINGERPRINT_SCAN_TOO_SLOW = 8,
44 FINGERPRINT_SCAN_TOO_FAST = 16
45 } fingerprint_scan_info_t;
47 typedef struct fingerprint_enroll {
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:
59 * medial |8|7|6| lateral
66 uint16_t data_collected_bmp;
67 uint16_t samples_remaining;
68 } fingerprint_enroll_t;
70 typedef struct fingerprint_removed {
72 } fingerprint_removed_t;
74 typedef struct fingerprint_acquired {
75 fingerprint_scan_info_t scan_info; /* information about the image */
76 } fingerprint_acquired_t;
78 typedef struct fingerprint_processed {
79 uint32_t id; /* 0 is a special id and means no match */
80 } fingerprint_processed_t;
82 typedef struct fingerprint_msg {
83 fingerprint_msg_type_t type;
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;
94 /* Callback function type */
95 typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
97 /* Synchronous operation */
98 typedef struct fingerprint_device {
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.
105 struct hw_device_t common;
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.
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.
119 int (*enroll)(struct fingerprint_device *dev, uint32_t timeout_sec);
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.
128 * Function return: 0 if cancel request is accepted
131 int (*enroll_cancel)(struct fingerprint_device *dev);
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.
141 * Function return: 0 if fingerprint template(s) can be successfully deleted
144 int (*remove)(struct fingerprint_device *dev, uint32_t fingerprint_id);
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.
152 * Function return: 0 if callback function is successfuly registered
155 int (*set_notify)(struct fingerprint_device *dev,
156 fingerprint_notify_t notify);
159 * Client provided callback function to receive notifications.
160 * Do not set by hand, use the function above instead.
162 fingerprint_notify_t notify;
164 /* Reserved for future use. Must be NULL. */
165 void* reserved[8 - 4];
166 } fingerprint_device_t;
168 typedef struct fingerprint_module {
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.
175 struct hw_module_t common;
176 } fingerprint_module_t;
178 #endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */