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 #include <stdint.h>
00024 #include <sys/time.h>
00025 
00026 /* structs that applications are not allowed to peek into */
00027 struct fp_dscv_dev;
00028 struct fp_dscv_print;
00029 struct fp_dev;
00030 struct fp_driver;
00031 struct fp_print_data;
00032 struct fp_img;
00033 
00034 /* misc/general stuff */
00035 
00041 enum fp_finger {
00042     LEFT_THUMB = 1, 
00043     LEFT_INDEX, 
00044     LEFT_MIDDLE, 
00045     LEFT_RING, 
00046     LEFT_LITTLE, 
00047     RIGHT_THUMB, 
00048     RIGHT_INDEX, 
00049     RIGHT_MIDDLE, 
00050     RIGHT_RING, 
00051     RIGHT_LITTLE, 
00052 };
00053 
00059 enum fp_scan_type {
00060     FP_SCAN_TYPE_PRESS = 0, 
00061     FP_SCAN_TYPE_SWIPE, 
00062 };
00063 
00064 /* Drivers */
00065 const char *fp_driver_get_name(struct fp_driver *drv);
00066 const char *fp_driver_get_full_name(struct fp_driver *drv);
00067 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
00068 enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv);
00069 
00070 /* Device discovery */
00071 struct fp_dscv_dev **fp_discover_devs(void);
00072 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
00073 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
00074 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
00075 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
00076     struct fp_print_data *print);
00077 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
00078     struct fp_dscv_print *print);
00079 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
00080     struct fp_print_data *print);
00081 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
00082     struct fp_dscv_print *print);
00083 
00084 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
00085 {
00086     return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
00087 }
00088 
00089 /* Print discovery */
00090 struct fp_dscv_print **fp_discover_prints(void);
00091 void fp_dscv_prints_free(struct fp_dscv_print **prints);
00092 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
00093 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
00094 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
00095 int fp_dscv_print_delete(struct fp_dscv_print *print);
00096 
00097 /* Device handling */
00098 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
00099 void fp_dev_close(struct fp_dev *dev);
00100 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
00101 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
00102 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
00103 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
00104 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
00105 
00106 int fp_dev_supports_imaging(struct fp_dev *dev);
00107 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
00108     struct fp_img **image);
00109 int fp_dev_get_img_width(struct fp_dev *dev);
00110 int fp_dev_get_img_height(struct fp_dev *dev);
00111 
00120 enum fp_enroll_result {
00123     FP_ENROLL_COMPLETE = 1,
00126     FP_ENROLL_FAIL,
00128     FP_ENROLL_PASS,
00131     FP_ENROLL_RETRY = 100,
00134     FP_ENROLL_RETRY_TOO_SHORT,
00137     FP_ENROLL_RETRY_CENTER_FINGER,
00141     FP_ENROLL_RETRY_REMOVE_FINGER,
00142 };
00143 
00144 int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
00145     struct fp_img **img);
00146 
00158 static inline int fp_enroll_finger(struct fp_dev *dev,
00159     struct fp_print_data **print_data)
00160 {
00161     return fp_enroll_finger_img(dev, print_data, NULL);
00162 }
00163 
00171 enum fp_verify_result {
00176     FP_VERIFY_NO_MATCH = 0,
00180     FP_VERIFY_MATCH = 1,
00183     FP_VERIFY_RETRY = FP_ENROLL_RETRY,
00185     FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
00188     FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
00191     FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
00192 };
00193 
00194 int fp_verify_finger_img(struct fp_dev *dev,
00195     struct fp_print_data *enrolled_print, struct fp_img **img);
00196 
00207 static inline int fp_verify_finger(struct fp_dev *dev,
00208     struct fp_print_data *enrolled_print)
00209 {
00210     return fp_verify_finger_img(dev, enrolled_print, NULL);
00211 }
00212 
00213 int fp_dev_supports_identification(struct fp_dev *dev);
00214 int fp_identify_finger_img(struct fp_dev *dev,
00215     struct fp_print_data **print_gallery, size_t *match_offset,
00216     struct fp_img **img);
00217 
00233 static inline int fp_identify_finger(struct fp_dev *dev,
00234     struct fp_print_data **print_gallery, size_t *match_offset)
00235 {
00236     return fp_identify_finger_img(dev, print_gallery, match_offset, NULL);
00237 }
00238 
00239 /* Data handling */
00240 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
00241     struct fp_print_data **data);
00242 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
00243     struct fp_print_data **data);
00244 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
00245 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
00246 void fp_print_data_free(struct fp_print_data *data);
00247 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
00248 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
00249     size_t buflen);
00250 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
00251 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
00252 
00253 /* Image handling */
00254 
00256 struct fp_minutia {
00257     int x;
00258     int y;
00259     int ex;
00260     int ey;
00261     int direction;
00262     double reliability;
00263     int type;
00264     int appearing;
00265     int feature_id;
00266     int *nbrs;
00267     int *ridge_counts;
00268     int num_nbrs;
00269 };
00270 
00271 int fp_img_get_height(struct fp_img *img);
00272 int fp_img_get_width(struct fp_img *img);
00273 unsigned char *fp_img_get_data(struct fp_img *img);
00274 int fp_img_save_to_file(struct fp_img *img, char *path);
00275 void fp_img_standardize(struct fp_img *img);
00276 struct fp_img *fp_img_binarize(struct fp_img *img);
00277 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
00278 void fp_img_free(struct fp_img *img);
00279 
00280 /* Polling and timing */
00281 
00282 struct fp_pollfd {
00283     int fd;
00284     short events;
00285 };
00286 
00287 int fp_handle_events_timeout(struct timeval *timeout);
00288 int fp_handle_events(void);
00289 size_t fp_get_pollfds(struct fp_pollfd **pollfds);
00290 int fp_get_next_timeout(struct timeval *tv);
00291 
00292 typedef void (*fp_pollfd_added_cb)(int fd, short events);
00293 typedef void (*fp_pollfd_removed_cb)(int fd);
00294 void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
00295     fp_pollfd_removed_cb removed_cb);
00296 
00297 /* Library */
00298 int fp_init(void);
00299 void fp_exit(void);
00300 void fp_set_debug(int level);
00301 
00302 /* Asynchronous I/O */
00303 
00304 typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data);
00305 int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
00306     void *user_data);
00307 
00308 typedef void (*fp_dev_close_cb)(struct fp_dev *dev, void *user_data);
00309 void fp_async_dev_close(struct fp_dev *dev, fp_dev_close_cb callback,
00310     void *user_data);
00311 
00312 typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result,
00313     struct fp_print_data *print, struct fp_img *img, void *user_data);
00314 int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback,
00315     void *user_data);
00316 
00317 typedef void (*fp_enroll_stop_cb)(struct fp_dev *dev, void *user_data);
00318 int fp_async_enroll_stop(struct fp_dev *dev, fp_enroll_stop_cb callback,
00319     void *user_data);
00320 
00321 typedef void (*fp_verify_cb)(struct fp_dev *dev, int result,
00322     struct fp_img *img, void *user_data);
00323 int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data,
00324     fp_verify_cb callback, void *user_data);
00325 
00326 typedef void (*fp_verify_stop_cb)(struct fp_dev *dev, void *user_data);
00327 int fp_async_verify_stop(struct fp_dev *dev, fp_verify_stop_cb callback,
00328     void *user_data);
00329 
00330 typedef void (*fp_identify_cb)(struct fp_dev *dev, int result,
00331     size_t match_offset, struct fp_img *img, void *user_data);
00332 int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery,
00333     fp_identify_cb callback, void *user_data);
00334 
00335 typedef void (*fp_identify_stop_cb)(struct fp_dev *dev, void *user_data);
00336 int fp_async_identify_stop(struct fp_dev *dev, fp_identify_stop_cb callback,
00337     void *user_data);
00338 
00339 #endif
00340