1 /*
2 * Core functions for libfprint
3 * Copyright (C) 2007-2008 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 #include <config.h>
21 #include <errno.h>
22 #include <stdio.h>
23 #include <stdlib.h>
24
25 #include <glib.h>
26 #include <libusb.h>
27
28 #include "fp_internal.h"
29
30 static int log_level = 0;
31 static int log_level_fixed = 0;
32
33 libusb_context *fpi_usb_ctx = NULL;
34 GSList *opened_devices = NULL;
35
36 /**
37 * \mainpage libfprint API Reference
38 * libfprint is an open source library to provide access to fingerprint
39 * scanning devices. For more info, see the
40 * <a href="http://www.reactivated.net/fprint/Libfprint">libfprint project
41 * homepage</a>.
42 *
43 * This documentation is aimed at application developers who wish to integrate
44 * fingerprint-related functionality into their software. libfprint has been
45 * designed so that you only have to do this once - by integrating your
46 * software with libfprint, you'll be supporting all the fingerprint readers
47 * that we have got our hands on. As such, the API is rather general (and
48 * therefore hopefully easy to comprehend!), and does its best to hide the
49 * technical details that required to operate the hardware.
50 *
51 * This documentation is not aimed at developers wishing to develop and
52 * contribute fingerprint device drivers to libfprint.
53 *
54 * Feedback on this API and its associated documentation is appreciated. Was
55 * anything unclear? Does anything seem unreasonably complicated? Is anything
56 * missing? Let us know on the
57 * <a href="http://www.reactivated.net/fprint/Mailing_list">mailing list</a>.
58 *
59 * \section enrollment Enrollment
60 *
61 * Before you dive into the API, it's worth introducing a couple of concepts.
62 *
63 * The process of enrolling a finger is where you effectively scan your
64 * finger for the purposes of teaching the system what your finger looks like.
65 * This means that you scan your fingerprint, then the system processes it and
66 * stores some data about your fingerprint to refer to later.
67 *
68 * \section verification Verification
69 *
70 * Verification is what most people think of when they think about fingerprint
71 * scanning. The process of verification is effectively performing a fresh
72 * fingerprint scan, and then comparing that scan to a finger that was
73 * previously enrolled.
74 *
75 * As an example scenario, verification can be used to implement what people
76 * would picture as fingerprint login (i.e. fingerprint replaces password).
77 * For example:
78 * - I enroll my fingerprint through some software that trusts I am who I say
79 * I am. This is a prerequisite before I can perform fingerprint-based
80 * login for my account.
81 * - Some time later, I want to login to my computer. I enter my username,
82 * but instead of prompting me for a password, it asks me to scan my finger.
83 * I scan my finger.
84 * - The system compares the finger I just scanned to the one that was
85 * enrolled earlier. If the system decides that the fingerprints match,
86 * I am successfully logged in. Otherwise, the system informs me that I am
87 * not authorised to login as that user.
88 *
89 * \section identification Identification
90 *
91 * Identification is the process of comparing a freshly scanned fingerprint
92 * to a <em>collection</em> of previously enrolled fingerprints. For example,
93 * imagine there are 100 people in an organisation, and they all have enrolled
94 * their fingerprints. One user walks up to a fingerprint scanner and scans
95 * their finger. With <em>no other knowledge</em> of who that user might be,
96 * the system examines their fingerprint, looks in the database, and determines
97 * that the user is user number #61.
98 *
99 * In other words, verification might be seen as a one-to-one fingerprint
100 * comparison where you know the identity of the user that you wish to
101 * authenticate, whereas identification is a one-to-many comparison where you
102 * do not know the identity of the user that you wish to authenticate.
103 *
104 * \section compat_general Device and print compatibility
105 * Moving off generic conceptual ideas and onto libfprint-specific
106 * implementation details, here are some introductory notes regarding how
107 * libfprint copes with compatibility of fingerprints.
108 *
109 * libfprint deals with a whole variety of different fingerprint readers and
110 * the design includes considerations of compatibility and interoperability
111 * between multiple devices. Your application should also be prepared to
112 * work with more than one type of fingerprint reader and should consider that
113 * enrolled fingerprint X may not be compatible with the device the user has
114 * plugged in today.
115 *
116 * libfprint implements the principle that fingerprints from different devices
117 * are not necessarily compatible. For example, different devices may see
118 * significantly different areas of fingerprint surface, and comparing images
119 * between the devices would be unreliable. Also, devices can stretch and
120 * distort images in different ways.
121 *
122 * libfprint also implements the principle that in some cases, fingerprints
123 * <em>are</em> compatible between different devices. If you go and buy two
124 * identical fingerprint readers, it seems logical that you should be able
125 * to enroll on one and verify on another without problems.
126 *
127 * libfprint takes a fairly simplistic approach to these issues. Internally,
128 * fingerprint hardware is driven by individual drivers. libfprint enforces
129 * that a fingerprint that came from a device backed by driver X is never
130 * compared to a fingerprint that came from a device backed by driver Y.
131 *
132 * Additionally, libfprint is designed for the situation where a single driver
133 * may support a range of devices which differ in imaging or scanning
134 * properties. For example, a driver may support two ranges of devices which
135 * even though are programmed over the same interface, one device sees
136 * substantially less of the finger flesh, therefore images from the two
137 * device types should be incompatible despite being from the same driver. To
138 * implement this, each driver assigns a <em>device type</em> to each device
139 * that it detects based on its imaging characteristics. libfprint ensures that
140 * two prints being compared have the same device type.
141 *
142 * In summary, libfprint represents fingerprints in several internal structures
143 * and each representation will offer you a way of determining the
144 * \ref driver_id "driver ID" and \ref devtype "devtype" of the print in
145 * question. Prints are only compatible if the driver ID <b>and</b> devtypes
146 * match. libfprint does offer you some "is this print compatible?" helper
147 * functions, so you don't have to worry about these details too much.
148 *
149 * \section sync Synchronity/asynchronity
150 *
151 * Currently, all data acquisition operations are synchronous and can
152 * potentially block for extended periods of time. For example, the enroll
153 * function will block for an unpredictable amount of time until the user
154 * scans their finger.
155 *
156 * Alternative asynchronous/non-blocking functionality will be offered in
157 * future but has not been implemented yet.
158 *
159 * \section getting_started Getting started
160 *
161 * libfprint includes several simple functional examples under the examples/
162 * directory in the libfprint source distribution. Those are good starting
163 * points.
164 *
165 * Usually the first thing you want to do is determine which fingerprint
166 * devices are present. This is done through \ref dscv_dev "device discovery".
167 *
168 * Once you have found a device you would like to operate, you should open it.
169 * Refer to \ref dev "device operations". This section also details enrollment,
170 * image capture, and verification.
171 *
172 *
173 * That should be enough to get you started, but do remember there are
174 * documentation pages on other aspects of libfprint's API (see the modules
175 * page).
176 */
177
178 /** @defgroup core Core library operations */
179
180 /**
181 * @defgroup dev Device operations
182 * In order to interact with fingerprint scanners, your software will
183 * interface primarily with libfprint's representation of devices, detailed
184 * on this page.
185 *
186 * \section enrolling Enrolling
187 * Enrolling is represented within libfprint as a multi-stage process. This
188 * slightly complicates things for application developers, but is required
189 * for a smooth process.
190 *
191 * Some devices require the user to scan their finger multiple times in
192 * order to complete the enrollment process. libfprint must return control
193 * to your application inbetween each scan in order for your application to
194 * instruct the user to swipe their finger again. Each scan is referred to
195 * as a stage, so a device that requires 3 scans for enrollment corresponds
196 * to you running 3 enrollment stages using libfprint.
197 *
198 * The fp_dev_get_nr_enroll_stages() function can be used to find out how
199 * many enroll stages are needed.
200 *
201 * In order to complete an enroll stage, you call an enroll function such
202 * as fp_enroll_finger(). The return of this function does not necessarily
203 * indicate that a stage has completed though, as the user may not have
204 * produced a good enough scan. Each stage may have to be retried several
205 * times.
206 *
207 * The exact semantics of the enroll functions are described in the
208 * fp_enroll_finger() documentation. You should pay careful attention to the
209 * details.
210 *
211 * \section imaging Imaging
212 * libfprint provides you with some ways to retrieve images of scanned
213 * fingers, such as the fp_dev_img_capture() function, or some enroll/verify
214 * function variants which provide images. You may wish to do something with
215 * such images in your application.
216 *
217 * However, you must be aware that not all hardware supported by libfprint
218 * operates like this. Most hardware does operate simply by sending
219 * fingerprint images to the host computer for further processing, but some
220 * devices do all fingerprint processing in hardware and do not present images
221 * to the host computer.
222 *
223 * You can use fp_dev_supports_imaging() to see if image capture is possible
224 * on a particular device. Your application must be able to cope with the
225 * fact that libfprint does support regular operations (e.g. enrolling and
226 * verification) on some devices which do not provide images.
227 *
228 * \section devtype Devtypes
229 * Internally, the \ref drv "driver" behind a device assigns a 32-bit
230 * <em>devtype</em> identifier to the device. This cannot be used as a unique
231 * ID for a specific device as many devices under the same range may share
232 * the same devtype. The devtype may even be 0 in all cases.
233 *
234 * The only reason you may be interested in retrieving the devtype for a
235 * device is for the purpose of checking if some print data is compatible
236 * with a device. libfprint uses the devtype as one way of checking that the
237 * print you are verifying is compatible with the device in question - the
238 * devtypes must be equal. This effectively allows drivers to support more
239 * than one type of device where the data from each one is not compatible with
240 * the other. Note that libfprint does provide you with helper functions to
241 * determine whether a print is compatible with a device, so under most
242 * circumstances, you don't have to worry about devtypes at all.
243 */
244
245 /** @defgroup dscv_dev Device discovery
246 * These functions allow you to scan the system for supported fingerprint
247 * scanning hardware. This is your starting point when integrating libfprint
248 * into your software.
249 *
250 * When you've identified a discovered device that you would like to control,
251 * you can open it with fp_dev_open(). Note that discovered devices may no
252 * longer be available at the time when you want to open them, for example
253 * the user may have unplugged the device.
254 */
255
256 /** @defgroup drv Driver operations
257 * Internally, libfprint is abstracted into various drivers to communicate
258 * with the different types of supported fingerprint readers. libfprint works
259 * hard so that you don't have to care about these internal abstractions,
260 * however there are some situations where you may be interested in a little
261 * behind-the-scenes driver info.
262 *
263 * You can obtain the driver for a device using fp_dev_get_driver(), which
264 * you can pass to the functions documented on this page.
265 *
266 * \section driver_id Driver IDs
267 * Each driver is assigned a unique ID by the project maintainer. These
268 * assignments are
269 * <a href="http://www.reactivated.net/fprint/Driver_ID_assignments">
270 * documented on the wiki</a> and will never change.
271 *
272 * The only reason you may be interested in retrieving the driver ID for a
273 * driver is for the purpose of checking if some print data is compatible
274 * with a device. libfprint uses the driver ID as one way of checking that
275 * the print you are trying to verify is compatible with the device in
276 * question - it ensures that enrollment data from one driver is never fed to
277 * another. Note that libfprint does provide you with helper functions to
278 * determine whether a print is compatible with a device, so under most
279 * circumstances, you don't have to worry about driver IDs at all.
280 */
281
282 static GSList *registered_drivers = NULL;
283
fpi_log(enum fpi_log_level level,const char * component,const char * function,const char * format,...)284 void fpi_log(enum fpi_log_level level, const char *component,
285 const char *function, const char *format, ...)
286 {
287 va_list args;
288 FILE *stream = stdout;
289 const char *prefix;
290
291 #ifndef ENABLE_DEBUG_LOGGING
292 if (!log_level)
293 return;
294 if (level == FPRINT_LOG_LEVEL_WARNING && log_level < 2)
295 return;
296 if (level == FPRINT_LOG_LEVEL_INFO && log_level < 3)
297 return;
298 #endif
299
300 switch (level) {
301 case FPRINT_LOG_LEVEL_INFO:
302 prefix = "info";
303 break;
304 case FPRINT_LOG_LEVEL_WARNING:
305 stream = stderr;
306 prefix = "warning";
307 break;
308 case FPRINT_LOG_LEVEL_ERROR:
309 stream = stderr;
310 prefix = "error";
311 break;
312 case FPRINT_LOG_LEVEL_DEBUG:
313 stream = stderr;
314 prefix = "debug";
315 break;
316 default:
317 stream = stderr;
318 prefix = "unknown";
319 break;
320 }
321
322 fprintf(stream, "%s:%s [%s] ", component ? component : "fp", prefix,
323 function);
324
325 va_start (args, format);
326 vfprintf(stream, format, args);
327 va_end (args);
328
329 fprintf(stream, "\n");
330 }
331
register_driver(struct fp_driver * drv)332 static void register_driver(struct fp_driver *drv)
333 {
334 if (drv->id == 0) {
335 fp_err("not registering driver %s: driver ID is 0", drv->name);
336 return;
337 }
338 registered_drivers = g_slist_prepend(registered_drivers, (gpointer) drv);
339 fp_dbg("registered driver %s", drv->name);
340 }
341
342 static struct fp_driver * const primitive_drivers[] = {
343 #ifdef ENABLE_UPEKTS
344 &upekts_driver,
345 #endif
346 #ifdef ENABLE_UPEKE2
347 &upeke2_driver,
348 #endif
349 };
350
351 static struct fp_img_driver * const img_drivers[] = {
352 #ifdef ENABLE_AES3500
353 &aes3500_driver,
354 #endif
355 #ifdef ENABLE_AES4000
356 &aes4000_driver,
357 #endif
358 #ifdef ENABLE_AES2501
359 &aes2501_driver,
360 #endif
361 #ifdef ENABLE_AES2550
362 &aes2550_driver,
363 #endif
364 #ifdef ENABLE_URU4000
365 &uru4000_driver,
366 #endif
367 #ifdef ENABLE_VCOM5S
368 &vcom5s_driver,
369 #endif
370 #ifdef ENABLE_UPEKSONLY
371 &upeksonly_driver,
372 #endif
373
374 #ifdef ENABLE_AES1610
375 &aes1610_driver,
376 #endif
377 #ifdef ENABLE_AES1660
378 &aes1660_driver,
379 #endif
380 #ifdef ENABLE_AES2660
381 &aes2660_driver,
382 #endif
383 #ifdef ENABLE_VFS101
384 &vfs101_driver,
385 #endif
386 #ifdef ENABLE_VFS301
387 &vfs301_driver,
388 #endif
389 #ifdef ENABLE_VFS5011
390 &vfs5011_driver,
391 #endif
392 #ifdef ENABLE_UPEKTC
393 &upektc_driver,
394 #endif
395 #ifdef ENABLE_UPEKTC_IMG
396 &upektc_img_driver,
397 #endif
398 #ifdef ENABLE_ETES603
399 &etes603_driver,
400 #endif
401 #ifdef ENABLE_VFS0050
402 &vfs0050_driver,
403 #endif
404 /*#ifdef ENABLE_FDU2000
405 &fdu2000_driver,
406 #endif
407 */
408 };
409
register_drivers(void)410 static void register_drivers(void)
411 {
412 unsigned int i;
413
414 for (i = 0; i < G_N_ELEMENTS(primitive_drivers); i++)
415 register_driver(primitive_drivers[i]);
416
417 for (i = 0; i < G_N_ELEMENTS(img_drivers); i++) {
418 struct fp_img_driver *imgdriver = img_drivers[i];
419 fpi_img_driver_setup(imgdriver);
420 register_driver(&imgdriver->driver);
421 }
422 }
423
fprint_get_drivers(void)424 API_EXPORTED struct fp_driver **fprint_get_drivers (void)
425 {
426 GPtrArray *array;
427 unsigned int i;
428
429 array = g_ptr_array_new ();
430 for (i = 0; i < G_N_ELEMENTS(primitive_drivers); i++)
431 g_ptr_array_add (array, primitive_drivers[i]);
432
433 for (i = 0; i < G_N_ELEMENTS(img_drivers); i++)
434 g_ptr_array_add (array, &(img_drivers[i]->driver));
435
436 /* Add a null item terminating the array */
437 g_ptr_array_add (array, NULL);
438
439 return (struct fp_driver **) g_ptr_array_free (array, FALSE);
440 }
441
find_supporting_driver(libusb_device * udev,const struct usb_id ** usb_id,uint32_t * devtype)442 static struct fp_driver *find_supporting_driver(libusb_device *udev,
443 const struct usb_id **usb_id, uint32_t *devtype)
444 {
445 int ret;
446 GSList *elem = registered_drivers;
447 struct libusb_device_descriptor dsc;
448
449 const struct usb_id *best_usb_id;
450 struct fp_driver *best_drv;
451 uint32_t best_devtype;
452 int drv_score = 0;
453
454 ret = libusb_get_device_descriptor(udev, &dsc);
455 if (ret < 0) {
456 fp_err("Failed to get device descriptor");
457 return NULL;
458 }
459
460 best_drv = NULL;
461 best_devtype = 0;
462
463 do {
464 struct fp_driver *drv = elem->data;
465 uint32_t type = 0;
466 const struct usb_id *id;
467
468 for (id = drv->id_table; id->vendor; id++) {
469 if (dsc.idVendor == id->vendor && dsc.idProduct == id->product) {
470 if (drv->discover) {
471 int r = drv->discover(&dsc, &type);
472 if (r < 0)
473 fp_err("%s discover failed, code %d", drv->name, r);
474 if (r <= 0)
475 continue;
476 /* Has a discover function, and matched our device */
477 drv_score = 100;
478 } else {
479 /* Already got a driver as good */
480 if (drv_score >= 50)
481 continue;
482 drv_score = 50;
483 }
484 fp_dbg("driver %s supports USB device %04x:%04x",
485 drv->name, id->vendor, id->product);
486 best_usb_id = id;
487 best_drv = drv;
488 best_devtype = type;
489
490 /* We found the best possible driver */
491 if (drv_score == 100)
492 break;
493 }
494 }
495 } while ((elem = g_slist_next(elem)));
496
497 if (best_drv != NULL) {
498 fp_dbg("selected driver %s supports USB device %04x:%04x",
499 best_drv->name, dsc.idVendor, dsc.idProduct);
500 *devtype = best_devtype;
501 *usb_id = best_usb_id;
502 }
503
504 return best_drv;
505 }
506
discover_dev(libusb_device * udev)507 static struct fp_dscv_dev *discover_dev(libusb_device *udev)
508 {
509 const struct usb_id *usb_id;
510 struct fp_driver *drv;
511 struct fp_dscv_dev *ddev;
512 uint32_t devtype;
513
514 drv = find_supporting_driver(udev, &usb_id, &devtype);
515
516 if (!drv)
517 return NULL;
518
519 ddev = g_malloc0(sizeof(*ddev));
520 ddev->drv = drv;
521 ddev->udev = udev;
522 ddev->driver_data = usb_id->driver_data;
523 ddev->devtype = devtype;
524 return ddev;
525 }
526
527 /** \ingroup dscv_dev
528 * Scans the system and returns a list of discovered devices. This is your
529 * entry point into finding a fingerprint reader to operate.
530 * \returns a NULL-terminated list of discovered devices. Must be freed with
531 * fp_dscv_devs_free() after use.
532 */
fp_discover_devs(void)533 API_EXPORTED struct fp_dscv_dev **fp_discover_devs(void)
534 {
535 GSList *tmplist = NULL;
536 struct fp_dscv_dev **list;
537 libusb_device *udev;
538 libusb_device **devs;
539 int dscv_count = 0;
540 int r;
541 int i = 0;
542
543 if (registered_drivers == NULL)
544 return NULL;
545
546 r = libusb_get_device_list(fpi_usb_ctx, &devs);
547 if (r < 0) {
548 fp_err("couldn't enumerate USB devices, error %d", r);
549 return NULL;
550 }
551
552 /* Check each device against each driver, temporarily storing successfully
553 * discovered devices in a GSList.
554 *
555 * Quite inefficient but excusable as we'll only be dealing with small
556 * sets of drivers against small sets of USB devices */
557 while ((udev = devs[i++]) != NULL) {
558 struct fp_dscv_dev *ddev = discover_dev(udev);
559 if (!ddev)
560 continue;
561 tmplist = g_slist_prepend(tmplist, (gpointer) ddev);
562 dscv_count++;
563 }
564
565 /* Convert our temporary GSList into a standard NULL-terminated pointer
566 * array. */
567 list = g_malloc(sizeof(*list) * (dscv_count + 1));
568 if (dscv_count > 0) {
569 GSList *elem = tmplist;
570 i = 0;
571 do {
572 list[i++] = elem->data;
573 } while ((elem = g_slist_next(elem)));
574 }
575 list[dscv_count] = NULL; /* NULL-terminate */
576
577 g_slist_free(tmplist);
578 return list;
579 }
580
581 /** \ingroup dscv_dev
582 * Free a list of discovered devices. This function destroys the list and all
583 * discovered devices that it included, so make sure you have opened your
584 * discovered device <b>before</b> freeing the list.
585 * \param devs the list of discovered devices. If NULL, function simply
586 * returns.
587 */
fp_dscv_devs_free(struct fp_dscv_dev ** devs)588 API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs)
589 {
590 int i;
591 if (!devs)
592 return;
593
594 for (i = 0; devs[i]; i++)
595 g_free(devs[i]);
596 g_free(devs);
597 }
598
599 /** \ingroup dscv_dev
600 * Gets the \ref drv "driver" for a discovered device.
601 * \param dev the discovered device
602 * \returns the driver backing the device
603 */
fp_dscv_dev_get_driver(struct fp_dscv_dev * dev)604 API_EXPORTED struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev)
605 {
606 return dev->drv;
607 }
608
609 /** \ingroup dscv_dev
610 * Gets the \ref devtype "devtype" for a discovered device.
611 * \param dev the discovered device
612 * \returns the devtype of the device
613 */
fp_dscv_dev_get_devtype(struct fp_dscv_dev * dev)614 API_EXPORTED uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev)
615 {
616 return dev->devtype;
617 }
618
fpi_driver_get_data_type(struct fp_driver * drv)619 enum fp_print_data_type fpi_driver_get_data_type(struct fp_driver *drv)
620 {
621 switch (drv->type) {
622 case DRIVER_PRIMITIVE:
623 return PRINT_DATA_RAW;
624 case DRIVER_IMAGING:
625 return PRINT_DATA_NBIS_MINUTIAE;
626 default:
627 fp_err("unrecognised drv type %d", drv->type);
628 return PRINT_DATA_RAW;
629 }
630 }
631
632 /** \ingroup dscv_dev
633 * Determines if a specific \ref print_data "stored print" appears to be
634 * compatible with a discovered device.
635 * \param dev the discovered device
636 * \param data the print for compatibility checking
637 * \returns 1 if the print is compatible with the device, 0 otherwise
638 */
fp_dscv_dev_supports_print_data(struct fp_dscv_dev * dev,struct fp_print_data * data)639 API_EXPORTED int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
640 struct fp_print_data *data)
641 {
642 return fpi_print_data_compatible(dev->drv->id, dev->devtype,
643 fpi_driver_get_data_type(dev->drv), data->driver_id, data->devtype,
644 data->type);
645 }
646
647 /** \ingroup dscv_dev
648 * Determines if a specific \ref dscv_print "discovered print" appears to be
649 * compatible with a discovered device.
650 * \param dev the discovered device
651 * \param data the discovered print for compatibility checking
652 * \returns 1 if the print is compatible with the device, 0 otherwise
653 */
fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev * dev,struct fp_dscv_print * data)654 API_EXPORTED int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
655 struct fp_dscv_print *data)
656 {
657 return fpi_print_data_compatible(dev->drv->id, dev->devtype, 0,
658 data->driver_id, data->devtype, 0);
659 }
660
661 /** \ingroup dscv_dev
662 * Searches a list of discovered devices for a device that appears to be
663 * compatible with a \ref print_data "stored print".
664 * \param devs a list of discovered devices
665 * \param data the print under inspection
666 * \returns the first discovered device that appears to support the print, or
667 * NULL if no apparently compatible devices could be found
668 */
fp_dscv_dev_for_print_data(struct fp_dscv_dev ** devs,struct fp_print_data * data)669 API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
670 struct fp_print_data *data)
671 {
672 struct fp_dscv_dev *ddev;
673 int i;
674
675 for (i = 0; (ddev = devs[i]); i++)
676 if (fp_dscv_dev_supports_print_data(ddev, data))
677 return ddev;
678 return NULL;
679 }
680
681 /** \ingroup dscv_dev
682 * Searches a list of discovered devices for a device that appears to be
683 * compatible with a \ref dscv_print "discovered print".
684 * \param devs a list of discovered devices
685 * \param print the print under inspection
686 * \returns the first discovered device that appears to support the print, or
687 * NULL if no apparently compatible devices could be found
688 */
fp_dscv_dev_for_dscv_print(struct fp_dscv_dev ** devs,struct fp_dscv_print * print)689 API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
690 struct fp_dscv_print *print)
691 {
692 struct fp_dscv_dev *ddev;
693 int i;
694
695 for (i = 0; (ddev = devs[i]); i++)
696 if (fp_dscv_dev_supports_dscv_print(ddev, print))
697 return ddev;
698 return NULL;
699 }
700
701 /** \ingroup dev
702 * Get the \ref drv "driver" for a fingerprint device.
703 * \param dev the device
704 * \returns the driver controlling the device
705 */
fp_dev_get_driver(struct fp_dev * dev)706 API_EXPORTED struct fp_driver *fp_dev_get_driver(struct fp_dev *dev)
707 {
708 return dev->drv;
709 }
710
711 /** \ingroup dev
712 * Gets the number of \ref enrolling "enroll stages" required to enroll a
713 * fingerprint with the device.
714 * \param dev the device
715 * \returns the number of enroll stages
716 */
fp_dev_get_nr_enroll_stages(struct fp_dev * dev)717 API_EXPORTED int fp_dev_get_nr_enroll_stages(struct fp_dev *dev)
718 {
719 return dev->nr_enroll_stages;
720 }
721
722 /** \ingroup dev
723 * Gets the \ref devtype "devtype" for a device.
724 * \param dev the device
725 * \returns the devtype
726 */
fp_dev_get_devtype(struct fp_dev * dev)727 API_EXPORTED uint32_t fp_dev_get_devtype(struct fp_dev *dev)
728 {
729 return dev->devtype;
730 }
731
732 /** \ingroup dev
733 * Determines if a stored print is compatible with a certain device.
734 * \param dev the device
735 * \param data the stored print
736 * \returns 1 if the print is compatible with the device, 0 if not
737 */
fp_dev_supports_print_data(struct fp_dev * dev,struct fp_print_data * data)738 API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev,
739 struct fp_print_data *data)
740 {
741 return fpi_print_data_compatible(dev->drv->id, dev->devtype,
742 fpi_driver_get_data_type(dev->drv), data->driver_id, data->devtype,
743 data->type);
744 }
745
746 /** \ingroup dev
747 * Determines if a \ref dscv_print "discovered print" appears to be compatible
748 * with a certain device.
749 * \param dev the device
750 * \param data the discovered print
751 * \returns 1 if the print is compatible with the device, 0 if not
752 */
fp_dev_supports_dscv_print(struct fp_dev * dev,struct fp_dscv_print * data)753 API_EXPORTED int fp_dev_supports_dscv_print(struct fp_dev *dev,
754 struct fp_dscv_print *data)
755 {
756 return fpi_print_data_compatible(dev->drv->id, dev->devtype,
757 0, data->driver_id, data->devtype, 0);
758 }
759
760 /** \ingroup drv
761 * Retrieves the name of the driver. For example: "upekts"
762 * \param drv the driver
763 * \returns the driver name. Must not be modified or freed.
764 */
fp_driver_get_name(struct fp_driver * drv)765 API_EXPORTED const char *fp_driver_get_name(struct fp_driver *drv)
766 {
767 return drv->name;
768 }
769
770 /** \ingroup drv
771 * Retrieves a descriptive name of the driver. For example: "UPEK TouchStrip"
772 * \param drv the driver
773 * \returns the descriptive name. Must not be modified or freed.
774 */
fp_driver_get_full_name(struct fp_driver * drv)775 API_EXPORTED const char *fp_driver_get_full_name(struct fp_driver *drv)
776 {
777 return drv->full_name;
778 }
779
780 /** \ingroup drv
781 * Retrieves the driver ID code for a driver.
782 * \param drv the driver
783 * \returns the driver ID
784 */
fp_driver_get_driver_id(struct fp_driver * drv)785 API_EXPORTED uint16_t fp_driver_get_driver_id(struct fp_driver *drv)
786 {
787 return drv->id;
788 }
789
790 /** \ingroup drv
791 * Retrieves the scan type for the devices associated with the driver.
792 * \param drv the driver
793 * \returns the scan type
794 */
fp_driver_get_scan_type(struct fp_driver * drv)795 API_EXPORTED enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv)
796 {
797 return drv->scan_type;
798 }
799
dev_to_img_dev(struct fp_dev * dev)800 static struct fp_img_dev *dev_to_img_dev(struct fp_dev *dev)
801 {
802 if (dev->drv->type != DRIVER_IMAGING)
803 return NULL;
804 return dev->priv;
805 }
806
807 /** \ingroup dev
808 * Determines if a device has imaging capabilities. If a device has imaging
809 * capabilities you are able to perform imaging operations such as retrieving
810 * scan images using fp_dev_img_capture(). However, not all devices are
811 * imaging devices - some do all processing in hardware. This function will
812 * indicate which class a device in question falls into.
813 * \param dev the fingerprint device
814 * \returns 1 if the device is an imaging device, 0 if the device does not
815 * provide images to the host computer
816 */
fp_dev_supports_imaging(struct fp_dev * dev)817 API_EXPORTED int fp_dev_supports_imaging(struct fp_dev *dev)
818 {
819 return dev->drv->capture_start != NULL;
820 }
821
822 /** \ingroup dev
823 * Determines if a device is capable of \ref identification "identification"
824 * through fp_identify_finger() and similar. Not all devices support this
825 * functionality.
826 * \param dev the fingerprint device
827 * \returns 1 if the device is capable of identification, 0 otherwise.
828 */
fp_dev_supports_identification(struct fp_dev * dev)829 API_EXPORTED int fp_dev_supports_identification(struct fp_dev *dev)
830 {
831 return dev->drv->identify_start != NULL;
832 }
833
834 /** \ingroup dev
835 * Gets the expected width of images that will be captured from the device.
836 * This function will return -1 for devices that are not
837 * \ref imaging "imaging devices". If the width of images from this device
838 * can vary, 0 will be returned.
839 * \param dev the device
840 * \returns the expected image width, or 0 for variable, or -1 for non-imaging
841 * devices.
842 */
fp_dev_get_img_width(struct fp_dev * dev)843 API_EXPORTED int fp_dev_get_img_width(struct fp_dev *dev)
844 {
845 struct fp_img_dev *imgdev = dev_to_img_dev(dev);
846 if (!imgdev) {
847 fp_dbg("get image width for non-imaging device");
848 return -1;
849 }
850
851 return fpi_imgdev_get_img_width(imgdev);
852 }
853
854 /** \ingroup dev
855 * Gets the expected height of images that will be captured from the device.
856 * This function will return -1 for devices that are not
857 * \ref imaging "imaging devices". If the height of images from this device
858 * can vary, 0 will be returned.
859 * \param dev the device
860 * \returns the expected image height, or 0 for variable, or -1 for non-imaging
861 * devices.
862 */
fp_dev_get_img_height(struct fp_dev * dev)863 API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev)
864 {
865 struct fp_img_dev *imgdev = dev_to_img_dev(dev);
866 if (!imgdev) {
867 fp_dbg("get image height for non-imaging device");
868 return -1;
869 }
870
871 return fpi_imgdev_get_img_height(imgdev);
872 }
873
874 /** \ingroup core
875 * Set message verbosity.
876 * - Level 0: no messages ever printed by the library (default)
877 * - Level 1: error messages are printed to stderr
878 * - Level 2: warning and error messages are printed to stderr
879 * - Level 3: informational messages are printed to stdout, warning and error
880 * messages are printed to stderr
881 *
882 * The default level is 0, which means no messages are ever printed. If you
883 * choose to increase the message verbosity level, ensure that your
884 * application does not close the stdout/stderr file descriptors.
885 *
886 * You are advised to set level 3. libfprint is conservative with its message
887 * logging and most of the time, will only log messages that explain error
888 * conditions and other oddities. This will help you debug your software.
889 *
890 * If the LIBFPRINT_DEBUG environment variable was set when libfprint was
891 * initialized, this function does nothing: the message verbosity is fixed
892 * to the value in the environment variable.
893 *
894 * If libfprint was compiled without any message logging, this function does
895 * nothing: you'll never get any messages.
896 *
897 * If libfprint was compiled with verbose debug message logging, this function
898 * does nothing: you'll always get messages from all levels.
899 *
900 * \param ctx the context to operate on, or NULL for the default context
901 * \param level debug level to set
902 */
fp_set_debug(int level)903 API_EXPORTED void fp_set_debug(int level)
904 {
905 if (log_level_fixed)
906 return;
907
908 log_level = level;
909 libusb_set_debug(fpi_usb_ctx, level);
910 }
911
912 /** \ingroup core
913 * Initialise libfprint. This function must be called before you attempt to
914 * use the library in any way.
915 * \return 0 on success, non-zero on error.
916 */
fp_init(void)917 API_EXPORTED int fp_init(void)
918 {
919 char *dbg = getenv("LIBFPRINT_DEBUG");
920 int r;
921 fp_dbg("");
922
923 r = libusb_init(&fpi_usb_ctx);
924 if (r < 0)
925 return r;
926
927 if (dbg) {
928 log_level = atoi(dbg);
929 if (log_level) {
930 log_level_fixed = 1;
931 libusb_set_debug(fpi_usb_ctx, log_level);
932 }
933 }
934
935 register_drivers();
936 fpi_poll_init();
937 return 0;
938 }
939
940 /** \ingroup core
941 * Deinitialise libfprint. This function should be called during your program
942 * exit sequence. You must not use any libfprint functions after calling this
943 * function, unless you call fp_init() again.
944 */
fp_exit(void)945 API_EXPORTED void fp_exit(void)
946 {
947 fp_dbg("");
948
949 if (opened_devices) {
950 GSList *copy = g_slist_copy(opened_devices);
951 GSList *elem = copy;
952 fp_dbg("naughty app left devices open on exit!");
953
954 do
955 fp_dev_close((struct fp_dev *) elem->data);
956 while ((elem = g_slist_next(elem)));
957
958 g_slist_free(copy);
959 g_slist_free(opened_devices);
960 opened_devices = NULL;
961 }
962
963 fpi_data_exit();
964 fpi_poll_exit();
965 g_slist_free(registered_drivers);
966 registered_drivers = NULL;
967 libusb_exit(fpi_usb_ctx);
968 }
969
970