0a45ed7af6
The only API user currently seems to be the examples. fprintd has its own storage and that will be a good idea in general. So deprecate the API, we'll need to find a different solution for the examples eventually.
460 lines
16 KiB
C
460 lines
16 KiB
C
/*
|
|
* Main definitions for libfprint
|
|
* Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
|
|
*
|
|
* 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 <stdint.h>
|
|
#include <stddef.h>
|
|
#include <unistd.h>
|
|
#include <sys/time.h>
|
|
|
|
/**
|
|
* 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 `<poll.h>`
|
|
*
|
|
* 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 `<poll.h>` 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
|
|
* `<poll.h>` 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
|
|
|