/* * Main definitions for libfprint * Copyright (C) 2007 Daniel Drake * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef __FPRINT_H__ #define __FPRINT_H__ #ifdef __cplusplus extern "C" { #endif #include #include #include #include /** * LIBFPRINT_DEPRECATED: * * Expands to the GNU C deprecated attribute if the compiler is `gcc`. When * called with the `-Wdeprecated-declarations` option, `gcc` will generate warnings * when deprecated interfaces are used. */ #define LIBFPRINT_DEPRECATED __attribute__((__deprecated__)) /** * fp_dscv_dev: * * #fp_dscv_dev is an opaque structure type. You must access it using the * functions in this section. */ struct fp_dscv_dev; /** * fp_dscv_print: * * #fp_dscv_print is an opaque structure type. You must access it using the * functions in this section. */ struct fp_dscv_print; /** * fp_dev: * * #fp_dev is an opaque structure type. You must access it using the * functions in this section. */ struct fp_dev; /** * fp_driver: * * #fp_driver is an opaque structure type. You must access it using the * functions in this section. */ struct fp_driver; /** * fp_print_data: * * #fp_print_data is an opaque structure type. You must access it using the * functions in this section. */ struct fp_print_data; /** * fp_img: * * #fp_img is an opaque structure type. You must access it using the * functions in this section. */ struct fp_img; /* misc/general stuff */ /** * fp_finger: * @LEFT_THUMB: Left thumb * @LEFT_INDEX: Left index finger * @LEFT_MIDDLE: Left middle finger * @LEFT_RING: Left ring finger * @LEFT_LITTLE: Left little finger * @RIGHT_THUMB: Right thumb * @RIGHT_INDEX: Right index finger * @RIGHT_MIDDLE: Right middle finger * @RIGHT_RING: Right ring finger * @RIGHT_LITTLE: Right little finger * * Numeric codes used to refer to fingers (and thumbs) of a human. These are * purposely not available as strings, to avoid getting the library tangled up * in localization efforts. */ enum fp_finger { LEFT_THUMB = 1, LEFT_INDEX, LEFT_MIDDLE, LEFT_RING, LEFT_LITTLE, RIGHT_THUMB, RIGHT_INDEX, RIGHT_MIDDLE, RIGHT_RING, RIGHT_LITTLE, }; /** * fp_scan_type: * @FP_SCAN_TYPE_PRESS: the reader has a surface area that covers the whole finger * @FP_SCAN_TYPE_SWIPE: the reader requires swiping the finger on a smaller area * * Numeric codes used to refer to the scan type of the device. Devices require * either swiping or pressing the finger on the device. This is useful for * front-ends. */ enum fp_scan_type { FP_SCAN_TYPE_PRESS = 0, FP_SCAN_TYPE_SWIPE, }; /* Drivers */ const char *fp_driver_get_name(struct fp_driver *drv); const char *fp_driver_get_full_name(struct fp_driver *drv); uint16_t fp_driver_get_driver_id(struct fp_driver *drv); enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv); int fp_driver_supports_imaging(struct fp_driver *drv); /* Device discovery */ struct fp_dscv_dev **fp_discover_devs(void); void fp_dscv_devs_free(struct fp_dscv_dev **devs); struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev); uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev); uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev); int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev, struct fp_print_data *print); int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev, struct fp_dscv_print *print) LIBFPRINT_DEPRECATED; struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs, struct fp_print_data *print) LIBFPRINT_DEPRECATED; struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs, struct fp_dscv_print *print) LIBFPRINT_DEPRECATED; /* Print discovery */ struct fp_dscv_print **fp_discover_prints(void) LIBFPRINT_DEPRECATED; void fp_dscv_prints_free(struct fp_dscv_print **prints) LIBFPRINT_DEPRECATED; uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED; uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED; enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED; int fp_dscv_print_delete(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED; /* Device handling */ struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev); void fp_dev_close(struct fp_dev *dev); struct fp_driver *fp_dev_get_driver(struct fp_dev *dev); int fp_dev_get_nr_enroll_stages(struct fp_dev *dev); uint32_t fp_dev_get_devtype(struct fp_dev *dev); int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data); int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print) LIBFPRINT_DEPRECATED; /** * fp_capture_result: * @FP_CAPTURE_COMPLETE: Capture completed successfully, the capture data has been returned to the caller. * @FP_CAPTURE_FAIL: Capture failed * * Whether a capture failed or completed. */ enum fp_capture_result { FP_CAPTURE_COMPLETE = 0, FP_CAPTURE_FAIL, }; int fp_dev_supports_imaging(struct fp_dev *dev); int fp_dev_img_capture(struct fp_dev *dev, int unconditional, struct fp_img **img); int fp_dev_get_img_width(struct fp_dev *dev); int fp_dev_get_img_height(struct fp_dev *dev); /** * fp_enroll_result: * @FP_ENROLL_COMPLETE: Enrollment completed successfully, the enrollment data has been * returned to the caller. * @FP_ENROLL_FAIL: Enrollment failed due to incomprehensible data; this may occur when * the user scans a different finger on each enroll stage. * @FP_ENROLL_PASS: Enroll stage passed; more stages are need to complete the process. * @FP_ENROLL_RETRY: The enrollment scan did not succeed due to poor scan quality or * other general user scanning problem. * @FP_ENROLL_RETRY_TOO_SHORT: The enrollment scan did not succeed because the finger swipe was * too short. * @FP_ENROLL_RETRY_CENTER_FINGER: The enrollment scan did not succeed because the finger was not * centered on the scanner. * @FP_ENROLL_RETRY_REMOVE_FINGER: The verification scan did not succeed due to quality or pressure * problems; the user should remove their finger from the scanner before * retrying. * * * Enrollment result codes returned from fp_enroll_finger(). * Result codes with RETRY in the name suggest that the scan failed due to * user error. Applications will generally want to inform the user of the * problem and then retry the enrollment stage. For more info on the semantics * of interpreting these result codes and tracking enrollment process, see * [Enrolling](libfprint-Devices-operations.html#enrolling) */ enum fp_enroll_result { FP_ENROLL_COMPLETE = 1, FP_ENROLL_FAIL, FP_ENROLL_PASS, FP_ENROLL_RETRY = 100, FP_ENROLL_RETRY_TOO_SHORT, FP_ENROLL_RETRY_CENTER_FINGER, FP_ENROLL_RETRY_REMOVE_FINGER, }; int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data, struct fp_img **img); int fp_enroll_finger(struct fp_dev *dev, struct fp_print_data **print_data); /** * fp_verify_result: * @FP_VERIFY_NO_MATCH: The scan completed successfully, but the newly scanned fingerprint * does not match the fingerprint being verified against. * In the case of identification, this return code indicates that the * scanned finger could not be found in the print gallery. * @FP_VERIFY_MATCH: The scan completed successfully and the newly scanned fingerprint does * match the fingerprint being verified, or in the case of identification, * the scanned fingerprint was found in the print gallery. * @FP_VERIFY_RETRY: The scan did not succeed due to poor scan quality or other general * user scanning problem. * @FP_VERIFY_RETRY_TOO_SHORT: The scan did not succeed because the finger swipe was too short. * @FP_VERIFY_RETRY_CENTER_FINGER: The scan did not succeed because the finger was not centered on the * scanner. * @FP_VERIFY_RETRY_REMOVE_FINGER: The scan did not succeed due to quality or pressure problems; the user * should remove their finger from the scanner before retrying. * * Verification result codes returned from fp_verify_finger(). Return codes * are also shared with fp_identify_finger(). * Result codes with RETRY in the name suggest that the scan failed due to * user error. Applications will generally want to inform the user of the * problem and then retry the verify operation. */ enum fp_verify_result { FP_VERIFY_NO_MATCH = 0, FP_VERIFY_MATCH = 1, FP_VERIFY_RETRY = FP_ENROLL_RETRY, FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT, FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER, FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER, }; int fp_verify_finger_img(struct fp_dev *dev, struct fp_print_data *enrolled_print, struct fp_img **img); int fp_verify_finger(struct fp_dev *dev, struct fp_print_data *enrolled_print); int fp_dev_supports_identification(struct fp_dev *dev); int fp_identify_finger_img(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset, struct fp_img **img); int fp_identify_finger(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset); /* Data handling */ int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger, struct fp_print_data **data) LIBFPRINT_DEPRECATED; int fp_print_data_from_dscv_print(struct fp_dscv_print *print, struct fp_print_data **data) LIBFPRINT_DEPRECATED; int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger) LIBFPRINT_DEPRECATED; int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger) LIBFPRINT_DEPRECATED; void fp_print_data_free(struct fp_print_data *data); size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret); struct fp_print_data *fp_print_data_from_data(unsigned char *buf, size_t buflen); uint16_t fp_print_data_get_driver_id(struct fp_print_data *data); uint32_t fp_print_data_get_devtype(struct fp_print_data *data); /* Image handling */ /** * fp_minutia: * * #fp_minutia is an opaque structure type. You must access it using the * functions in this section. */ struct fp_minutia; int fp_img_get_height(struct fp_img *img); int fp_img_get_width(struct fp_img *img); unsigned char *fp_img_get_data(struct fp_img *img); int fp_img_save_to_file(struct fp_img *img, char *path); void fp_img_standardize(struct fp_img *img); struct fp_img *fp_img_binarize(struct fp_img *img); struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae); int fp_minutia_get_coords(struct fp_minutia *minutia, int *coord_x, int *coord_y); void fp_img_free(struct fp_img *img); /* Polling and timing */ /** * fp_pollfd: * @fd: a file descriptor * @events: Event flags to poll for from `` * * A structure representing a file descriptor and the @events to poll * for, as returned by fp_get_pollfds(). */ struct fp_pollfd { int fd; short int events; }; int fp_handle_events_timeout(struct timeval *timeout); int fp_handle_events(void); ssize_t fp_get_pollfds(struct fp_pollfd **pollfds); int fp_get_next_timeout(struct timeval *tv); /** * fp_pollfd_added_cb: * @fd: the new file descriptor * @events: events to monitor for, see `` for the possible values * * Type definition for a function that will be called when a new * event source is added. The @events argument is a flag as defined in * `` such as `POLLIN`, or `POLLOUT`. See fp_set_pollfd_notifiers(). */ typedef void (*fp_pollfd_added_cb)(int fd, short int events); /** * fp_pollfd_removed_cb: * @fd: the file descriptor to stop monitoring * * Type definition for a function that will be called when an * event source is removed. See fp_set_pollfd_notifiers(). */ typedef void (*fp_pollfd_removed_cb)(int fd); void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb, fp_pollfd_removed_cb removed_cb); /* Library */ int fp_init(void); void fp_exit(void); void fp_set_debug(int level) LIBFPRINT_DEPRECATED; /* Asynchronous I/O */ /** * fp_operation_stop_cb: * @dev: the struct #fp_dev device * @user_data: user data passed to the callback * * Type definition for a function that will be called when fp_async_dev_close(), * fp_async_verify_stop(), fp_async_identify_stop() or fp_async_capture_stop() * finishes. */ typedef void (*fp_operation_stop_cb)(struct fp_dev *dev, void *user_data); /** * fp_img_operation_cb: * @dev: the struct #fp_dev device * @result: an #fp_verify_result for fp_async_verify_start(), or an #fp_capture_result * for fp_async_capture_start(), or a negative value on error * @img: the captured #fp_img if capture or verification was successful * @user_data: user data passed to the callback * * Type definition for a function that will be called when fp_async_verify_start() * or fp_async_capture_start() finished. */ typedef void (*fp_img_operation_cb)(struct fp_dev *dev, int result, struct fp_img *img, void *user_data); /** * fp_dev_open_cb: * @dev: the struct #fp_dev device * @status: 0 on success, or a negative value on error * @user_data: user data passed to the callback * * Type definition for a function that will be called when fp_async_dev_open * finishes. */ typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data); int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback, void *user_data); void fp_async_dev_close(struct fp_dev *dev, fp_operation_stop_cb callback, void *user_data); /** * fp_enroll_stage_cb: * @dev: the struct #fp_dev device * @result: a #fp_enroll_result on success, or a negative value on failure * @print: the enrollment data from the final stage * @img: an #fp_img to free with fp_img_free() * @user_data: user data passed to the callback * * Type definition for a function that will be called when * fp_async_enroll_start() finishes. See fp_enroll_finger_img() for * the expected behaviour of your program based on the @result. */ typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result, struct fp_print_data *print, struct fp_img *img, void *user_data); int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback, void *user_data); int fp_async_enroll_stop(struct fp_dev *dev, fp_operation_stop_cb callback, void *user_data); int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data, fp_img_operation_cb callback, void *user_data); int fp_async_verify_stop(struct fp_dev *dev, fp_operation_stop_cb callback, void *user_data); /** * fp_identify_cb: * @dev: the struct #fp_dev device * @result: a #fp_verify_result on success, or a negative value on error. * @match_offset: the array index of the matched gallery print (if any was found). * Only valid if %FP_VERIFY_MATCH was returned. * @img: the scan image, it must be freed with fp_img_free() after use. * @user_data: user data passed to the callback * * Type definition for a function that will be called when fp_async_identify_start() * finishes. */ typedef void (*fp_identify_cb)(struct fp_dev *dev, int result, size_t match_offset, struct fp_img *img, void *user_data); int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery, fp_identify_cb callback, void *user_data); int fp_async_identify_stop(struct fp_dev *dev, fp_operation_stop_cb callback, void *user_data); int fp_async_capture_start(struct fp_dev *dev, int unconditional, fp_img_operation_cb callback, void *user_data); int fp_async_capture_stop(struct fp_dev *dev, fp_operation_stop_cb callback, void *user_data); #ifdef __cplusplus } #endif #endif