libfprint/fprint.h

   1 /*
   2  * Main definitions for libfprint
   3  * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  18  */
  19
  20 #ifndef __FPRINT_H__
  21 #define __FPRINT_H__
  22
  23 #include <stdint.h>
  24
  25 /* structs that applications are not allowed to peek into */
  26 struct fp_dscv_dev;
  27 struct fp_dscv_print;
  28 struct fp_dev;
  29 struct fp_driver;
  30 struct fp_print_data;
  31 struct fp_img;
  32
  33 /* misc/general stuff */
  34
  35 /** \ingroup print_data
  36  * Numeric codes used to refer to fingers (and thumbs) of a human. These are
  37  * purposely not available as strings, to avoid getting the library tangled up
  38  * in localization efforts.
  39  */
  40 enum fp_finger {
  41         LEFT_THUMB = 1, /** thumb (left hand) */
  42         LEFT_INDEX, /** index finger (left hand) */
  43         LEFT_MIDDLE, /** middle finger (left hand) */
  44         LEFT_RING, /** ring finger (left hand) */
  45         LEFT_LITTLE, /** little finger (left hand) */
  46         RIGHT_THUMB, /** thumb (right hand) */
  47         RIGHT_INDEX, /** index finger (right hand) */
  48         RIGHT_MIDDLE, /** middle finger (right hand) */
  49         RIGHT_RING, /** ring finger (right hand) */
  50         RIGHT_LITTLE, /** little finger (right hand) */
  51 };
  52
  53 /* Drivers */
  54 const char *fp_driver_get_name(struct fp_driver *drv);
  55 const char *fp_driver_get_full_name(struct fp_driver *drv);
  56 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
  57
  58 /* Device discovery */
  59 struct fp_dscv_dev **fp_discover_devs(void);
  60 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
  61 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
  62 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
  63 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
  64         struct fp_print_data *print);
  65 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
  66         struct fp_dscv_print *print);
  67 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
  68         struct fp_print_data *print);
  69 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
  70         struct fp_dscv_print *print);
  71
  72 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
  73 {
  74         return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
  75 }
  76
  77 /* Print discovery */
  78 struct fp_dscv_print **fp_discover_prints(void);
  79 void fp_dscv_prints_free(struct fp_dscv_print **prints);
  80 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
  81 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
  82 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
  83
  84 /* Device handling */
  85 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
  86 void fp_dev_close(struct fp_dev *dev);
  87 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
  88 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
  89 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
  90 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
  91 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
  92
  93 int fp_dev_supports_imaging(struct fp_dev *dev);
  94 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
  95         struct fp_img **image);
  96 int fp_dev_get_img_width(struct fp_dev *dev);
  97 int fp_dev_get_img_height(struct fp_dev *dev);
  98
  99 /** \ingroup dev
 100  * Enrollment result codes returned from fp_enroll_finger().
 101  * Result codes with RETRY in the name suggest that the scan failed due to
 102  * user error. Applications will generally want to inform the user of the
 103  * problem and then retry the enrollment stage. For more info on the semantics
 104  * of interpreting these result codes and tracking enrollment process, see
 105  * \ref enrolling.
 106  */
 107 enum fp_enroll_result {
 108         /** Enrollment completed successfully, the enrollment data has been
 109          * returned to the caller. */
 110         FP_ENROLL_COMPLETE = 1,
 111         /** Enrollment failed due to incomprehensible data; this may occur when
 112          * the user scans a different finger on each enroll stage. */
 113         FP_ENROLL_FAIL,
 114         /** Enroll stage passed; more stages are need to complete the process. */
 115         FP_ENROLL_PASS,
 116         /** The enrollment scan did not succeed due to poor scan quality or
 117          * other general user scanning problem. */
 118         FP_ENROLL_RETRY = 100,
 119         /** The enrollment scan did not succeed because the finger swipe was
 120          * too short. */
 121         FP_ENROLL_RETRY_TOO_SHORT,
 122         /** The enrollment scan did not succeed because the finger was not
 123          * centered on the scanner. */
 124         FP_ENROLL_RETRY_CENTER_FINGER,
 125         /** The verification scan did not succeed due to quality or pressure
 126          * problems; the user should remove their finger from the scanner before
 127          * retrying. */
 128         FP_ENROLL_RETRY_REMOVE_FINGER,
 129 };
 130
 131 int fp_enroll_finger(struct fp_dev *dev, struct fp_print_data **print_data);
 132
 133 /** \ingroup dev
 134  * Verification result codes returned from fp_verify_finger().
 135  * Result codes with RETRY in the name suggest that the scan failed due to
 136  * user error. Applications will generally want to inform the user of the
 137  * problem and then retry the verify operation.
 138  */
 139 enum fp_verify_result {
 140         /** The verification scan completed successfully, but the newly scanned
 141          * fingerprint does not match the fingerprint being verified against. */
 142         FP_VERIFY_NO_MATCH = 0,
 143         /** The verification scan completed successfully and the newly scanned
 144          * fingerprint does match the fingerprint being verified. */
 145         FP_VERIFY_MATCH = 1,
 146         /** The verification scan did not succeed due to poor scan quality or
 147          * other general user scanning problem. */
 148         FP_VERIFY_RETRY = FP_ENROLL_RETRY,
 149         /** The verification scan did not succeed because the finger swipe was
 150          * too short. */
 151         FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
 152         /** The verification scan did not succeed because the finger was not
 153          * centered on the scanner. */
 154         FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
 155         /** The verification scan did not succeed due to quality or pressure
 156          * problems; the user should remove their finger from the scanner before
 157          * retrying. */
 158         FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
 159 };
 160
 161 int fp_verify_finger(struct fp_dev *dev, struct fp_print_data *enrolled_print);
 162
 163 /* Data handling */
 164 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
 165         struct fp_print_data **data);
 166 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
 167         struct fp_print_data **data);
 168 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
 169 void fp_print_data_free(struct fp_print_data *data);
 170 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
 171 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
 172         size_t buflen);
 173 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
 174 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
 175
 176 /* Image handling */
 177 int fp_img_get_height(struct fp_img *img);
 178 int fp_img_get_width(struct fp_img *img);
 179 unsigned char *fp_img_get_data(struct fp_img *img);
 180 int fp_img_save_to_file(struct fp_img *img, char *path);
 181 void fp_img_standardize(struct fp_img *img);
 182 void fp_img_free(struct fp_img *img);
 183
 184 /* Library */
 185 int fp_init(void);
 186 void fp_exit(void);
 187
 188 #endif
 189