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