include/hardware/fingerprint.h

   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_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;
  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_scan_info_t scan_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 */