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 #include <sys/time.h>
  25
  26 /* structs that applications are not allowed to peek into */
  27 struct fp_dscv_dev;
  28 struct fp_dscv_print;
  29 struct fp_dev;
  30 struct fp_driver;
  31 struct fp_print_data;
  32 struct fp_img;
  33
  34 /* misc/general stuff */
  35
  36 /** \ingroup print_data
  37  * Numeric codes used to refer to fingers (and thumbs) of a human. These are
  38  * purposely not available as strings, to avoid getting the library tangled up
  39  * in localization efforts.
  40  */
  41 enum fp_finger {
  42         LEFT_THUMB = 1, /** thumb (left hand) */
  43         LEFT_INDEX, /** index finger (left hand) */
  44         LEFT_MIDDLE, /** middle finger (left hand) */
  45         LEFT_RING, /** ring finger (left hand) */
  46         LEFT_LITTLE, /** little finger (left hand) */
  47         RIGHT_THUMB, /** thumb (right hand) */
  48         RIGHT_INDEX, /** index finger (right hand) */
  49         RIGHT_MIDDLE, /** middle finger (right hand) */
  50         RIGHT_RING, /** ring finger (right hand) */
  51         RIGHT_LITTLE, /** little finger (right hand) */
  52 };
  53
  54 /* Drivers */
  55 const char *fp_driver_get_name(struct fp_driver *drv);
  56 const char *fp_driver_get_full_name(struct fp_driver *drv);
  57 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
  58
  59 /* Device discovery */
  60 struct fp_dscv_dev **fp_discover_devs(void);
  61 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
  62 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
  63 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
  64 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
  65         struct fp_print_data *print);
  66 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
  67         struct fp_dscv_print *print);
  68 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
  69         struct fp_print_data *print);
  70 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
  71         struct fp_dscv_print *print);
  72
  73 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
  74 {
  75         return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
  76 }
  77
  78 /* Print discovery */
  79 struct fp_dscv_print **fp_discover_prints(void);
  80 void fp_dscv_prints_free(struct fp_dscv_print **prints);
  81 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
  82 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
  83 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
  84 int fp_dscv_print_delete(struct fp_dscv_print *print);
  85
  86 /* Device handling */
  87 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
  88 void fp_dev_close(struct fp_dev *dev);
  89 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
  90 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
  91 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
  92 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
  93 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
  94
  95 int fp_dev_supports_imaging(struct fp_dev *dev);
  96 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
  97         struct fp_img **image);
  98 int fp_dev_get_img_width(struct fp_dev *dev);
  99 int fp_dev_get_img_height(struct fp_dev *dev);
 100
 101 /** \ingroup dev
 102  * Enrollment result codes returned from fp_enroll_finger().
 103  * Result codes with RETRY in the name suggest that the scan failed due to
 104  * user error. Applications will generally want to inform the user of the
 105  * problem and then retry the enrollment stage. For more info on the semantics
 106  * of interpreting these result codes and tracking enrollment process, see
 107  * \ref enrolling.
 108  */
 109 enum fp_enroll_result {
 110         /** Enrollment completed successfully, the enrollment data has been
 111          * returned to the caller. */
 112         FP_ENROLL_COMPLETE = 1,
 113         /** Enrollment failed due to incomprehensible data; this may occur when
 114          * the user scans a different finger on each enroll stage. */
 115         FP_ENROLL_FAIL,
 116         /** Enroll stage passed; more stages are need to complete the process. */
 117         FP_ENROLL_PASS,
 118         /** The enrollment scan did not succeed due to poor scan quality or
 119          * other general user scanning problem. */
 120         FP_ENROLL_RETRY = 100,
 121         /** The enrollment scan did not succeed because the finger swipe was
 122          * too short. */
 123         FP_ENROLL_RETRY_TOO_SHORT,
 124         /** The enrollment scan did not succeed because the finger was not
 125          * centered on the scanner. */
 126         FP_ENROLL_RETRY_CENTER_FINGER,
 127         /** The verification scan did not succeed due to quality or pressure
 128          * problems; the user should remove their finger from the scanner before
 129          * retrying. */
 130         FP_ENROLL_RETRY_REMOVE_FINGER,
 131 };
 132
 133 int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
 134         struct fp_img **img);
 135
 136 /** \ingroup dev
 137  * Performs an enroll stage. See \ref enrolling for an explanation of enroll
 138  * stages. This function is just a shortcut to calling fp_enroll_finger_img()
 139  * with a NULL image parameter. Be sure to read the description of
 140  * fp_enroll_finger_img() in order to understand its behaviour.
 141  *
 142  * \param dev the device
 143  * \param print_data a location to return the resultant enrollment data from
 144  * the final stage. Must be freed with fp_print_data_free() after use.
 145  * \return negative code on error, otherwise a code from #fp_enroll_result
 146  */
 147 static inline int fp_enroll_finger(struct fp_dev *dev,
 148         struct fp_print_data **print_data)
 149 {
 150         return fp_enroll_finger_img(dev, print_data, NULL);
 151 }
 152
 153 /** \ingroup dev
 154  * Verification result codes returned from fp_verify_finger(). Return codes
 155  * are also shared with fp_identify_finger().
 156  * Result codes with RETRY in the name suggest that the scan failed due to
 157  * user error. Applications will generally want to inform the user of the
 158  * problem and then retry the verify operation.
 159  */
 160 enum fp_verify_result {
 161         /** The scan completed successfully, but the newly scanned fingerprint
 162          * does not match the fingerprint being verified against.
 163          * In the case of identification, this return code indicates that the
 164          * scanned finger could not be found in the print gallery. */
 165         FP_VERIFY_NO_MATCH = 0,
 166         /** The scan completed successfully and the newly scanned fingerprint does
 167          * match the fingerprint being verified, or in the case of identification,
 168          * the scanned fingerprint was found in the print gallery. */
 169         FP_VERIFY_MATCH = 1,
 170         /** The scan did not succeed due to poor scan quality or other general
 171          * user scanning problem. */
 172         FP_VERIFY_RETRY = FP_ENROLL_RETRY,
 173         /** The scan did not succeed because the finger swipe was too short. */
 174         FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
 175         /** The scan did not succeed because the finger was not centered on the
 176          * scanner. */
 177         FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
 178         /** The scan did not succeed due to quality or pressure problems; the user
 179          * should remove their finger from the scanner before retrying. */
 180         FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
 181 };
 182
 183 int fp_verify_finger_img(struct fp_dev *dev,
 184         struct fp_print_data *enrolled_print, struct fp_img **img);
 185
 186 /** \ingroup dev
 187  * Performs a new scan and verify it against a previously enrolled print. This
 188  * function is just a shortcut to calling fp_verify_finger_img() with a NULL
 189  * image output parameter.
 190  * \param dev the device to perform the scan.
 191  * \param enrolled_print the print to verify against. Must have been previously
 192  * enrolled with a device compatible to the device selected to perform the scan.
 193  * \return negative code on error, otherwise a code from #fp_verify_result
 194  * \sa fp_verify_finger_img()
 195  */
 196 static inline int fp_verify_finger(struct fp_dev *dev,
 197         struct fp_print_data *enrolled_print)
 198 {
 199         return fp_verify_finger_img(dev, enrolled_print, NULL);
 200 }
 201
 202 int fp_dev_supports_identification(struct fp_dev *dev);
 203 int fp_identify_finger_img(struct fp_dev *dev,
 204         struct fp_print_data **print_gallery, size_t *match_offset,
 205         struct fp_img **img);
 206
 207 /** \ingroup dev
 208  * Performs a new scan and attempts to identify the scanned finger against a
 209  * collection of previously enrolled fingerprints. This function is just a
 210  * shortcut to calling fp_identify_finger_img() with a NULL image output
 211  * parameter.
 212  * \param dev the device to perform the scan.
 213  * \param print_gallery NULL-terminated array of pointers to the prints to
 214  * identify against. Each one must have been previously enrolled with a device
 215  * compatible to the device selected to perform the scan.
 216  * \param match_offset output location to store the array index of the matched
 217  * gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
 218  * returned.
 219  * \return negative code on error, otherwise a code from #fp_verify_result
 220  * \sa fp_identify_finger_img()
 221  */
 222 static inline int fp_identify_finger(struct fp_dev *dev,
 223         struct fp_print_data **print_gallery, size_t *match_offset)
 224 {
 225         return fp_identify_finger_img(dev, print_gallery, match_offset, NULL);
 226 }
 227
 228 /* Data handling */
 229 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
 230         struct fp_print_data **data);
 231 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
 232         struct fp_print_data **data);
 233 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
 234 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
 235 void fp_print_data_free(struct fp_print_data *data);
 236 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
 237 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
 238         size_t buflen);
 239 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
 240 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
 241
 242 /* Image handling */
 243
 244 /** \ingroup img */
 245 struct fp_minutia {
 246         int x;
 247         int y;
 248         int ex;
 249         int ey;
 250         int direction;
 251         double reliability;
 252         int type;
 253         int appearing;
 254         int feature_id;
 255         int *nbrs;
 256         int *ridge_counts;
 257         int num_nbrs;
 258 };
 259
 260 int fp_img_get_height(struct fp_img *img);
 261 int fp_img_get_width(struct fp_img *img);
 262 unsigned char *fp_img_get_data(struct fp_img *img);
 263 int fp_img_save_to_file(struct fp_img *img, char *path);
 264 void fp_img_standardize(struct fp_img *img);
 265 struct fp_img *fp_img_binarize(struct fp_img *img);
 266 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
 267 void fp_img_free(struct fp_img *img);
 268
 269 /* Polling and timing */
 270 int fp_handle_events_timeout(struct timeval *timeout);
 271 int fp_handle_events(void);
 272
 273 /* Library */
 274 int fp_init(void);
 275 void fp_exit(void);
 276
 277 /* Asynchronous I/O */
 278
 279 typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data);
 280 int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
 281         void *user_data);
 282
 283 typedef void (*fp_dev_close_cb)(struct fp_dev *dev, void *user_data);
 284 void fp_async_dev_close(struct fp_dev *dev, fp_dev_close_cb callback,
 285         void *user_data);
 286
 287 typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result,
 288         struct fp_print_data *print, struct fp_img *img, void *user_data);
 289 int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback,
 290         void *user_data);
 291
 292 typedef void (*fp_enroll_stop_cb)(struct fp_dev *dev, void *user_data);
 293 int fp_async_enroll_stop(struct fp_dev *dev, fp_enroll_stop_cb callback,
 294         void *user_data);
 295
 296 typedef void (*fp_verify_cb)(struct fp_dev *dev, int result,
 297         struct fp_img *img, void *user_data);
 298 int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data,
 299         fp_verify_cb callback, void *user_data);
 300
 301 typedef void (*fp_verify_stop_cb)(struct fp_dev *dev, void *user_data);
 302 int fp_async_verify_stop(struct fp_dev *dev, fp_verify_stop_cb callback,
 303         void *user_data);
 304
 305 typedef void (*fp_identify_cb)(struct fp_dev *dev, int result,
 306         size_t match_offset, struct fp_img *img, void *user_data);
 307 int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery,
 308         fp_identify_cb callback, void *user_data);
 309
 310 typedef void (*fp_identify_stop_cb)(struct fp_dev *dev, void *user_data);
 311 int fp_async_identify_stop(struct fp_dev *dev, fp_identify_stop_cb callback,
 312         void *user_data);
 313
 314 #endif
 315