libfprint
fprint.h
00001 /*
00002  * Main definitions for libfprint
00003  * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it under the terms of the GNU Lesser General Public
00007  * License as published by the Free Software Foundation; either
00008  * version 2.1 of the License, or (at your option) any later version.
00009  *
00010  * This library is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  * Lesser General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU Lesser General Public
00016  * License along with this library; if not, write to the Free Software
00017  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
00018  */
00019 
00020 #ifndef __FPRINT_H__
00021 #define __FPRINT_H__
00022 
00023 #ifdef __cplusplus
00024 extern "C" {
00025 #endif
00026 
00027 #include <stdint.h>
00028 #include <sys/time.h>
00029 
00030 /* structs that applications are not allowed to peek into */
00031 struct fp_dscv_dev;
00032 struct fp_dscv_print;
00033 struct fp_dev;
00034 struct fp_driver;
00035 struct fp_print_data;
00036 struct fp_img;
00037 
00038 /* misc/general stuff */
00039 
00045 enum fp_finger {
00046     LEFT_THUMB = 1, 
00047     LEFT_INDEX, 
00048     LEFT_MIDDLE, 
00049     LEFT_RING, 
00050     LEFT_LITTLE, 
00051     RIGHT_THUMB, 
00052     RIGHT_INDEX, 
00053     RIGHT_MIDDLE, 
00054     RIGHT_RING, 
00055     RIGHT_LITTLE, 
00056 };
00057 
00063 enum fp_scan_type {
00064     FP_SCAN_TYPE_PRESS = 0, 
00065     FP_SCAN_TYPE_SWIPE, 
00066 };
00067 
00068 /* Drivers */
00069 const char *fp_driver_get_name(struct fp_driver *drv);
00070 const char *fp_driver_get_full_name(struct fp_driver *drv);
00071 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
00072 enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv);
00073 
00074 /* Device discovery */
00075 struct fp_dscv_dev **fp_discover_devs(void);
00076 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
00077 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
00078 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
00079 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
00080     struct fp_print_data *print);
00081 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
00082     struct fp_dscv_print *print);
00083 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
00084     struct fp_print_data *print);
00085 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
00086     struct fp_dscv_print *print);
00087 
00088 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
00089 {
00090     return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
00091 }
00092 
00093 /* Print discovery */
00094 struct fp_dscv_print **fp_discover_prints(void);
00095 void fp_dscv_prints_free(struct fp_dscv_print **prints);
00096 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
00097 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
00098 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
00099 int fp_dscv_print_delete(struct fp_dscv_print *print);
00100 
00101 /* Device handling */
00102 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
00103 void fp_dev_close(struct fp_dev *dev);
00104 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
00105 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
00106 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
00107 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
00108 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
00109 
00110 int fp_dev_supports_imaging(struct fp_dev *dev);
00111 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
00112     struct fp_img **image);
00113 int fp_dev_get_img_width(struct fp_dev *dev);
00114 int fp_dev_get_img_height(struct fp_dev *dev);
00115 
00124 enum fp_enroll_result {
00127     FP_ENROLL_COMPLETE = 1,
00130     FP_ENROLL_FAIL,
00132     FP_ENROLL_PASS,
00135     FP_ENROLL_RETRY = 100,
00138     FP_ENROLL_RETRY_TOO_SHORT,
00141     FP_ENROLL_RETRY_CENTER_FINGER,
00145     FP_ENROLL_RETRY_REMOVE_FINGER,
00146 };
00147 
00148 int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
00149     struct fp_img **img);
00150 
00162 static inline int fp_enroll_finger(struct fp_dev *dev,
00163     struct fp_print_data **print_data)
00164 {
00165     return fp_enroll_finger_img(dev, print_data, NULL);
00166 }
00167 
00175 enum fp_verify_result {
00180     FP_VERIFY_NO_MATCH = 0,
00184     FP_VERIFY_MATCH = 1,
00187     FP_VERIFY_RETRY = FP_ENROLL_RETRY,
00189     FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
00192     FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
00195     FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
00196 };
00197 
00198 int fp_verify_finger_img(struct fp_dev *dev,
00199     struct fp_print_data *enrolled_print, struct fp_img **img);
00200 
00211 static inline int fp_verify_finger(struct fp_dev *dev,
00212     struct fp_print_data *enrolled_print)
00213 {
00214     return fp_verify_finger_img(dev, enrolled_print, NULL);
00215 }
00216 
00217 int fp_dev_supports_identification(struct fp_dev *dev);
00218 int fp_identify_finger_img(struct fp_dev *dev,
00219     struct fp_print_data **print_gallery, size_t *match_offset,
00220     struct fp_img **img);
00221 
00237 static inline int fp_identify_finger(struct fp_dev *dev,
00238     struct fp_print_data **print_gallery, size_t *match_offset)
00239 {
00240     return fp_identify_finger_img(dev, print_gallery, match_offset, NULL);
00241 }
00242 
00243 /* Data handling */
00244 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
00245     struct fp_print_data **data);
00246 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
00247     struct fp_print_data **data);
00248 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
00249 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
00250 void fp_print_data_free(struct fp_print_data *data);
00251 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
00252 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
00253     size_t buflen);
00254 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
00255 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
00256 
00257 /* Image handling */
00258 
00260 struct fp_minutia {
00261     int x;
00262     int y;
00263     int ex;
00264     int ey;
00265     int direction;
00266     double reliability;
00267     int type;
00268     int appearing;
00269     int feature_id;
00270     int *nbrs;
00271     int *ridge_counts;
00272     int num_nbrs;
00273 };
00274 
00275 int fp_img_get_height(struct fp_img *img);
00276 int fp_img_get_width(struct fp_img *img);
00277 unsigned char *fp_img_get_data(struct fp_img *img);
00278 int fp_img_save_to_file(struct fp_img *img, char *path);
00279 void fp_img_standardize(struct fp_img *img);
00280 struct fp_img *fp_img_binarize(struct fp_img *img);
00281 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
00282 void fp_img_free(struct fp_img *img);
00283 
00284 /* Polling and timing */
00285 
00286 struct fp_pollfd {
00287     int fd;
00288     short events;
00289 };
00290 
00291 int fp_handle_events_timeout(struct timeval *timeout);
00292 int fp_handle_events(void);
00293 size_t fp_get_pollfds(struct fp_pollfd **pollfds);
00294 int fp_get_next_timeout(struct timeval *tv);
00295 
00296 typedef void (*fp_pollfd_added_cb)(int fd, short events);
00297 typedef void (*fp_pollfd_removed_cb)(int fd);
00298 void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
00299     fp_pollfd_removed_cb removed_cb);
00300 
00301 /* Library */
00302 int fp_init(void);
00303 void fp_exit(void);
00304 void fp_set_debug(int level);
00305 
00306 /* Asynchronous I/O */
00307 
00308 typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data);
00309 int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
00310     void *user_data);
00311 
00312 typedef void (*fp_dev_close_cb)(struct fp_dev *dev, void *user_data);
00313 void fp_async_dev_close(struct fp_dev *dev, fp_dev_close_cb callback,
00314     void *user_data);
00315 
00316 typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result,
00317     struct fp_print_data *print, struct fp_img *img, void *user_data);
00318 int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback,
00319     void *user_data);
00320 
00321 typedef void (*fp_enroll_stop_cb)(struct fp_dev *dev, void *user_data);
00322 int fp_async_enroll_stop(struct fp_dev *dev, fp_enroll_stop_cb callback,
00323     void *user_data);
00324 
00325 typedef void (*fp_verify_cb)(struct fp_dev *dev, int result,
00326     struct fp_img *img, void *user_data);
00327 int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data,
00328     fp_verify_cb callback, void *user_data);
00329 
00330 typedef void (*fp_verify_stop_cb)(struct fp_dev *dev, void *user_data);
00331 int fp_async_verify_stop(struct fp_dev *dev, fp_verify_stop_cb callback,
00332     void *user_data);
00333 
00334 typedef void (*fp_identify_cb)(struct fp_dev *dev, int result,
00335     size_t match_offset, struct fp_img *img, void *user_data);
00336 int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery,
00337     fp_identify_cb callback, void *user_data);
00338 
00339 typedef void (*fp_identify_stop_cb)(struct fp_dev *dev, void *user_data);
00340 int fp_async_identify_stop(struct fp_dev *dev, fp_identify_stop_cb callback,
00341     void *user_data);
00342 
00343 #ifdef __cplusplus
00344 }
00345 #endif
00346 
00347 #endif
00348