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
23typedef 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
31typedef 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
38typedef 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
47typedef 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
70typedef struct fingerprint_removed {
71    uint32_t id;
72} fingerprint_removed_t;
73
74typedef struct fingerprint_acquired {
75    fingerprint_acquired_info_t acquired_info; /* information about the image */
76} fingerprint_acquired_t;
77
78typedef struct fingerprint_processed {
79    uint32_t id; /* 0 is a special id and means no match */
80} fingerprint_processed_t;
81
82typedef 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 */
95typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
96
97/* Synchronous operation */
98typedef 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
168typedef 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