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 
119 };
120 
121 int fp_dev_supports_imaging(struct fp_dev *dev);
122 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
123  struct fp_img **image);
124 int fp_dev_get_img_width(struct fp_dev *dev);
125 int fp_dev_get_img_height(struct fp_dev *dev);
126 
157 };
158 
159 int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
160  struct fp_img **img);
161 
173 static inline int fp_enroll_finger(struct fp_dev *dev,
174  struct fp_print_data **print_data)
175 {
176  return fp_enroll_finger_img(dev, print_data, NULL);
177 }
178 
207 };
208 
209 int fp_verify_finger_img(struct fp_dev *dev,
210  struct fp_print_data *enrolled_print, struct fp_img **img);
211 
222 static inline int fp_verify_finger(struct fp_dev *dev,
223  struct fp_print_data *enrolled_print)
224 {
225  return fp_verify_finger_img(dev, enrolled_print, NULL);
226 }
227 
228 int fp_dev_supports_identification(struct fp_dev *dev);
229 int fp_identify_finger_img(struct fp_dev *dev,
230  struct fp_print_data **print_gallery, size_t *match_offset,
231  struct fp_img **img);
232 
248 static inline int fp_identify_finger(struct fp_dev *dev,
249  struct fp_print_data **print_gallery, size_t *match_offset)
250 {
251  return fp_identify_finger_img(dev, print_gallery, match_offset, NULL);
252 }
253 
254 /* Data handling */
255 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
256  struct fp_print_data **data);
257 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
258  struct fp_print_data **data);
259 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
260 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
261 void fp_print_data_free(struct fp_print_data *data);
262 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
263 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
264  size_t buflen);
265 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
266 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
267 
268 /* Image handling */
269 
271 struct fp_minutia {
272  int x;
273  int y;
274  int ex;
275  int ey;
276  int direction;
277  double reliability;
278  int type;
279  int appearing;
280  int feature_id;
281  int *nbrs;
282  int *ridge_counts;
283  int num_nbrs;
284 };
285 
286 int fp_img_get_height(struct fp_img *img);
287 int fp_img_get_width(struct fp_img *img);
288 unsigned char *fp_img_get_data(struct fp_img *img);
289 int fp_img_save_to_file(struct fp_img *img, char *path);
290 void fp_img_standardize(struct fp_img *img);
291 struct fp_img *fp_img_binarize(struct fp_img *img);
292 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
293 void fp_img_free(struct fp_img *img);
294 
295 /* Polling and timing */
296 
297 struct fp_pollfd {
298  int fd;
299  short events;
300 };
301 
302 int fp_handle_events_timeout(struct timeval *timeout);
303 int fp_handle_events(void);
304 size_t fp_get_pollfds(struct fp_pollfd **pollfds);
305 int fp_get_next_timeout(struct timeval *tv);
306 
307 typedef void (*fp_pollfd_added_cb)(int fd, short events);
308 typedef void (*fp_pollfd_removed_cb)(int fd);
309 void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
310  fp_pollfd_removed_cb removed_cb);
311 
312 /* Library */
313 int fp_init(void);
314 void fp_exit(void);
315 void fp_set_debug(int level);
316 
317 /* Asynchronous I/O */
318 
319 typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data);
320 int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
321  void *user_data);
322 
323 typedef void (*fp_dev_close_cb)(struct fp_dev *dev, void *user_data);
324 void fp_async_dev_close(struct fp_dev *dev, fp_dev_close_cb callback,
325  void *user_data);
326 
327 typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result,
328  struct fp_print_data *print, struct fp_img *img, void *user_data);
329 int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback,
330  void *user_data);
331 
332 typedef void (*fp_enroll_stop_cb)(struct fp_dev *dev, void *user_data);
333 int fp_async_enroll_stop(struct fp_dev *dev, fp_enroll_stop_cb callback,
334  void *user_data);
335 
336 typedef void (*fp_verify_cb)(struct fp_dev *dev, int result,
337  struct fp_img *img, void *user_data);
338 int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data,
339  fp_verify_cb callback, void *user_data);
340 
341 typedef void (*fp_verify_stop_cb)(struct fp_dev *dev, void *user_data);
342 int fp_async_verify_stop(struct fp_dev *dev, fp_verify_stop_cb callback,
343  void *user_data);
344 
345 typedef void (*fp_identify_cb)(struct fp_dev *dev, int result,
346  size_t match_offset, struct fp_img *img, void *user_data);
347 int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery,
348  fp_identify_cb callback, void *user_data);
349 
350 typedef void (*fp_identify_stop_cb)(struct fp_dev *dev, void *user_data);
351 int fp_async_identify_stop(struct fp_dev *dev, fp_identify_stop_cb callback,
352  void *user_data);
353 
354 typedef void (*fp_capture_cb)(struct fp_dev *dev, int result,
355  struct fp_img *img, void *user_data);
356 int fp_async_capture_start(struct fp_dev *dev, int unconditional, fp_capture_cb callback, void *user_data);
357 
358 typedef void (*fp_capture_stop_cb)(struct fp_dev *dev, void *user_data);
359 int fp_async_capture_stop(struct fp_dev *dev, fp_capture_stop_cb callback, void *user_data);
360 
361 #ifdef __cplusplus
362 }
363 #endif
364 
365 #endif
366 
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:795
The scan did not succeed due to quality or pressure problems; the user should remove their finger fro...
Definition: fprint.h:206
uint32_t fp_print_data_get_devtype(struct fp_print_data *data)
Gets the devtype for a stored print.
Definition: data.c:528
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:143
void fp_dev_close(struct fp_dev *dev)
Close a device.
Definition: sync.c:84
void fp_exit(void)
Deinitialise libfprint.
Definition: core.c:945
uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev)
Gets the devtype for a discovered device.
Definition: core.c:614
int fp_img_get_height(struct fp_img *img)
Gets the pixel height of an image.
Definition: img.c:106
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:248
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:323
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:139
const char * fp_driver_get_name(struct fp_driver *drv)
Retrieves the name of the driver.
Definition: core.c:765
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
Capture failed for some reason.
Definition: fprint.h:118
static int fp_enroll_finger(struct fp_dev *dev, struct fp_print_data **print_data)
Performs an enroll stage.
Definition: fprint.h:173
Definition: fprint.h:297
struct fp_dscv_dev ** fp_discover_devs(void)
Scans the system and returns a list of discovered devices.
Definition: core.c:533
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:829
Capture completed successfully, the capture data has been returned to the caller. ...
Definition: fprint.h:116
enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print)
Gets the finger code for a discovered print.
Definition: data.c:759
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:493
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:191
struct fp_img * fp_img_binarize(struct fp_img *img)
Get a binarized form of a standardized scanned image.
Definition: img.c:440
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:186
void fp_set_debug(int level)
Set message verbosity.
Definition: core.c:903
uint16_t fp_print_data_get_driver_id(struct fp_print_data *data)
Gets the driver ID for a stored print.
Definition: data.c:517
Definition: fprint.h:271
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:652
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:738
void fp_img_standardize(struct fp_img *img)
Standardizes an image by normalizing its orientation, colors, etc.
Definition: img.c:219
int fp_dscv_print_delete(struct fp_dscv_print *print)
Removes a discovered print from disk.
Definition: data.c:772
The scan did not succeed because the finger swipe was too short.
Definition: fprint.h:200
The scan completed successfully and the newly scanned fingerprint does match the fingerprint being ve...
Definition: fprint.h:195
Enrollment completed successfully, the enrollment data has been returned to the caller.
Definition: fprint.h:138
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:492
middle finger (left hand)
Definition: fprint.h:49
void fp_img_free(struct fp_img *img)
Frees an image.
Definition: img.c:89
The enrollment scan did not succeed because the finger swipe was too short.
Definition: fprint.h:149
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:146
int fp_init(void)
Initialise libfprint.
Definition: core.c:917
fp_capture_result
Image capture result codes returned from fp_dev_img_capture().
Definition: fprint.h:113
struct fp_driver * fp_dev_get_driver(struct fp_dev *dev)
Get the driver for a fingerprint device.
Definition: core.c:706
int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print)
Determines if a discovered print appears to be compatible with a certain device.
Definition: core.c:753
int fp_dev_supports_imaging(struct fp_dev *dev)
Determines if a device has imaging capabilities.
Definition: core.c:817
const char * fp_driver_get_full_name(struct fp_driver *drv)
Retrieves a descriptive name of the driver.
Definition: core.c:775
int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev, struct fp_dscv_print *print)
Determines if a specific discovered print appears to be compatible with a discovered device...
Definition: core.c:654
int fp_handle_events(void)
Convenience function for calling fp_handle_events_timeout() with a sensible default timeout value of ...
Definition: poll.c:246
int fp_dev_img_capture(struct fp_dev *dev, int unconditional, struct fp_img **image)
Captures an image from a device.
Definition: sync.c:554
The scan did not succeed because the finger was not centered on the scanner.
Definition: fprint.h:203
Enrollment failed due to incomprehensible data; this may occur when the user scans a different finger...
Definition: fprint.h:141
struct fp_driver * fp_dscv_dev_get_driver(struct fp_dscv_dev *dev)
Gets the driver for a discovered device.
Definition: core.c:604
The scan did not succeed due to poor scan quality or other general user scanning problem.
Definition: fprint.h:198
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:717
uint16_t fp_driver_get_driver_id(struct fp_driver *drv)
Retrieves the driver ID code for a driver.
Definition: core.c:785
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:257
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:136
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:432
struct fp_dscv_dev * fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs, struct fp_print_data *print)
Searches a list of discovered devices for a device that appears to be compatible with a stored print...
Definition: core.c:669
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:843
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:222
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:863
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:464
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 *print)
Determines if a specific stored print appears to be compatible with a discovered device.
Definition: core.c:639
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:503
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:152
void fp_dscv_devs_free(struct fp_dscv_dev **devs)
Free a list of discovered devices.
Definition: core.c:588
uint32_t fp_dev_get_devtype(struct fp_dev *dev)
Gets the devtype for a device.
Definition: core.c:727
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:689
unsigned char * fp_img_get_data(struct fp_img *img)
Gets the greyscale data for an image.
Definition: img.c:127
fp_enroll_result
Enrollment result codes returned from fp_enroll_finger().
Definition: fprint.h:135
void fp_dscv_prints_free(struct fp_dscv_print **prints)
Frees a list of discovered prints.
Definition: data.c:714
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:737
uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print)
Gets the devtype for a discovered print.
Definition: data.c:749
The verification scan did not succeed due to quality or pressure problems; the user should remove the...
Definition: fprint.h:156
int fp_img_get_width(struct fp_img *img)
Gets the pixel width of an image.
Definition: img.c:116