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 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 #include <stdint.h>
28 #include <sys/time.h>
29 
30 /* structs that applications are not allowed to peek into */
31 struct fp_dscv_dev;
32 struct fp_dscv_print;
33 struct fp_dev;
34 struct fp_driver;
35 struct fp_print_data;
36 struct fp_img;
37 
38 /* misc/general stuff */
39 
45 enum fp_finger {
46  LEFT_THUMB = 1,
56 };
57 
64  FP_SCAN_TYPE_PRESS = 0,
66 };
67 
68 /* Drivers */
69 const char *fp_driver_get_name(struct fp_driver *drv);
70 const char *fp_driver_get_full_name(struct fp_driver *drv);
71 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
72 enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv);
73 
74 /* Device discovery */
75 struct fp_dscv_dev **fp_discover_devs(void);
76 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
77 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
78 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
79 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
80  struct fp_print_data *print);
81 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
82  struct fp_dscv_print *print);
83 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
84  struct fp_print_data *print);
85 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
86  struct fp_dscv_print *print);
87 
88 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
89 {
91 }
92 
93 /* Print discovery */
94 struct fp_dscv_print **fp_discover_prints(void);
95 void fp_dscv_prints_free(struct fp_dscv_print **prints);
96 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
97 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
98 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
99 int fp_dscv_print_delete(struct fp_dscv_print *print);
100 
101 /* Device handling */
102 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
103 void fp_dev_close(struct fp_dev *dev);
104 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
105 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
106 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
107 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
108 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
109 
110 int fp_dev_supports_imaging(struct fp_dev *dev);
111 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
112  struct fp_img **image);
113 int fp_dev_get_img_width(struct fp_dev *dev);
114 int fp_dev_get_img_height(struct fp_dev *dev);
115 
146 };
147 
148 int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
149  struct fp_img **img);
150 
162 static inline int fp_enroll_finger(struct fp_dev *dev,
163  struct fp_print_data **print_data)
164 {
165  return fp_enroll_finger_img(dev, print_data, NULL);
166 }
167 
196 };
197 
198 int fp_verify_finger_img(struct fp_dev *dev,
199  struct fp_print_data *enrolled_print, struct fp_img **img);
200 
211 static inline int fp_verify_finger(struct fp_dev *dev,
212  struct fp_print_data *enrolled_print)
213 {
214  return fp_verify_finger_img(dev, enrolled_print, NULL);
215 }
216 
217 int fp_dev_supports_identification(struct fp_dev *dev);
218 int fp_identify_finger_img(struct fp_dev *dev,
219  struct fp_print_data **print_gallery, size_t *match_offset,
220  struct fp_img **img);
221 
237 static inline int fp_identify_finger(struct fp_dev *dev,
238  struct fp_print_data **print_gallery, size_t *match_offset)
239 {
240  return fp_identify_finger_img(dev, print_gallery, match_offset, NULL);
241 }
242 
243 /* Data handling */
244 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
245  struct fp_print_data **data);
246 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
247  struct fp_print_data **data);
248 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
249 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
250 void fp_print_data_free(struct fp_print_data *data);
251 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
252 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
253  size_t buflen);
254 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
255 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
256 
257 /* Image handling */
258 
260 struct fp_minutia {
261  int x;
262  int y;
263  int ex;
264  int ey;
265  int direction;
266  double reliability;
267  int type;
268  int appearing;
269  int feature_id;
270  int *nbrs;
271  int *ridge_counts;
272  int num_nbrs;
273 };
274 
275 int fp_img_get_height(struct fp_img *img);
276 int fp_img_get_width(struct fp_img *img);
277 unsigned char *fp_img_get_data(struct fp_img *img);
278 int fp_img_save_to_file(struct fp_img *img, char *path);
279 void fp_img_standardize(struct fp_img *img);
280 struct fp_img *fp_img_binarize(struct fp_img *img);
281 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
282 void fp_img_free(struct fp_img *img);
283 
284 /* Polling and timing */
285 
286 struct fp_pollfd {
287  int fd;
288  short events;
289 };
290 
291 int fp_handle_events_timeout(struct timeval *timeout);
292 int fp_handle_events(void);
293 size_t fp_get_pollfds(struct fp_pollfd **pollfds);
294 int fp_get_next_timeout(struct timeval *tv);
295 
296 typedef void (*fp_pollfd_added_cb)(int fd, short events);
297 typedef void (*fp_pollfd_removed_cb)(int fd);
298 void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
299  fp_pollfd_removed_cb removed_cb);
300 
301 /* Library */
302 int fp_init(void);
303 void fp_exit(void);
304 void fp_set_debug(int level);
305 
306 /* Asynchronous I/O */
307 
308 typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data);
309 int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
310  void *user_data);
311 
312 typedef void (*fp_dev_close_cb)(struct fp_dev *dev, void *user_data);
313 void fp_async_dev_close(struct fp_dev *dev, fp_dev_close_cb callback,
314  void *user_data);
315 
316 typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result,
317  struct fp_print_data *print, struct fp_img *img, void *user_data);
318 int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback,
319  void *user_data);
320 
321 typedef void (*fp_enroll_stop_cb)(struct fp_dev *dev, void *user_data);
322 int fp_async_enroll_stop(struct fp_dev *dev, fp_enroll_stop_cb callback,
323  void *user_data);
324 
325 typedef void (*fp_verify_cb)(struct fp_dev *dev, int result,
326  struct fp_img *img, void *user_data);
327 int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data,
328  fp_verify_cb callback, void *user_data);
329 
330 typedef void (*fp_verify_stop_cb)(struct fp_dev *dev, void *user_data);
331 int fp_async_verify_stop(struct fp_dev *dev, fp_verify_stop_cb callback,
332  void *user_data);
333 
334 typedef void (*fp_identify_cb)(struct fp_dev *dev, int result,
335  size_t match_offset, struct fp_img *img, void *user_data);
336 int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery,
337  fp_identify_cb callback, void *user_data);
338 
339 typedef void (*fp_identify_stop_cb)(struct fp_dev *dev, void *user_data);
340 int fp_async_identify_stop(struct fp_dev *dev, fp_identify_stop_cb callback,
341  void *user_data);
342 
343 #ifdef __cplusplus
344 }
345 #endif
346 
347 #endif
348 
enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv)
Retrieves the scan type for the devices associated with the driver.
Definition: core.c:780
The scan did not succeed due to quality or pressure problems; the user should remove their finger fro...
Definition: fprint.h:195
uint32_t fp_print_data_get_devtype(struct fp_print_data *data)
Gets the devtype for a stored print.
Definition: data.c:430
struct fp_dev * fp_dev_open(struct fp_dscv_dev *ddev)
Opens and initialises a device.
Definition: sync.c:47
int fp_handle_events_timeout(struct timeval *timeout)
Handle any pending events.
Definition: poll.c:204
Enroll stage passed; more stages are need to complete the process.
Definition: fprint.h:132
void fp_dev_close(struct fp_dev *dev)
Close a device.
Definition: sync.c:84
void fp_exit(void)
Deinitialise libfprint.
Definition: core.c:962
uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev)
Gets the devtype for a discovered device.
Definition: core.c:599
int fp_img_get_height(struct fp_img *img)
Gets the pixel height of an image.
Definition: img.c:107
static int fp_identify_finger(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset)
Performs a new scan and attempts to identify the scanned finger against a collection of previously en...
Definition: fprint.h:237
int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger)
Saves a stored print to disk, assigned to a specific finger.
Definition: data.c:227
int fp_img_save_to_file(struct fp_img *img, char *path)
A quick convenience function to save an image to a file in PGM format.
Definition: img.c:140
const char * fp_driver_get_name(struct fp_driver *drv)
Retrieves the name of the driver.
Definition: core.c:750
size_t fp_get_pollfds(struct fp_pollfd **pollfds)
Retrieve a list of file descriptors that should be polled for events interesting to libfprint...
Definition: poll.c:300
int fp_dev_img_capture(struct fp_dev *dev, int unconditional, struct fp_img **image)
Captures an image from a device.
Definition: core.c:837
static int fp_enroll_finger(struct fp_dev *dev, struct fp_print_data **print_data)
Performs an enroll stage.
Definition: fprint.h:162
Definition: fprint.h:286
struct fp_dscv_dev ** fp_discover_devs(void)
Scans the system and returns a list of discovered devices.
Definition: core.c:518
int fp_dev_supports_identification(struct fp_dev *dev)
Determines if a device is capable of identification through fp_identify_finger() and similar...
Definition: core.c:814
enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print)
Gets the finger code for a discovered print.
Definition: data.c:661
fp_scan_type
Numeric codes used to refer to the scan type of the device.
Definition: fprint.h:63
int fp_print_data_from_dscv_print(struct fp_dscv_print *print, struct fp_print_data **data)
Attempts to load a stored print based on a discovered print record.
Definition: data.c:397
middle finger (right hand)
Definition: fprint.h:54
index finger (right hand)
Definition: fprint.h:53
The scan completed successfully, but the newly scanned fingerprint does not match the fingerprint bei...
Definition: fprint.h:180
struct fp_img * fp_img_binarize(struct fp_img *img)
Get a binarized form of a standardized scanned image.
Definition: img.c:404
int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data, struct fp_img **img)
Performs an enroll stage.
Definition: sync.c:176
index finger (left hand)
Definition: fprint.h:48
fp_verify_result
Verification result codes returned from fp_verify_finger().
Definition: fprint.h:175
void fp_set_debug(int level)
Set message verbosity.
Definition: core.c:920
uint16_t fp_print_data_get_driver_id(struct fp_print_data *data)
Gets the driver ID for a stored print.
Definition: data.c:419
Definition: fprint.h:260
thumb (left hand)
Definition: fprint.h:47
struct fp_dscv_print ** fp_discover_prints(void)
Scans the users home directory and returns a list of prints that were previously saved using fp_print...
Definition: data.c:554
int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data)
Determines if a stored print is compatible with a certain device.
Definition: core.c:723
void fp_img_standardize(struct fp_img *img)
Standardizes an image by normalizing its orientation, colors, etc.
Definition: img.c:220
int fp_dscv_print_delete(struct fp_dscv_print *print)
Removes a discovered print from disk.
Definition: data.c:674
The scan did not succeed because the finger swipe was too short.
Definition: fprint.h:189
The scan completed successfully and the newly scanned fingerprint does match the fingerprint being ve...
Definition: fprint.h:184
Enrollment completed successfully, the enrollment data has been returned to the caller.
Definition: fprint.h:127
struct fp_minutia ** fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae)
Get a list of minutiae detected in an image.
Definition: img.c:456
middle finger (left hand)
Definition: fprint.h:49
void fp_img_free(struct fp_img *img)
Frees an image.
Definition: img.c:90
The enrollment scan did not succeed because the finger swipe was too short.
Definition: fprint.h:138
thumb (right hand)
Definition: fprint.h:52
The enrollment scan did not succeed due to poor scan quality or other general user scanning problem...
Definition: fprint.h:135
int fp_init(void)
Initialise libfprint.
Definition: core.c:934
struct fp_driver * fp_dev_get_driver(struct fp_dev *dev)
Get the driver for a fingerprint device.
Definition: core.c:691
int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *data)
Determines if a discovered print appears to be compatible with a certain device.
Definition: core.c:738
int fp_dev_supports_imaging(struct fp_dev *dev)
Determines if a device has imaging capabilities.
Definition: core.c:802
const char * fp_driver_get_full_name(struct fp_driver *drv)
Retrieves a descriptive name of the driver.
Definition: core.c:760
int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev, struct fp_dscv_print *data)
Determines if a specific discovered print appears to be compatible with a discovered device...
Definition: core.c:639
int fp_handle_events(void)
Convenience function for calling fp_handle_events_timeout() with a sensible default timeout value of ...
Definition: poll.c:246
The scan did not succeed because the finger was not centered on the scanner.
Definition: fprint.h:192
Enrollment failed due to incomprehensible data; this may occur when the user scans a different finger...
Definition: fprint.h:130
struct fp_driver * fp_dscv_dev_get_driver(struct fp_dscv_dev *dev)
Gets the driver for a discovered device.
Definition: core.c:589
The scan did not succeed due to poor scan quality or other general user scanning problem.
Definition: fprint.h:187
int fp_dev_get_nr_enroll_stages(struct fp_dev *dev)
Gets the number of enroll stages required to enroll a fingerprint with the device.
Definition: core.c:702
uint16_t fp_driver_get_driver_id(struct fp_driver *drv)
Retrieves the driver ID code for a driver.
Definition: core.c:770
struct fp_print_data * fp_print_data_from_data(unsigned char *buf, size_t buflen)
Load a stored print from a data buffer.
Definition: data.c:158
size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret)
Convert a stored print into a unified representation inside a data buffer.
Definition: data.c:125
int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger, struct fp_print_data **data)
Loads a previously stored print from disk.
Definition: data.c:336
struct fp_dscv_dev * fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs, struct fp_print_data *data)
Searches a list of discovered devices for a device that appears to be compatible with a stored print...
Definition: core.c:654
int fp_dev_get_img_width(struct fp_dev *dev)
Gets the expected width of images that will be captured from the device.
Definition: core.c:860
static int fp_verify_finger(struct fp_dev *dev, struct fp_print_data *enrolled_print)
Performs a new scan and verify it against a previously enrolled print.
Definition: fprint.h:211
int fp_dev_get_img_height(struct fp_dev *dev)
Gets the expected height of images that will be captured from the device.
Definition: core.c:880
int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger)
Removes a stored print from disk previously saved with fp_print_data_save().
Definition: data.c:368
fp_finger
Numeric codes used to refer to fingers (and thumbs) of a human.
Definition: fprint.h:45
int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev, struct fp_print_data *data)
Determines if a specific stored print appears to be compatible with a discovered device.
Definition: core.c:624
ring finger (left hand)
Definition: fprint.h:50
press
Definition: fprint.h:65
void fp_print_data_free(struct fp_print_data *data)
Frees a stored print.
Definition: data.c:407
int fp_verify_finger_img(struct fp_dev *dev, struct fp_print_data *enrolled_print, struct fp_img **img)
Performs a new scan and verify it against a previously enrolled print.
Definition: sync.c:320
The enrollment scan did not succeed because the finger was not centered on the scanner.
Definition: fprint.h:141
void fp_dscv_devs_free(struct fp_dscv_dev **devs)
Free a list of discovered devices.
Definition: core.c:573
uint32_t fp_dev_get_devtype(struct fp_dev *dev)
Gets the devtype for a device.
Definition: core.c:712
int fp_identify_finger_img(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset, struct fp_img **img)
Performs a new scan and attempts to identify the scanned finger against a collection of previously en...
Definition: sync.c:450
struct fp_dscv_dev * fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs, struct fp_dscv_print *print)
Searches a list of discovered devices for a device that appears to be compatible with a discovered pr...
Definition: core.c:674
unsigned char * fp_img_get_data(struct fp_img *img)
Gets the greyscale data for an image.
Definition: img.c:128
fp_enroll_result
Enrollment result codes returned from fp_enroll_finger().
Definition: fprint.h:124
void fp_dscv_prints_free(struct fp_dscv_print **prints)
Frees a list of discovered prints.
Definition: data.c:616
little finger (left hand)
Definition: fprint.h:51
ring finger (right hand)
Definition: fprint.h:55
uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print)
Gets the driver ID for a discovered print.
Definition: data.c:639
uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print)
Gets the devtype for a discovered print.
Definition: data.c:651
The verification scan did not succeed due to quality or pressure problems; the user should remove the...
Definition: fprint.h:145
int fp_img_get_width(struct fp_img *img)
Gets the pixel width of an image.
Definition: img.c:117