blob: b295ebbcba86fc04698e42f34ec91774114021d0 [file] [log] [blame]
Sasha Levitskiya747c062014-03-24 16:14:42 -07001/*
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
Sasha Levitskiy73082842014-04-18 11:14:11 -070023typedef enum fingerprint_msg_type {
Sasha Levitskiya747c062014-03-24 16:14:42 -070024 FINGERPRINT_ERROR = -1,
Sasha Levitskiy73082842014-04-18 11:14:11 -070025 FINGERPRINT_SCANNED = 1,
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070026 FINGERPRINT_TEMPLATE_ENROLLING = 2,
27 FINGERPRINT_TEMPLATE_REMOVED = 4
Sasha Levitskiy73082842014-04-18 11:14:11 -070028} fingerprint_msg_type_t;
Sasha Levitskiya747c062014-03-24 16:14:42 -070029
30typedef enum fingerprint_error {
31 FINGERPRINT_ERROR_HW_UNAVAILABLE = 1,
Sasha Levitskiy73082842014-04-18 11:14:11 -070032 FINGERPRINT_ERROR_BAD_CAPTURE = 2,
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070033 FINGERPRINT_ERROR_TIMEOUT = 3,
34 FINGERPRINT_ERROR_NO_SPACE = 4 /* No space available to store a template */
Sasha Levitskiya747c062014-03-24 16:14:42 -070035} fingerprint_error_t;
36
Sasha Levitskiy73082842014-04-18 11:14:11 -070037typedef struct fingerprint_enroll {
38 uint32_t id;
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -070039 /* samples_remaining goes from N (no data collected, but N scans needed)
Sasha Levitskiy73082842014-04-18 11:14:11 -070040 * to 0 (no more data is needed to build a template)
41 * If HAL fails to decrement samples_remaining between calls the client
42 * will declare template collection a failure and should abort the operation
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -070043 * by calling module->common.methods->close() */
Sasha Levitskiy73082842014-04-18 11:14:11 -070044 uint32_t samples_remaining;
45} fingerprint_enroll_t;
46
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070047typedef struct fingerprint_removed {
48 uint32_t id;
49} fingerprint_removed_t;
50
Sasha Levitskiy73082842014-04-18 11:14:11 -070051typedef struct fingerprint_scanned {
52 uint32_t id; /* 0 is a special id and means no match */
53 uint32_t confidence; /* Goes form 0 (no match) to 0xffffFFFF (100% sure) */
Sasha Levitskiycc14f232014-04-24 09:52:47 -070054} fingerprint_scanned_t;
Sasha Levitskiy73082842014-04-18 11:14:11 -070055
56typedef struct fingerprint_msg {
57 fingerprint_msg_type_t type;
58 union {
59 uint64_t raw;
60 fingerprint_error_t error;
61 fingerprint_enroll_t enroll;
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070062 fingerprint_removed_t removed;
Sasha Levitskiycc14f232014-04-24 09:52:47 -070063 fingerprint_scanned_t scan;
Sasha Levitskiy73082842014-04-18 11:14:11 -070064 } data;
65} fingerprint_msg_t;
66
67/* Callback function type */
68typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
69
Sasha Levitskiya747c062014-03-24 16:14:42 -070070/* Synchronous operation */
71typedef struct fingerprint_device {
72 struct hw_device_t common;
73
74 /*
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -070075 * Fingerprint enroll request:
Sasha Levitskiy73082842014-04-18 11:14:11 -070076 * Switches the HAL state machine to collect and store a new fingerprint
77 * template. Switches back as soon as enroll is complete
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070078 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
Sasha Levitskiy73082842014-04-18 11:14:11 -070079 * fingerprint_msg.data.enroll.samples_remaining == 0)
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -070080 * or after timeout_sec seconds.
Sasha Levitskiya747c062014-03-24 16:14:42 -070081 *
Sasha Levitskiy73082842014-04-18 11:14:11 -070082 * Function return: 0 if enrollment process can be successfully started
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070083 * -1 otherwise. A notify() function may be called
84 * indicating the error condition.
Sasha Levitskiya747c062014-03-24 16:14:42 -070085 */
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -070086 int (*enroll)(struct fingerprint_device *dev, uint32_t timeout_sec);
Sasha Levitskiya747c062014-03-24 16:14:42 -070087
88 /*
Sasha Levitskiy3b9ee8d2014-04-23 10:04:57 -070089 * Fingerprint remove request:
Sasha Levitskiy73082842014-04-18 11:14:11 -070090 * deletes a fingerprint template.
91 * If the fingerprint id is 0 the entire template database will be removed.
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070092 * notify() will be called for each template deleted with
93 * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and
94 * fingerprint_msg.data.removed.id indicating each template id removed.
Sasha Levitskiya747c062014-03-24 16:14:42 -070095 *
Sasha Levitskiy0d1cd3f2014-04-30 13:29:43 -070096 * Function return: 0 if fingerprint template(s) can be successfully deleted
Sasha Levitskiy73082842014-04-18 11:14:11 -070097 * -1 otherwise.
Sasha Levitskiya747c062014-03-24 16:14:42 -070098 */
Sasha Levitskiy73082842014-04-18 11:14:11 -070099 int (*remove)(struct fingerprint_device *dev, uint32_t fingerprint_id);
Sasha Levitskiya747c062014-03-24 16:14:42 -0700100
101 /*
Sasha Levitskiy73082842014-04-18 11:14:11 -0700102 * Set notification callback:
103 * Registers a user function that would receive notifications from the HAL
104 * The call will block if the HAL state machine is in busy state until HAL
105 * leaves the busy state.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700106 *
Sasha Levitskiy73082842014-04-18 11:14:11 -0700107 * Function return: 0 if callback function is successfuly registered
108 * -1 otherwise.
Sasha Levitskiya747c062014-03-24 16:14:42 -0700109 */
Sasha Levitskiy73082842014-04-18 11:14:11 -0700110 int (*set_notify)(struct fingerprint_device *dev,
111 fingerprint_notify_t notify);
112
113 /*
114 * Client provided callback function to receive notifications.
115 * Do not set by hand, use the function above instead.
116 */
117 fingerprint_notify_t notify;
Sasha Levitskiya747c062014-03-24 16:14:42 -0700118
119 /* Reserved for future use. Must be NULL. */
Sasha Levitskiy73082842014-04-18 11:14:11 -0700120 void* reserved[8 - 4];
Sasha Levitskiya747c062014-03-24 16:14:42 -0700121} fingerprint_device_t;
122
123typedef struct fingerprint_module {
124 struct hw_module_t common;
125} fingerprint_module_t;
126
Sasha Levitskiya747c062014-03-24 16:14:42 -0700127#endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */