doc: Port from Doxygen to gtk-doc
Split the introduction into separate chapters, add filler documentation for async functions, fix mismatched function arguments.
This commit is contained in:
Bastien Nocera
parent
dac153d24a
commit
231b8f9f92
18 changed files with 1216 additions and 1847 deletions
115
doc/advanced-topics.xml
Normal file
115
doc/advanced-topics.xml
Normal file
|
|
@ -0,0 +1,115 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
||||||
|
]>
|
||||||
|
<chapter id="advanced-topics" xmlns:xi="http://www.w3.org/2003/XInclude">
|
||||||
|
<title>Advanced Topics</title>
|
||||||
|
|
||||||
|
<refsect2 id="compatibility">
|
||||||
|
<title>Device and print compatibility</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Moving off generic conceptual ideas and onto libfprint-specific
|
||||||
|
implementation details, here are some introductory notes regarding how
|
||||||
|
libfprint copes with compatibility of fingerprints.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
libfprint deals with a whole variety of different fingerprint readers and
|
||||||
|
the design includes considerations of compatibility and interoperability
|
||||||
|
between multiple devices. Your application should also be prepared to
|
||||||
|
work with more than one type of fingerprint reader and should consider that
|
||||||
|
enrolled fingerprint X may not be compatible with the device the user has
|
||||||
|
plugged in today.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
libfprint implements the principle that fingerprints from different devices
|
||||||
|
are not necessarily compatible. For example, different devices may see
|
||||||
|
significantly different areas of fingerprint surface, and comparing images
|
||||||
|
between the devices would be unreliable. Also, devices can stretch and
|
||||||
|
distort images in different ways.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
libfprint also implements the principle that in some cases, fingerprints
|
||||||
|
<emphasis>are</emphasis> compatible between different devices. If you go and buy two
|
||||||
|
identical fingerprint readers, it seems logical that you should be able
|
||||||
|
to enroll on one and verify on another without problems.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
libfprint takes a fairly simplistic approach to these issues. Internally,
|
||||||
|
fingerprint hardware is driven by individual drivers. libfprint enforces
|
||||||
|
that a fingerprint that came from a device backed by driver X is never
|
||||||
|
compared to a fingerprint that came from a device backed by driver Y.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Additionally, libfprint is designed for the situation where a single driver
|
||||||
|
may support a range of devices which differ in imaging or scanning
|
||||||
|
properties. For example, a driver may support two ranges of devices which
|
||||||
|
even though are programmed over the same interface, one device sees
|
||||||
|
substantially less of the finger flesh, therefore images from the two
|
||||||
|
device types should be incompatible despite being from the same driver. To
|
||||||
|
implement this, each driver assigns a <emphasis>device type</emphasis> to each device
|
||||||
|
that it detects based on its imaging characteristics. libfprint ensures that
|
||||||
|
two prints being compared have the same device type.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In summary, libfprint represents fingerprints in several internal structures
|
||||||
|
and each representation will offer you a way of determining the
|
||||||
|
\ref driver_id "driver ID" and \ref devtype "devtype" of the print in
|
||||||
|
question. Prints are only compatible if the driver ID <emphasis role="strong">and</emphasis> devtypes
|
||||||
|
match. libfprint does offer you some "is this print compatible?" helper
|
||||||
|
functions, so you don't have to worry about these details too much.
|
||||||
|
</para>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2 id="driver_id">
|
||||||
|
<title>Driver IDs</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Each driver is assigned a unique ID by the project maintainer. These
|
||||||
|
assignments are
|
||||||
|
<ulink href="http://www.reactivated.net/fprint/Driver_ID_assignments">
|
||||||
|
documented on the wiki</ulink> and will never change.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The only reason you may be interested in retrieving the driver ID for a
|
||||||
|
driver is for the purpose of checking if some print data is compatible
|
||||||
|
with a device. libfprint uses the driver ID as one way of checking that
|
||||||
|
the print you are trying to verify is compatible with the device in
|
||||||
|
question - it ensures that enrollment data from one driver is never fed to
|
||||||
|
another. Note that libfprint does provide you with helper functions to
|
||||||
|
determine whether a print is compatible with a device, so under most
|
||||||
|
circumstances, you don't have to worry about driver IDs at all.
|
||||||
|
</para>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2 id="device-types">
|
||||||
|
<title>Device types</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Internally, the \ref drv "driver" behind a device assigns a 32-bit
|
||||||
|
<emphasis>devtype</emphasis> identifier to the device. This cannot be used as a unique
|
||||||
|
ID for a specific device as many devices under the same range may share
|
||||||
|
the same devtype. The devtype may even be 0 in all cases.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The only reason you may be interested in retrieving the devtype for a
|
||||||
|
device is for the purpose of checking if some print data is compatible
|
||||||
|
with a device. libfprint uses the devtype as one way of checking that the
|
||||||
|
print you are verifying is compatible with the device in question - the
|
||||||
|
devtypes must be equal. This effectively allows drivers to support more
|
||||||
|
than one type of device where the data from each one is not compatible with
|
||||||
|
the other. Note that libfprint does provide you with helper functions to
|
||||||
|
determine whether a print is compatible with a device, so under most
|
||||||
|
circumstances, you don't have to worry about devtypes at all.
|
||||||
|
</para>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
1294
doc/doxygen.cfg.in
1294
doc/doxygen.cfg.in
File diff suppressed because it is too large
Load diff
30
doc/getting-started.xml
Normal file
30
doc/getting-started.xml
Normal file
|
|
@ -0,0 +1,30 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
||||||
|
]>
|
||||||
|
<chapter id="getting-started" xmlns:xi="http://www.w3.org/2003/XInclude">
|
||||||
|
<title>Getting Started</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
libfprint includes several simple functional examples under the examples/
|
||||||
|
directory in the libfprint source distribution. Those are good starting
|
||||||
|
points.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Usually the first thing you want to do is determine which fingerprint
|
||||||
|
devices are present. This is done through \ref dscv_dev "device discovery".
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Once you have found a device you would like to operate, you should open it.
|
||||||
|
Refer to \ref dev "device operations". This section also details enrollment,
|
||||||
|
image capture, and verification.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
That should be enough to get you started, but do remember there are
|
||||||
|
documentation pages on other aspects of libfprint's API (see the modules
|
||||||
|
page).
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
106
doc/intro.xml
Normal file
106
doc/intro.xml
Normal file
|
|
@ -0,0 +1,106 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
||||||
|
]>
|
||||||
|
<chapter id="intro" xmlns:xi="http://www.w3.org/2003/XInclude">
|
||||||
|
<title>Introduction</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
libfprint is an open source library to provide access to fingerprint
|
||||||
|
scanning devices. For more info, see the
|
||||||
|
<ulink url="http://www.reactivated.net/fprint/Libfprint">libfprint project homepage</ulink>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This documentation is aimed at application developers who wish to integrate
|
||||||
|
fingerprint-related functionality into their software. libfprint has been
|
||||||
|
designed so that you only have to do this once - by integrating your
|
||||||
|
software with libfprint, you'll be supporting all the fingerprint readers
|
||||||
|
that we have got our hands on. As such, the API is rather general (and
|
||||||
|
therefore hopefully easy to comprehend!), and does its best to hide the
|
||||||
|
technical details that required to operate the hardware.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This documentation is not aimed at developers wishing to develop and
|
||||||
|
contribute fingerprint device drivers to libfprint.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Feedback on this API and its associated documentation is appreciated. Was
|
||||||
|
anything unclear? Does anything seem unreasonably complicated? Is anything
|
||||||
|
missing? Let us know on the
|
||||||
|
<ulink url="http://www.reactivated.net/fprint/Mailing_list">mailing list</ulink>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<refsect2 id="enrollment">
|
||||||
|
<title>Enrollment</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Before you dive into the API, it's worth introducing a couple of concepts.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The process of enrolling a finger is where you effectively scan your
|
||||||
|
finger for the purposes of teaching the system what your finger looks like.
|
||||||
|
This means that you scan your fingerprint, then the system processes it and
|
||||||
|
stores some data about your fingerprint to refer to later.
|
||||||
|
</para>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2 id="verification">
|
||||||
|
<title>Verification</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Verification is what most people think of when they think about fingerprint
|
||||||
|
scanning. The process of verification is effectively performing a fresh
|
||||||
|
fingerprint scan, and then comparing that scan to a finger that was
|
||||||
|
previously enrolled.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
As an example scenario, verification can be used to implement what people
|
||||||
|
would picture as fingerprint login (i.e. fingerprint replaces password).
|
||||||
|
For example:
|
||||||
|
</para>
|
||||||
|
<itemizedlist mark='dot'>
|
||||||
|
<listitem>
|
||||||
|
I enroll my fingerprint through some software that trusts I am who I say
|
||||||
|
I am. This is a prerequisite before I can perform fingerprint-based
|
||||||
|
login for my account.
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
Some time later, I want to login to my computer. I enter my username,
|
||||||
|
but instead of prompting me for a password, it asks me to scan my finger.
|
||||||
|
I scan my finger.
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
The system compares the finger I just scanned to the one that was
|
||||||
|
enrolled earlier. If the system decides that the fingerprints match,
|
||||||
|
I am successfully logged in. Otherwise, the system informs me that I am
|
||||||
|
not authorised to login as that user.
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2 id="identification">
|
||||||
|
<title>Identification</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Identification is the process of comparing a freshly scanned fingerprint
|
||||||
|
to a <emphasis>collection</emphasis> of previously enrolled fingerprints. For example,
|
||||||
|
imagine there are 100 people in an organisation, and they all have enrolled
|
||||||
|
their fingerprints. One user walks up to a fingerprint scanner and scans
|
||||||
|
their finger. With <emphasis>no other knowledge</emphasis> of who that user might be,
|
||||||
|
the system examines their fingerprint, looks in the database, and determines
|
||||||
|
that the user is user number #61.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In other words, verification might be seen as a one-to-one fingerprint
|
||||||
|
comparison where you know the identity of the user that you wish to
|
||||||
|
authenticate, whereas identification is a one-to-many comparison where you
|
||||||
|
do not know the identity of the user that you wish to authenticate.
|
||||||
|
</para>
|
||||||
|
</refsect2>
|
||||||
|
</chapter>
|
||||||
53
doc/libfprint-docs.xml
Normal file
53
doc/libfprint-docs.xml
Normal file
|
|
@ -0,0 +1,53 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
|
||||||
|
[
|
||||||
|
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
|
||||||
|
]>
|
||||||
|
<book id="index">
|
||||||
|
<bookinfo>
|
||||||
|
<title>libfprint Reference Manual</title>
|
||||||
|
<releaseinfo>
|
||||||
|
<para>This document is the API reference for the libfprint library.</para>
|
||||||
|
<para>
|
||||||
|
The latest version of libfprint, as well as the latest version of
|
||||||
|
this API reference, is <ulink role="online-location" url="https://www.freedesktop.org/wiki/Software/fprint/libfprint/">available online</ulink>.
|
||||||
|
</para>
|
||||||
|
</releaseinfo>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<part>
|
||||||
|
<title>Library Overview</title>
|
||||||
|
<xi:include href="intro.xml"/>
|
||||||
|
<xi:include href="advanced-topics.xml"/>
|
||||||
|
<xi:include href="getting-started.xml"/>
|
||||||
|
</part>
|
||||||
|
|
||||||
|
<part>
|
||||||
|
<title>API Documentation</title>
|
||||||
|
<xi:include href="xml/events.xml"/>
|
||||||
|
<xi:include href="xml/discovery.xml"/>
|
||||||
|
|
||||||
|
<xi:include href="xml/drv.xml"/>
|
||||||
|
<xi:include href="xml/dev.xml"/>
|
||||||
|
<xi:include href="xml/print_data.xml"/>
|
||||||
|
<!-- https://bugs.freedesktop.org/show_bug.cgi?id=106550
|
||||||
|
<xi:include href="xml/dscv_print.xml"/> -->
|
||||||
|
<xi:include href="xml/img.xml"/>
|
||||||
|
</part>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
<part>
|
||||||
|
<title>Writing Drivers</title>
|
||||||
|
</part>
|
||||||
|
-->
|
||||||
|
|
||||||
|
<index id="api-index">
|
||||||
|
<title>API Index</title>
|
||||||
|
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
|
||||||
|
</index>
|
||||||
|
<index id="deprecated-api-index" role="deprecated">
|
||||||
|
<title>Index of deprecated API</title>
|
||||||
|
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
|
||||||
|
</index>
|
||||||
|
</book>
|
||||||
127
doc/libfprint-sections.txt
Normal file
127
doc/libfprint-sections.txt
Normal file
|
|
@ -0,0 +1,127 @@
|
||||||
|
<INCLUDE>fprint.h</INCLUDE>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>events</FILE>
|
||||||
|
<TITLE>Initialisation and events handling</TITLE>
|
||||||
|
fp_set_debug
|
||||||
|
fp_init
|
||||||
|
fp_exit
|
||||||
|
fp_pollfd
|
||||||
|
fp_handle_events_timeout
|
||||||
|
fp_handle_events
|
||||||
|
fp_get_next_timeout
|
||||||
|
fp_get_pollfds
|
||||||
|
fp_set_pollfd_notifiers
|
||||||
|
</SECTION>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>discovery</FILE>
|
||||||
|
<TITLE>Device discovery</TITLE>
|
||||||
|
fp_dscv_dev
|
||||||
|
fp_discover_devs
|
||||||
|
fp_dscv_devs_free
|
||||||
|
fp_dscv_dev_get_driver
|
||||||
|
fp_dscv_dev_get_devtype
|
||||||
|
fp_dscv_dev_supports_print_data
|
||||||
|
fp_dscv_dev_supports_dscv_print
|
||||||
|
fp_dscv_dev_for_print_data
|
||||||
|
fp_dscv_dev_for_dscv_print
|
||||||
|
</SECTION>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>drv</FILE>
|
||||||
|
fp_driver
|
||||||
|
fp_driver_get_name
|
||||||
|
fp_driver_get_full_name
|
||||||
|
fp_driver_get_driver_id
|
||||||
|
fp_driver_get_scan_type
|
||||||
|
</SECTION>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>dev</FILE>
|
||||||
|
fp_dev
|
||||||
|
fp_scan_type
|
||||||
|
fp_capture_result
|
||||||
|
fp_enroll_result
|
||||||
|
fp_verify_result
|
||||||
|
|
||||||
|
fp_dev_get_driver
|
||||||
|
fp_dev_get_nr_enroll_stages
|
||||||
|
fp_dev_get_devtype
|
||||||
|
fp_dev_supports_print_data
|
||||||
|
fp_dev_supports_imaging
|
||||||
|
fp_dev_supports_identification
|
||||||
|
fp_dev_supports_dscv_print
|
||||||
|
fp_dev_get_img_width
|
||||||
|
fp_dev_get_img_height
|
||||||
|
|
||||||
|
fp_dev_open
|
||||||
|
fp_async_dev_open
|
||||||
|
|
||||||
|
fp_dev_close
|
||||||
|
fp_async_dev_close
|
||||||
|
|
||||||
|
fp_enroll_finger
|
||||||
|
fp_enroll_finger_img
|
||||||
|
fp_async_enroll_start
|
||||||
|
fp_async_enroll_stop
|
||||||
|
|
||||||
|
fp_verify_finger
|
||||||
|
fp_verify_finger_img
|
||||||
|
fp_async_verify_start
|
||||||
|
fp_async_verify_stop
|
||||||
|
|
||||||
|
fp_identify_finger
|
||||||
|
fp_identify_finger_img
|
||||||
|
fp_async_identify_start
|
||||||
|
fp_async_identify_stop
|
||||||
|
|
||||||
|
fp_dev_img_capture
|
||||||
|
fp_async_capture_start
|
||||||
|
fp_async_capture_stop
|
||||||
|
</SECTION>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>print_data</FILE>
|
||||||
|
fp_finger
|
||||||
|
fp_print_data
|
||||||
|
fp_print_data
|
||||||
|
fp_print_data_get_data
|
||||||
|
fp_print_data_from_data
|
||||||
|
fp_print_data_save
|
||||||
|
fp_print_data_load
|
||||||
|
fp_print_data_delete
|
||||||
|
fp_print_data_from_dscv_print
|
||||||
|
fp_print_data_free
|
||||||
|
fp_print_data_get_driver_id
|
||||||
|
fp_print_data_get_devtype
|
||||||
|
</SECTION>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>dscv_print</FILE>
|
||||||
|
fp_dscv_print
|
||||||
|
fp_discover_prints
|
||||||
|
fp_dscv_prints_free
|
||||||
|
fp_dscv_print_get_driver_id
|
||||||
|
fp_dscv_print_get_devtype
|
||||||
|
fp_dscv_print_get_finger
|
||||||
|
fp_dscv_print_delete
|
||||||
|
</SECTION>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>img</FILE>
|
||||||
|
fp_img
|
||||||
|
fp_minutia
|
||||||
|
fp_img_free
|
||||||
|
fp_img_get_height
|
||||||
|
fp_img_get_width
|
||||||
|
fp_img_get_data
|
||||||
|
fp_img_save_to_file
|
||||||
|
fp_img_standardize
|
||||||
|
fp_img_binarize
|
||||||
|
fp_img_get_minutiae
|
||||||
|
</SECTION>
|
||||||
|
|
||||||
|
<SECTION>
|
||||||
|
<FILE>poll</FILE>
|
||||||
|
</SECTION>
|
||||||
|
|
@ -1,17 +1,67 @@
|
||||||
cdata = configuration_data()
|
subdir('xml')
|
||||||
cdata.set('SRCDIR', join_paths(meson.source_root(), 'libfprint'))
|
|
||||||
cdata.set('BUILDDIR', join_paths(meson.build_root(), 'doc'))
|
|
||||||
|
|
||||||
cfg = configure_file(input: 'doxygen.cfg.in',
|
private_headers = [
|
||||||
output: 'doxygen.cfg',
|
'config.h',
|
||||||
configuration: cdata,
|
|
||||||
install: false)
|
|
||||||
|
|
||||||
doxygen = find_program('doxygen')
|
'aeslib.h',
|
||||||
datadir = join_paths(get_option('datadir'), 'doc', 'libfprint-devel')
|
'assembling.h',
|
||||||
custom_target('docs',
|
'fp_internal.h',
|
||||||
input: cfg,
|
|
||||||
output: 'html',
|
# Drivers
|
||||||
command: [ doxygen, '@INPUT@' ],
|
'aes1660.h',
|
||||||
install: true,
|
'aes2501.h',
|
||||||
install_dir: datadir)
|
'aes2550.h',
|
||||||
|
'aes2660.h',
|
||||||
|
'aes3k.h',
|
||||||
|
'aesx660.h',
|
||||||
|
'driver_ids.h',
|
||||||
|
'elan.h',
|
||||||
|
'upeksonly.h',
|
||||||
|
'upektc.h',
|
||||||
|
'upektc_img.h',
|
||||||
|
'vfs0050.h',
|
||||||
|
'vfs301_proto_fragments.h',
|
||||||
|
'vfs301_proto.h',
|
||||||
|
'vfs5011_proto.h',
|
||||||
|
|
||||||
|
# NBIS
|
||||||
|
'morph.h',
|
||||||
|
'sunrast.h',
|
||||||
|
'bozorth.h',
|
||||||
|
'defs.h',
|
||||||
|
'log.h',
|
||||||
|
'bz_array.h',
|
||||||
|
'lfs.h',
|
||||||
|
]
|
||||||
|
|
||||||
|
html_images = [
|
||||||
|
]
|
||||||
|
|
||||||
|
content_files = [
|
||||||
|
'intro.xml'
|
||||||
|
]
|
||||||
|
|
||||||
|
expand_content_files = content_files
|
||||||
|
|
||||||
|
glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
|
||||||
|
glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
|
||||||
|
docpath = join_paths(get_option('datadir'), 'gtk-doc', 'html')
|
||||||
|
|
||||||
|
gnome.gtkdoc('libfprint',
|
||||||
|
main_xml: 'libfprint-docs.xml',
|
||||||
|
src_dir: join_paths(meson.source_root(), 'libfprint'),
|
||||||
|
dependencies: libfprint_dep,
|
||||||
|
content_files: content_files,
|
||||||
|
expand_content_files: expand_content_files,
|
||||||
|
scan_args: [
|
||||||
|
'--rebuild-types',
|
||||||
|
'--ignore-decorators=API_EXPORTED',
|
||||||
|
'--ignore-headers=' + ' '.join(private_headers),
|
||||||
|
],
|
||||||
|
fixxref_args: [
|
||||||
|
'--html-dir=@0@'.format(docpath),
|
||||||
|
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
|
||||||
|
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
|
||||||
|
],
|
||||||
|
html_assets: html_images,
|
||||||
|
install: true)
|
||||||
|
|
|
||||||
8
doc/xml/gtkdocentities.ent.in
Normal file
8
doc/xml/gtkdocentities.ent.in
Normal file
|
|
@ -0,0 +1,8 @@
|
||||||
|
<!ENTITY package "@PACKAGE@">
|
||||||
|
<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
|
||||||
|
<!ENTITY package_name "@PACKAGE_NAME@">
|
||||||
|
<!ENTITY package_string "@PACKAGE_STRING@">
|
||||||
|
<!ENTITY package_tarname "@PACKAGE_TARNAME@">
|
||||||
|
<!ENTITY package_url "@PACKAGE_URL@">
|
||||||
|
<!ENTITY package_version "@PACKAGE_VERSION@">
|
||||||
|
<!ENTITY package_api_version "@PACKAGE_API_VERSION@">
|
||||||
10
doc/xml/meson.build
Normal file
10
doc/xml/meson.build
Normal file
|
|
@ -0,0 +1,10 @@
|
||||||
|
ent_conf = configuration_data()
|
||||||
|
ent_conf.set('PACKAGE', 'libfprint')
|
||||||
|
ent_conf.set('PACKAGE_BUGREPORT', 'https://bugs.freedesktop.org/enter_bug.cgi?product=libfprint')
|
||||||
|
ent_conf.set('PACKAGE_NAME', 'libfprint')
|
||||||
|
ent_conf.set('PACKAGE_STRING', 'libfprint')
|
||||||
|
ent_conf.set('PACKAGE_TARNAME', 'libfprint-' + meson.project_version())
|
||||||
|
ent_conf.set('PACKAGE_URL', 'https://www.freedesktop.org/wiki/Software/fprint/libfprint/')
|
||||||
|
ent_conf.set('PACKAGE_VERSION', meson.project_version())
|
||||||
|
ent_conf.set('PACKAGE_API_VERSION', '1.0')
|
||||||
|
configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
|
||||||
|
|
@ -36,7 +36,15 @@ void fpi_drvcb_open_complete(struct fp_dev *dev, int status)
|
||||||
dev->open_cb(dev, status, dev->open_cb_data);
|
dev->open_cb(dev, status, dev->open_cb_data);
|
||||||
}
|
}
|
||||||
|
|
||||||
API_EXPORTED int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb cb,
|
/**
|
||||||
|
* fp_async_dev_open:
|
||||||
|
* @ddev:
|
||||||
|
* @callback:
|
||||||
|
* @user_data
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
|
API_EXPORTED int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
|
||||||
void *user_data)
|
void *user_data)
|
||||||
{
|
{
|
||||||
struct fp_driver *drv = ddev->drv;
|
struct fp_driver *drv = ddev->drv;
|
||||||
|
|
@ -56,7 +64,7 @@ API_EXPORTED int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb cb,
|
||||||
dev->udev = udevh;
|
dev->udev = udevh;
|
||||||
dev->__enroll_stage = -1;
|
dev->__enroll_stage = -1;
|
||||||
dev->state = DEV_STATE_INITIALIZING;
|
dev->state = DEV_STATE_INITIALIZING;
|
||||||
dev->open_cb = cb;
|
dev->open_cb = callback;
|
||||||
dev->open_cb_data = user_data;
|
dev->open_cb_data = user_data;
|
||||||
|
|
||||||
if (!drv->open) {
|
if (!drv->open) {
|
||||||
|
|
@ -87,6 +95,12 @@ void fpi_drvcb_close_complete(struct fp_dev *dev)
|
||||||
g_free(dev);
|
g_free(dev);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_dev_close:
|
||||||
|
* @dev:
|
||||||
|
* @callback:
|
||||||
|
* @user_data
|
||||||
|
*/
|
||||||
API_EXPORTED void fp_async_dev_close(struct fp_dev *dev,
|
API_EXPORTED void fp_async_dev_close(struct fp_dev *dev,
|
||||||
fp_dev_close_cb callback, void *user_data)
|
fp_dev_close_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -127,6 +141,14 @@ void fpi_drvcb_enroll_started(struct fp_dev *dev, int status)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_enroll_start:
|
||||||
|
* @dev:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_enroll_start(struct fp_dev *dev,
|
API_EXPORTED int fp_async_enroll_start(struct fp_dev *dev,
|
||||||
fp_enroll_stage_cb callback, void *user_data)
|
fp_enroll_stage_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -181,6 +203,14 @@ void fpi_drvcb_enroll_stopped(struct fp_dev *dev)
|
||||||
dev->enroll_stop_cb(dev, dev->enroll_stop_cb_data);
|
dev->enroll_stop_cb(dev, dev->enroll_stop_cb_data);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_enroll_stop:
|
||||||
|
* @dev:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_enroll_stop(struct fp_dev *dev,
|
API_EXPORTED int fp_async_enroll_stop(struct fp_dev *dev,
|
||||||
fp_enroll_stop_cb callback, void *user_data)
|
fp_enroll_stop_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -210,6 +240,15 @@ API_EXPORTED int fp_async_enroll_stop(struct fp_dev *dev,
|
||||||
return r;
|
return r;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_verify_start:
|
||||||
|
* @dev:
|
||||||
|
* @data:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_verify_start(struct fp_dev *dev,
|
API_EXPORTED int fp_async_verify_start(struct fp_dev *dev,
|
||||||
struct fp_print_data *data, fp_verify_cb callback, void *user_data)
|
struct fp_print_data *data, fp_verify_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -278,6 +317,14 @@ void fpi_drvcb_verify_stopped(struct fp_dev *dev)
|
||||||
dev->verify_stop_cb(dev, dev->verify_stop_cb_data);
|
dev->verify_stop_cb(dev, dev->verify_stop_cb_data);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_verify_stop:
|
||||||
|
* @dev:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_verify_stop(struct fp_dev *dev,
|
API_EXPORTED int fp_async_verify_stop(struct fp_dev *dev,
|
||||||
fp_verify_stop_cb callback, void *user_data)
|
fp_verify_stop_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -311,6 +358,15 @@ API_EXPORTED int fp_async_verify_stop(struct fp_dev *dev,
|
||||||
return r;
|
return r;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_identify_start:
|
||||||
|
* @dev:
|
||||||
|
* @gallery:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_identify_start(struct fp_dev *dev,
|
API_EXPORTED int fp_async_identify_start(struct fp_dev *dev,
|
||||||
struct fp_print_data **gallery, fp_identify_cb callback, void *user_data)
|
struct fp_print_data **gallery, fp_identify_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -369,6 +425,14 @@ void fpi_drvcb_report_identify_result(struct fp_dev *dev, int result,
|
||||||
fp_dbg("ignoring verify result as no callback is subscribed");
|
fp_dbg("ignoring verify result as no callback is subscribed");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_identify_stop:
|
||||||
|
* @dev:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_identify_stop(struct fp_dev *dev,
|
API_EXPORTED int fp_async_identify_stop(struct fp_dev *dev,
|
||||||
fp_identify_stop_cb callback, void *user_data)
|
fp_identify_stop_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -412,6 +476,15 @@ void fpi_drvcb_identify_stopped(struct fp_dev *dev)
|
||||||
dev->identify_stop_cb(dev, dev->identify_stop_cb_data);
|
dev->identify_stop_cb(dev, dev->identify_stop_cb_data);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_capture_start:
|
||||||
|
* @dev:
|
||||||
|
* @unconditional:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_capture_start(struct fp_dev *dev, int unconditional,
|
API_EXPORTED int fp_async_capture_start(struct fp_dev *dev, int unconditional,
|
||||||
fp_capture_cb callback, void *user_data)
|
fp_capture_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
@ -479,6 +552,14 @@ void fpi_drvcb_capture_stopped(struct fp_dev *dev)
|
||||||
dev->capture_stop_cb(dev, dev->capture_stop_cb_data);
|
dev->capture_stop_cb(dev, dev->capture_stop_cb_data);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_async_capture_stop:
|
||||||
|
* @dev:
|
||||||
|
* @callback:
|
||||||
|
* @user_data:
|
||||||
|
*
|
||||||
|
* Returns:
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_async_capture_stop(struct fp_dev *dev,
|
API_EXPORTED int fp_async_capture_stop(struct fp_dev *dev,
|
||||||
fp_capture_stop_cb callback, void *user_data)
|
fp_capture_stop_cb callback, void *user_data)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
492
libfprint/core.c
492
libfprint/core.c
|
|
@ -34,163 +34,50 @@ libusb_context *fpi_usb_ctx = NULL;
|
||||||
GSList *opened_devices = NULL;
|
GSList *opened_devices = NULL;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \mainpage libfprint API Reference
|
* SECTION:discovery
|
||||||
* libfprint is an open source library to provide access to fingerprint
|
* @title: Device discovery
|
||||||
* scanning devices. For more info, see the
|
|
||||||
* <a href="http://www.reactivated.net/fprint/Libfprint">libfprint project
|
|
||||||
* homepage</a>.
|
|
||||||
*
|
*
|
||||||
* This documentation is aimed at application developers who wish to integrate
|
* These functions allow you to scan the system for supported fingerprint
|
||||||
* fingerprint-related functionality into their software. libfprint has been
|
* scanning hardware. This is your starting point when integrating libfprint
|
||||||
* designed so that you only have to do this once - by integrating your
|
* into your software.
|
||||||
* software with libfprint, you'll be supporting all the fingerprint readers
|
|
||||||
* that we have got our hands on. As such, the API is rather general (and
|
|
||||||
* therefore hopefully easy to comprehend!), and does its best to hide the
|
|
||||||
* technical details that required to operate the hardware.
|
|
||||||
*
|
*
|
||||||
* This documentation is not aimed at developers wishing to develop and
|
* When you've identified a discovered device that you would like to control,
|
||||||
* contribute fingerprint device drivers to libfprint.
|
* you can open it with fp_dev_open(). Note that discovered devices may no
|
||||||
*
|
* longer be available at the time when you want to open them, for example
|
||||||
* Feedback on this API and its associated documentation is appreciated. Was
|
* the user may have unplugged the device.
|
||||||
* anything unclear? Does anything seem unreasonably complicated? Is anything
|
|
||||||
* missing? Let us know on the
|
|
||||||
* <a href="http://www.reactivated.net/fprint/Mailing_list">mailing list</a>.
|
|
||||||
*
|
|
||||||
* \section enrollment Enrollment
|
|
||||||
*
|
|
||||||
* Before you dive into the API, it's worth introducing a couple of concepts.
|
|
||||||
*
|
|
||||||
* The process of enrolling a finger is where you effectively scan your
|
|
||||||
* finger for the purposes of teaching the system what your finger looks like.
|
|
||||||
* This means that you scan your fingerprint, then the system processes it and
|
|
||||||
* stores some data about your fingerprint to refer to later.
|
|
||||||
*
|
|
||||||
* \section verification Verification
|
|
||||||
*
|
|
||||||
* Verification is what most people think of when they think about fingerprint
|
|
||||||
* scanning. The process of verification is effectively performing a fresh
|
|
||||||
* fingerprint scan, and then comparing that scan to a finger that was
|
|
||||||
* previously enrolled.
|
|
||||||
*
|
|
||||||
* As an example scenario, verification can be used to implement what people
|
|
||||||
* would picture as fingerprint login (i.e. fingerprint replaces password).
|
|
||||||
* For example:
|
|
||||||
* - I enroll my fingerprint through some software that trusts I am who I say
|
|
||||||
* I am. This is a prerequisite before I can perform fingerprint-based
|
|
||||||
* login for my account.
|
|
||||||
* - Some time later, I want to login to my computer. I enter my username,
|
|
||||||
* but instead of prompting me for a password, it asks me to scan my finger.
|
|
||||||
* I scan my finger.
|
|
||||||
* - The system compares the finger I just scanned to the one that was
|
|
||||||
* enrolled earlier. If the system decides that the fingerprints match,
|
|
||||||
* I am successfully logged in. Otherwise, the system informs me that I am
|
|
||||||
* not authorised to login as that user.
|
|
||||||
*
|
|
||||||
* \section identification Identification
|
|
||||||
*
|
|
||||||
* Identification is the process of comparing a freshly scanned fingerprint
|
|
||||||
* to a <em>collection</em> of previously enrolled fingerprints. For example,
|
|
||||||
* imagine there are 100 people in an organisation, and they all have enrolled
|
|
||||||
* their fingerprints. One user walks up to a fingerprint scanner and scans
|
|
||||||
* their finger. With <em>no other knowledge</em> of who that user might be,
|
|
||||||
* the system examines their fingerprint, looks in the database, and determines
|
|
||||||
* that the user is user number #61.
|
|
||||||
*
|
|
||||||
* In other words, verification might be seen as a one-to-one fingerprint
|
|
||||||
* comparison where you know the identity of the user that you wish to
|
|
||||||
* authenticate, whereas identification is a one-to-many comparison where you
|
|
||||||
* do not know the identity of the user that you wish to authenticate.
|
|
||||||
*
|
|
||||||
* \section compat_general Device and print compatibility
|
|
||||||
* Moving off generic conceptual ideas and onto libfprint-specific
|
|
||||||
* implementation details, here are some introductory notes regarding how
|
|
||||||
* libfprint copes with compatibility of fingerprints.
|
|
||||||
*
|
|
||||||
* libfprint deals with a whole variety of different fingerprint readers and
|
|
||||||
* the design includes considerations of compatibility and interoperability
|
|
||||||
* between multiple devices. Your application should also be prepared to
|
|
||||||
* work with more than one type of fingerprint reader and should consider that
|
|
||||||
* enrolled fingerprint X may not be compatible with the device the user has
|
|
||||||
* plugged in today.
|
|
||||||
*
|
|
||||||
* libfprint implements the principle that fingerprints from different devices
|
|
||||||
* are not necessarily compatible. For example, different devices may see
|
|
||||||
* significantly different areas of fingerprint surface, and comparing images
|
|
||||||
* between the devices would be unreliable. Also, devices can stretch and
|
|
||||||
* distort images in different ways.
|
|
||||||
*
|
|
||||||
* libfprint also implements the principle that in some cases, fingerprints
|
|
||||||
* <em>are</em> compatible between different devices. If you go and buy two
|
|
||||||
* identical fingerprint readers, it seems logical that you should be able
|
|
||||||
* to enroll on one and verify on another without problems.
|
|
||||||
*
|
|
||||||
* libfprint takes a fairly simplistic approach to these issues. Internally,
|
|
||||||
* fingerprint hardware is driven by individual drivers. libfprint enforces
|
|
||||||
* that a fingerprint that came from a device backed by driver X is never
|
|
||||||
* compared to a fingerprint that came from a device backed by driver Y.
|
|
||||||
*
|
|
||||||
* Additionally, libfprint is designed for the situation where a single driver
|
|
||||||
* may support a range of devices which differ in imaging or scanning
|
|
||||||
* properties. For example, a driver may support two ranges of devices which
|
|
||||||
* even though are programmed over the same interface, one device sees
|
|
||||||
* substantially less of the finger flesh, therefore images from the two
|
|
||||||
* device types should be incompatible despite being from the same driver. To
|
|
||||||
* implement this, each driver assigns a <em>device type</em> to each device
|
|
||||||
* that it detects based on its imaging characteristics. libfprint ensures that
|
|
||||||
* two prints being compared have the same device type.
|
|
||||||
*
|
|
||||||
* In summary, libfprint represents fingerprints in several internal structures
|
|
||||||
* and each representation will offer you a way of determining the
|
|
||||||
* \ref driver_id "driver ID" and \ref devtype "devtype" of the print in
|
|
||||||
* question. Prints are only compatible if the driver ID <b>and</b> devtypes
|
|
||||||
* match. libfprint does offer you some "is this print compatible?" helper
|
|
||||||
* functions, so you don't have to worry about these details too much.
|
|
||||||
*
|
|
||||||
* \section sync Synchronity/asynchronity
|
|
||||||
*
|
|
||||||
* Currently, all data acquisition operations are synchronous and can
|
|
||||||
* potentially block for extended periods of time. For example, the enroll
|
|
||||||
* function will block for an unpredictable amount of time until the user
|
|
||||||
* scans their finger.
|
|
||||||
*
|
|
||||||
* Alternative asynchronous/non-blocking functionality will be offered in
|
|
||||||
* future but has not been implemented yet.
|
|
||||||
*
|
|
||||||
* \section getting_started Getting started
|
|
||||||
*
|
|
||||||
* libfprint includes several simple functional examples under the examples/
|
|
||||||
* directory in the libfprint source distribution. Those are good starting
|
|
||||||
* points.
|
|
||||||
*
|
|
||||||
* Usually the first thing you want to do is determine which fingerprint
|
|
||||||
* devices are present. This is done through \ref dscv_dev "device discovery".
|
|
||||||
*
|
|
||||||
* Once you have found a device you would like to operate, you should open it.
|
|
||||||
* Refer to \ref dev "device operations". This section also details enrollment,
|
|
||||||
* image capture, and verification.
|
|
||||||
*
|
|
||||||
*
|
|
||||||
* That should be enough to get you started, but do remember there are
|
|
||||||
* documentation pages on other aspects of libfprint's API (see the modules
|
|
||||||
* page).
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/** @defgroup core Core library operations */
|
/**
|
||||||
|
* SECTION:drv
|
||||||
|
* @title: Driver operations
|
||||||
|
*
|
||||||
|
* Internally, libfprint is abstracted into various drivers to communicate
|
||||||
|
* with the different types of supported fingerprint readers. libfprint works
|
||||||
|
* hard so that you don't have to care about these internal abstractions,
|
||||||
|
* however there are some situations where you may be interested in a little
|
||||||
|
* behind-the-scenes driver info.
|
||||||
|
*
|
||||||
|
* You can obtain the driver for a device using fp_dev_get_driver(), which
|
||||||
|
* you can pass to the functions documented on this page.
|
||||||
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @defgroup dev Device operations
|
* SECTION:dev
|
||||||
|
* @title: Devices operations
|
||||||
|
*
|
||||||
* In order to interact with fingerprint scanners, your software will
|
* In order to interact with fingerprint scanners, your software will
|
||||||
* interface primarily with libfprint's representation of devices, detailed
|
* interface primarily with libfprint's representation of devices, detailed
|
||||||
* on this page.
|
* on this page.
|
||||||
*
|
*
|
||||||
* \section enrolling Enrolling
|
* # Enrolling # {#enrolling}
|
||||||
|
*
|
||||||
* Enrolling is represented within libfprint as a multi-stage process. This
|
* Enrolling is represented within libfprint as a multi-stage process. This
|
||||||
* slightly complicates things for application developers, but is required
|
* slightly complicates things for application developers, but is required
|
||||||
* for a smooth process.
|
* for a smooth process.
|
||||||
*
|
*
|
||||||
* Some devices require the user to scan their finger multiple times in
|
* Some devices require the user to scan their finger multiple times in
|
||||||
* order to complete the enrollment process. libfprint must return control
|
* order to complete the enrollment process. libfprint must return control
|
||||||
* to your application inbetween each scan in order for your application to
|
* to your application in-between each scan in order for your application to
|
||||||
* instruct the user to swipe their finger again. Each scan is referred to
|
* instruct the user to swipe their finger again. Each scan is referred to
|
||||||
* as a stage, so a device that requires 3 scans for enrollment corresponds
|
* as a stage, so a device that requires 3 scans for enrollment corresponds
|
||||||
* to you running 3 enrollment stages using libfprint.
|
* to you running 3 enrollment stages using libfprint.
|
||||||
|
|
@ -208,7 +95,8 @@ GSList *opened_devices = NULL;
|
||||||
* fp_enroll_finger() documentation. You should pay careful attention to the
|
* fp_enroll_finger() documentation. You should pay careful attention to the
|
||||||
* details.
|
* details.
|
||||||
*
|
*
|
||||||
* \section imaging Imaging
|
* # Imaging # {#imaging}
|
||||||
|
*
|
||||||
* libfprint provides you with some ways to retrieve images of scanned
|
* libfprint provides you with some ways to retrieve images of scanned
|
||||||
* fingers, such as the fp_dev_img_capture() function, or some enroll/verify
|
* fingers, such as the fp_dev_img_capture() function, or some enroll/verify
|
||||||
* function variants which provide images. You may wish to do something with
|
* function variants which provide images. You may wish to do something with
|
||||||
|
|
@ -224,59 +112,6 @@ GSList *opened_devices = NULL;
|
||||||
* on a particular device. Your application must be able to cope with the
|
* on a particular device. Your application must be able to cope with the
|
||||||
* fact that libfprint does support regular operations (e.g. enrolling and
|
* fact that libfprint does support regular operations (e.g. enrolling and
|
||||||
* verification) on some devices which do not provide images.
|
* verification) on some devices which do not provide images.
|
||||||
*
|
|
||||||
* \section devtype Devtypes
|
|
||||||
* Internally, the \ref drv "driver" behind a device assigns a 32-bit
|
|
||||||
* <em>devtype</em> identifier to the device. This cannot be used as a unique
|
|
||||||
* ID for a specific device as many devices under the same range may share
|
|
||||||
* the same devtype. The devtype may even be 0 in all cases.
|
|
||||||
*
|
|
||||||
* The only reason you may be interested in retrieving the devtype for a
|
|
||||||
* device is for the purpose of checking if some print data is compatible
|
|
||||||
* with a device. libfprint uses the devtype as one way of checking that the
|
|
||||||
* print you are verifying is compatible with the device in question - the
|
|
||||||
* devtypes must be equal. This effectively allows drivers to support more
|
|
||||||
* than one type of device where the data from each one is not compatible with
|
|
||||||
* the other. Note that libfprint does provide you with helper functions to
|
|
||||||
* determine whether a print is compatible with a device, so under most
|
|
||||||
* circumstances, you don't have to worry about devtypes at all.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/** @defgroup dscv_dev Device discovery
|
|
||||||
* These functions allow you to scan the system for supported fingerprint
|
|
||||||
* scanning hardware. This is your starting point when integrating libfprint
|
|
||||||
* into your software.
|
|
||||||
*
|
|
||||||
* When you've identified a discovered device that you would like to control,
|
|
||||||
* you can open it with fp_dev_open(). Note that discovered devices may no
|
|
||||||
* longer be available at the time when you want to open them, for example
|
|
||||||
* the user may have unplugged the device.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/** @defgroup drv Driver operations
|
|
||||||
* Internally, libfprint is abstracted into various drivers to communicate
|
|
||||||
* with the different types of supported fingerprint readers. libfprint works
|
|
||||||
* hard so that you don't have to care about these internal abstractions,
|
|
||||||
* however there are some situations where you may be interested in a little
|
|
||||||
* behind-the-scenes driver info.
|
|
||||||
*
|
|
||||||
* You can obtain the driver for a device using fp_dev_get_driver(), which
|
|
||||||
* you can pass to the functions documented on this page.
|
|
||||||
*
|
|
||||||
* \section driver_id Driver IDs
|
|
||||||
* Each driver is assigned a unique ID by the project maintainer. These
|
|
||||||
* assignments are
|
|
||||||
* <a href="http://www.reactivated.net/fprint/Driver_ID_assignments">
|
|
||||||
* documented on the wiki</a> and will never change.
|
|
||||||
*
|
|
||||||
* The only reason you may be interested in retrieving the driver ID for a
|
|
||||||
* driver is for the purpose of checking if some print data is compatible
|
|
||||||
* with a device. libfprint uses the driver ID as one way of checking that
|
|
||||||
* the print you are trying to verify is compatible with the device in
|
|
||||||
* question - it ensures that enrollment data from one driver is never fed to
|
|
||||||
* another. Note that libfprint does provide you with helper functions to
|
|
||||||
* determine whether a print is compatible with a device, so under most
|
|
||||||
* circumstances, you don't have to worry about driver IDs at all.
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
static GSList *registered_drivers = NULL;
|
static GSList *registered_drivers = NULL;
|
||||||
|
|
@ -524,10 +359,13 @@ static struct fp_dscv_dev *discover_dev(libusb_device *udev)
|
||||||
return ddev;
|
return ddev;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
|
* fp_discover_devs:
|
||||||
|
*
|
||||||
* Scans the system and returns a list of discovered devices. This is your
|
* Scans the system and returns a list of discovered devices. This is your
|
||||||
* entry point into finding a fingerprint reader to operate.
|
* entry point into finding a fingerprint reader to operate.
|
||||||
* \returns a NULL-terminated list of discovered devices. Must be freed with
|
*
|
||||||
|
* Returns: a %NULL-terminated list of discovered devices. Must be freed with
|
||||||
* fp_dscv_devs_free() after use.
|
* fp_dscv_devs_free() after use.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_dscv_dev **fp_discover_devs(void)
|
API_EXPORTED struct fp_dscv_dev **fp_discover_devs(void)
|
||||||
|
|
@ -582,12 +420,14 @@ API_EXPORTED struct fp_dscv_dev **fp_discover_devs(void)
|
||||||
return list;
|
return list;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
|
* fp_dscv_devs_free:
|
||||||
|
* @devs: the list of discovered devices. If %NULL, function simply
|
||||||
|
* returns.
|
||||||
|
*
|
||||||
* Free a list of discovered devices. This function destroys the list and all
|
* Free a list of discovered devices. This function destroys the list and all
|
||||||
* discovered devices that it included, so make sure you have opened your
|
* discovered devices that it included, so make sure you have opened your
|
||||||
* discovered device <b>before</b> freeing the list.
|
* discovered device <emphasis role="strong">before</emphasis> freeing the list.
|
||||||
* \param devs the list of discovered devices. If NULL, function simply
|
|
||||||
* returns.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs)
|
API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs)
|
||||||
{
|
{
|
||||||
|
|
@ -602,20 +442,26 @@ API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs)
|
||||||
g_free(devs);
|
g_free(devs);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
* Gets the \ref drv "driver" for a discovered device.
|
* fp_dscv_dev_get_driver:
|
||||||
* \param dev the discovered device
|
* @dev: the discovered device
|
||||||
* \returns the driver backing the device
|
*
|
||||||
|
* Gets the #fp_driver "driver" for a discovered device.
|
||||||
|
*
|
||||||
|
* Returns: the driver backing the device
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev)
|
API_EXPORTED struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev)
|
||||||
{
|
{
|
||||||
return dev->drv;
|
return dev->drv;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
* Gets the \ref devtype "devtype" for a discovered device.
|
* fp_dscv_dev_get_devtype:
|
||||||
* \param dev the discovered device
|
* @dev: the discovered device
|
||||||
* \returns the devtype of the device
|
*
|
||||||
|
* Gets the [devtype](advanced-topics.html#device-types) for a discovered device.
|
||||||
|
*
|
||||||
|
* Returns: the devtype of the device
|
||||||
*/
|
*/
|
||||||
API_EXPORTED uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev)
|
API_EXPORTED uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev)
|
||||||
{
|
{
|
||||||
|
|
@ -635,62 +481,74 @@ enum fp_print_data_type fpi_driver_get_data_type(struct fp_driver *drv)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
* Determines if a specific \ref print_data "stored print" appears to be
|
* fp_dscv_dev_supports_print_data:
|
||||||
|
* @dev: the discovered device
|
||||||
|
* @print: the print for compatibility checking
|
||||||
|
*
|
||||||
|
* Determines if a specific #fp_print_data "stored print" appears to be
|
||||||
* compatible with a discovered device.
|
* compatible with a discovered device.
|
||||||
* \param dev the discovered device
|
*
|
||||||
* \param data the print for compatibility checking
|
* Returns: 1 if the print is compatible with the device, 0 otherwise
|
||||||
* \returns 1 if the print is compatible with the device, 0 otherwise
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
|
API_EXPORTED int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
|
||||||
struct fp_print_data *data)
|
struct fp_print_data *print)
|
||||||
{
|
{
|
||||||
return fpi_print_data_compatible(dev->drv->id, dev->devtype,
|
return fpi_print_data_compatible(dev->drv->id, dev->devtype,
|
||||||
fpi_driver_get_data_type(dev->drv), data->driver_id, data->devtype,
|
fpi_driver_get_data_type(dev->drv), print->driver_id, print->devtype,
|
||||||
data->type);
|
print->type);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
* Determines if a specific \ref dscv_print "discovered print" appears to be
|
* fp_dscv_dev_supports_dscv_print:
|
||||||
|
* @dev: the discovered device
|
||||||
|
* @print: the discovered print for compatibility checking
|
||||||
|
*
|
||||||
|
* Determines if a specific #fp_dscv_print "discovered print" appears to be
|
||||||
* compatible with a discovered device.
|
* compatible with a discovered device.
|
||||||
* \param dev the discovered device
|
*
|
||||||
* \param data the discovered print for compatibility checking
|
* Returns: 1 if the print is compatible with the device, 0 otherwise
|
||||||
* \returns 1 if the print is compatible with the device, 0 otherwise
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
|
API_EXPORTED int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
|
||||||
struct fp_dscv_print *data)
|
struct fp_dscv_print *print)
|
||||||
{
|
{
|
||||||
return fpi_print_data_compatible(dev->drv->id, dev->devtype, 0,
|
return fpi_print_data_compatible(dev->drv->id, dev->devtype, 0,
|
||||||
data->driver_id, data->devtype, 0);
|
print->driver_id, print->devtype, 0);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
|
* fp_dscv_dev_for_print_data:
|
||||||
|
* @devs: a list of discovered devices
|
||||||
|
* @print: the print under inspection
|
||||||
|
*
|
||||||
* Searches a list of discovered devices for a device that appears to be
|
* Searches a list of discovered devices for a device that appears to be
|
||||||
* compatible with a \ref print_data "stored print".
|
* compatible with a #fp_print_data "stored print".
|
||||||
* \param devs a list of discovered devices
|
*
|
||||||
* \param data the print under inspection
|
* Returns: the first discovered device that appears to support the print, or
|
||||||
* \returns the first discovered device that appears to support the print, or
|
* %NULL if no apparently compatible devices could be found
|
||||||
* NULL if no apparently compatible devices could be found
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
|
API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
|
||||||
struct fp_print_data *data)
|
struct fp_print_data *print)
|
||||||
{
|
{
|
||||||
struct fp_dscv_dev *ddev;
|
struct fp_dscv_dev *ddev;
|
||||||
int i;
|
int i;
|
||||||
|
|
||||||
for (i = 0; (ddev = devs[i]); i++)
|
for (i = 0; (ddev = devs[i]); i++)
|
||||||
if (fp_dscv_dev_supports_print_data(ddev, data))
|
if (fp_dscv_dev_supports_print_data(ddev, print))
|
||||||
return ddev;
|
return ddev;
|
||||||
return NULL;
|
return NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_dev
|
/**
|
||||||
|
* fp_dscv_dev_for_dscv_print:
|
||||||
|
* @devs: a list of discovered devices
|
||||||
|
* @print: the print under inspection
|
||||||
|
*
|
||||||
* Searches a list of discovered devices for a device that appears to be
|
* Searches a list of discovered devices for a device that appears to be
|
||||||
* compatible with a \ref dscv_print "discovered print".
|
* compatible with a #fp_dscv_print "discovered print".
|
||||||
* \param devs a list of discovered devices
|
*
|
||||||
* \param print the print under inspection
|
* Returns: the first discovered device that appears to support the print, or
|
||||||
* \returns the first discovered device that appears to support the print, or
|
* %NULL if no apparently compatible devices could be found
|
||||||
* NULL if no apparently compatible devices could be found
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
|
API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
|
||||||
struct fp_dscv_print *print)
|
struct fp_dscv_print *print)
|
||||||
|
|
@ -704,42 +562,54 @@ API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev *
|
||||||
return NULL;
|
return NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Get the \ref drv "driver" for a fingerprint device.
|
* fp_dev_get_driver:
|
||||||
* \param dev the device
|
* @dev: the device
|
||||||
* \returns the driver controlling the device
|
*
|
||||||
|
* Get the #fp_driver "driver" for a fingerprint device.
|
||||||
|
*
|
||||||
|
* Returns: the driver controlling the device
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_driver *fp_dev_get_driver(struct fp_dev *dev)
|
API_EXPORTED struct fp_driver *fp_dev_get_driver(struct fp_dev *dev)
|
||||||
{
|
{
|
||||||
return dev->drv;
|
return dev->drv;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Gets the number of \ref enrolling "enroll stages" required to enroll a
|
* fp_dev_get_nr_enroll_stages:
|
||||||
|
* @dev: the device
|
||||||
|
*
|
||||||
|
* Gets the number of [enroll stages](intro.html#enrollment) required to enroll a
|
||||||
* fingerprint with the device.
|
* fingerprint with the device.
|
||||||
* \param dev the device
|
*
|
||||||
* \returns the number of enroll stages
|
* Returns: the number of enroll stages
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_get_nr_enroll_stages(struct fp_dev *dev)
|
API_EXPORTED int fp_dev_get_nr_enroll_stages(struct fp_dev *dev)
|
||||||
{
|
{
|
||||||
return dev->nr_enroll_stages;
|
return dev->nr_enroll_stages;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Gets the \ref devtype "devtype" for a device.
|
* fp_dev_get_devtype:
|
||||||
* \param dev the device
|
* @dev: the device
|
||||||
* \returns the devtype
|
*
|
||||||
|
* Gets the [devtype](advanced-topics.html#device-types) for a device.
|
||||||
|
*
|
||||||
|
* Returns: the devtype
|
||||||
*/
|
*/
|
||||||
API_EXPORTED uint32_t fp_dev_get_devtype(struct fp_dev *dev)
|
API_EXPORTED uint32_t fp_dev_get_devtype(struct fp_dev *dev)
|
||||||
{
|
{
|
||||||
return dev->devtype;
|
return dev->devtype;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_dev_supports_print_data:
|
||||||
|
* @dev: the device
|
||||||
|
* @data: the stored print
|
||||||
|
*
|
||||||
* Determines if a stored print is compatible with a certain device.
|
* Determines if a stored print is compatible with a certain device.
|
||||||
* \param dev the device
|
*
|
||||||
* \param data the stored print
|
* Returns: 1 if the print is compatible with the device, 0 if not
|
||||||
* \returns 1 if the print is compatible with the device, 0 if not
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev,
|
API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev,
|
||||||
struct fp_print_data *data)
|
struct fp_print_data *data)
|
||||||
|
|
@ -749,54 +619,69 @@ API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev,
|
||||||
data->type);
|
data->type);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Determines if a \ref dscv_print "discovered print" appears to be compatible
|
* fp_dev_supports_dscv_print:
|
||||||
|
* @dev: the device
|
||||||
|
* @print: the discovered print
|
||||||
|
*
|
||||||
|
* Determines if a #fp_dscv_print "discovered print" appears to be compatible
|
||||||
* with a certain device.
|
* with a certain device.
|
||||||
* \param dev the device
|
*
|
||||||
* \param data the discovered print
|
* Returns: 1 if the print is compatible with the device, 0 if not
|
||||||
* \returns 1 if the print is compatible with the device, 0 if not
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_supports_dscv_print(struct fp_dev *dev,
|
API_EXPORTED int fp_dev_supports_dscv_print(struct fp_dev *dev,
|
||||||
struct fp_dscv_print *data)
|
struct fp_dscv_print *print)
|
||||||
{
|
{
|
||||||
return fpi_print_data_compatible(dev->drv->id, dev->devtype,
|
return fpi_print_data_compatible(dev->drv->id, dev->devtype,
|
||||||
0, data->driver_id, data->devtype, 0);
|
0, print->driver_id, print->devtype, 0);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup drv
|
/**
|
||||||
|
* fp_driver_get_name:
|
||||||
|
* @drv: the driver
|
||||||
|
*
|
||||||
* Retrieves the name of the driver. For example: "upekts"
|
* Retrieves the name of the driver. For example: "upekts"
|
||||||
* \param drv the driver
|
*
|
||||||
* \returns the driver name. Must not be modified or freed.
|
* Returns: the driver name. Must not be modified or freed.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED const char *fp_driver_get_name(struct fp_driver *drv)
|
API_EXPORTED const char *fp_driver_get_name(struct fp_driver *drv)
|
||||||
{
|
{
|
||||||
return drv->name;
|
return drv->name;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup drv
|
/**
|
||||||
|
* fp_driver_get_full_name:
|
||||||
|
* @drv: the driver
|
||||||
|
*
|
||||||
* Retrieves a descriptive name of the driver. For example: "UPEK TouchStrip"
|
* Retrieves a descriptive name of the driver. For example: "UPEK TouchStrip"
|
||||||
* \param drv the driver
|
*
|
||||||
* \returns the descriptive name. Must not be modified or freed.
|
* Returns: the descriptive name. Must not be modified or freed.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED const char *fp_driver_get_full_name(struct fp_driver *drv)
|
API_EXPORTED const char *fp_driver_get_full_name(struct fp_driver *drv)
|
||||||
{
|
{
|
||||||
return drv->full_name;
|
return drv->full_name;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup drv
|
/**
|
||||||
|
* fp_driver_get_driver_id:
|
||||||
|
* @drv: the driver
|
||||||
|
*
|
||||||
* Retrieves the driver ID code for a driver.
|
* Retrieves the driver ID code for a driver.
|
||||||
* \param drv the driver
|
*
|
||||||
* \returns the driver ID
|
* Returns: the driver ID
|
||||||
*/
|
*/
|
||||||
API_EXPORTED uint16_t fp_driver_get_driver_id(struct fp_driver *drv)
|
API_EXPORTED uint16_t fp_driver_get_driver_id(struct fp_driver *drv)
|
||||||
{
|
{
|
||||||
return drv->id;
|
return drv->id;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup drv
|
/**
|
||||||
|
* fp_driver_get_scan_type:
|
||||||
|
* @drv: the driver
|
||||||
|
*
|
||||||
* Retrieves the scan type for the devices associated with the driver.
|
* Retrieves the scan type for the devices associated with the driver.
|
||||||
* \param drv the driver
|
*
|
||||||
* \returns the scan type
|
* Returns: the scan type
|
||||||
*/
|
*/
|
||||||
API_EXPORTED enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv)
|
API_EXPORTED enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv)
|
||||||
{
|
{
|
||||||
|
|
@ -810,14 +695,17 @@ static struct fp_img_dev *dev_to_img_dev(struct fp_dev *dev)
|
||||||
return dev->priv;
|
return dev->priv;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_dev_supports_imaging:
|
||||||
|
* @dev: the fingerprint device
|
||||||
|
*
|
||||||
* Determines if a device has imaging capabilities. If a device has imaging
|
* Determines if a device has imaging capabilities. If a device has imaging
|
||||||
* capabilities you are able to perform imaging operations such as retrieving
|
* capabilities you are able to perform imaging operations such as retrieving
|
||||||
* scan images using fp_dev_img_capture(). However, not all devices are
|
* scan images using fp_dev_img_capture(). However, not all devices are
|
||||||
* imaging devices - some do all processing in hardware. This function will
|
* imaging devices - some do all processing in hardware. This function will
|
||||||
* indicate which class a device in question falls into.
|
* indicate which class a device in question falls into.
|
||||||
* \param dev the fingerprint device
|
*
|
||||||
* \returns 1 if the device is an imaging device, 0 if the device does not
|
* Returns: 1 if the device is an imaging device, 0 if the device does not
|
||||||
* provide images to the host computer
|
* provide images to the host computer
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_supports_imaging(struct fp_dev *dev)
|
API_EXPORTED int fp_dev_supports_imaging(struct fp_dev *dev)
|
||||||
|
|
@ -825,25 +713,31 @@ API_EXPORTED int fp_dev_supports_imaging(struct fp_dev *dev)
|
||||||
return dev->drv->capture_start != NULL;
|
return dev->drv->capture_start != NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Determines if a device is capable of \ref identification "identification"
|
* fp_dev_supports_identification:
|
||||||
|
* @dev: the fingerprint device
|
||||||
|
*
|
||||||
|
* Determines if a device is capable of [identification](intro.html#identification)
|
||||||
* through fp_identify_finger() and similar. Not all devices support this
|
* through fp_identify_finger() and similar. Not all devices support this
|
||||||
* functionality.
|
* functionality.
|
||||||
* \param dev the fingerprint device
|
*
|
||||||
* \returns 1 if the device is capable of identification, 0 otherwise.
|
* Returns: 1 if the device is capable of identification, 0 otherwise.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_supports_identification(struct fp_dev *dev)
|
API_EXPORTED int fp_dev_supports_identification(struct fp_dev *dev)
|
||||||
{
|
{
|
||||||
return dev->drv->identify_start != NULL;
|
return dev->drv->identify_start != NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_dev_get_img_width:
|
||||||
|
* @dev: the fingerprint device
|
||||||
|
*
|
||||||
* Gets the expected width of images that will be captured from the device.
|
* Gets the expected width of images that will be captured from the device.
|
||||||
* This function will return -1 for devices that are not
|
* This function will return -1 for devices that are not
|
||||||
* \ref imaging "imaging devices". If the width of images from this device
|
* [imaging devices](libfprint-Devices-operations.html#imaging). If the width of images from this device
|
||||||
* can vary, 0 will be returned.
|
* can vary, 0 will be returned.
|
||||||
* \param dev the device
|
*
|
||||||
* \returns the expected image width, or 0 for variable, or -1 for non-imaging
|
* Returns: the expected image width, or 0 for variable, or -1 for non-imaging
|
||||||
* devices.
|
* devices.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_get_img_width(struct fp_dev *dev)
|
API_EXPORTED int fp_dev_get_img_width(struct fp_dev *dev)
|
||||||
|
|
@ -857,13 +751,16 @@ API_EXPORTED int fp_dev_get_img_width(struct fp_dev *dev)
|
||||||
return fpi_imgdev_get_img_width(imgdev);
|
return fpi_imgdev_get_img_width(imgdev);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_dev_get_img_height:
|
||||||
|
* @dev: the fingerprint device
|
||||||
|
*
|
||||||
* Gets the expected height of images that will be captured from the device.
|
* Gets the expected height of images that will be captured from the device.
|
||||||
* This function will return -1 for devices that are not
|
* This function will return -1 for devices that are not
|
||||||
* \ref imaging "imaging devices". If the height of images from this device
|
* [imaging devices](libfprint-Devices-operations.html#imaging). If the height of images from this device
|
||||||
* can vary, 0 will be returned.
|
* can vary, 0 will be returned.
|
||||||
* \param dev the device
|
*
|
||||||
* \returns the expected image height, or 0 for variable, or -1 for non-imaging
|
* Returns: the expected image height, or 0 for variable, or -1 for non-imaging
|
||||||
* devices.
|
* devices.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev)
|
API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev)
|
||||||
|
|
@ -877,7 +774,10 @@ API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev)
|
||||||
return fpi_imgdev_get_img_height(imgdev);
|
return fpi_imgdev_get_img_height(imgdev);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup core
|
/**
|
||||||
|
* fp_set_debug:
|
||||||
|
* @level: the verbosity level
|
||||||
|
*
|
||||||
* Set message verbosity.
|
* Set message verbosity.
|
||||||
* - Level 0: no messages ever printed by the library (default)
|
* - Level 0: no messages ever printed by the library (default)
|
||||||
* - Level 1: error messages are printed to stderr
|
* - Level 1: error messages are printed to stderr
|
||||||
|
|
@ -902,9 +802,6 @@ API_EXPORTED int fp_dev_get_img_height(struct fp_dev *dev)
|
||||||
*
|
*
|
||||||
* If libfprint was compiled with verbose debug message logging, this function
|
* If libfprint was compiled with verbose debug message logging, this function
|
||||||
* does nothing: you'll always get messages from all levels.
|
* does nothing: you'll always get messages from all levels.
|
||||||
*
|
|
||||||
* \param ctx the context to operate on, or NULL for the default context
|
|
||||||
* \param level debug level to set
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED void fp_set_debug(int level)
|
API_EXPORTED void fp_set_debug(int level)
|
||||||
{
|
{
|
||||||
|
|
@ -915,10 +812,13 @@ API_EXPORTED void fp_set_debug(int level)
|
||||||
libusb_set_debug(fpi_usb_ctx, level);
|
libusb_set_debug(fpi_usb_ctx, level);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup core
|
/**
|
||||||
|
* fp_init:
|
||||||
|
*
|
||||||
* Initialise libfprint. This function must be called before you attempt to
|
* Initialise libfprint. This function must be called before you attempt to
|
||||||
* use the library in any way.
|
* use the library in any way.
|
||||||
* \return 0 on success, non-zero on error.
|
*
|
||||||
|
* Returns: 0 on success, non-zero on error.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_init(void)
|
API_EXPORTED int fp_init(void)
|
||||||
{
|
{
|
||||||
|
|
@ -943,7 +843,9 @@ API_EXPORTED int fp_init(void)
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup core
|
/**
|
||||||
|
* fp_exit:
|
||||||
|
*
|
||||||
* Deinitialise libfprint. This function should be called during your program
|
* Deinitialise libfprint. This function should be called during your program
|
||||||
* exit sequence. You must not use any libfprint functions after calling this
|
* exit sequence. You must not use any libfprint functions after calling this
|
||||||
* function, unless you call fp_init() again.
|
* function, unless you call fp_init() again.
|
||||||
|
|
|
||||||
173
libfprint/data.c
173
libfprint/data.c
|
|
@ -32,8 +32,11 @@
|
||||||
|
|
||||||
#define DIR_PERMS 0700
|
#define DIR_PERMS 0700
|
||||||
|
|
||||||
/** @defgroup print_data Stored prints
|
/**
|
||||||
* Stored prints are represented by a structure named <tt>fp_print_data</tt>.
|
* SECTION: print_data
|
||||||
|
* @title: Stored prints
|
||||||
|
*
|
||||||
|
* Stored prints are represented by a structure named #fp_print_data.
|
||||||
* Stored prints are originally obtained from an enrollment function such as
|
* Stored prints are originally obtained from an enrollment function such as
|
||||||
* fp_enroll_finger().
|
* fp_enroll_finger().
|
||||||
*
|
*
|
||||||
|
|
@ -124,14 +127,17 @@ struct fp_print_data *fpi_print_data_new(struct fp_dev *dev)
|
||||||
fpi_driver_get_data_type(dev->drv));
|
fpi_driver_get_data_type(dev->drv));
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
|
* fp_print_data_get_data:
|
||||||
|
* @data: the stored print
|
||||||
|
* @ret: output location for the data buffer. Must be freed with free()
|
||||||
|
* after use.
|
||||||
|
|
||||||
* Convert a stored print into a unified representation inside a data buffer.
|
* Convert a stored print into a unified representation inside a data buffer.
|
||||||
* You can then store this data buffer in any way that suits you, and load
|
* You can then store this data buffer in any way that suits you, and load
|
||||||
* it back at some later time using fp_print_data_from_data().
|
* it back at some later time using fp_print_data_from_data().
|
||||||
* \param data the stored print
|
*
|
||||||
* \param ret output location for the data buffer. Must be freed with free()
|
* Returns: the size of the freshly allocated buffer, or 0 on error.
|
||||||
* after use.
|
|
||||||
* \returns the size of the freshly allocated buffer, or 0 on error.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED size_t fp_print_data_get_data(struct fp_print_data *data,
|
API_EXPORTED size_t fp_print_data_get_data(struct fp_print_data *data,
|
||||||
unsigned char **ret)
|
unsigned char **ret)
|
||||||
|
|
@ -245,13 +251,16 @@ static struct fp_print_data *fpi_print_data_from_fp2_data(unsigned char *buf,
|
||||||
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
|
* fp_print_data_from_data:
|
||||||
|
* @buf: the data buffer
|
||||||
|
* @buflen: the length of the buffer
|
||||||
|
|
||||||
* Load a stored print from a data buffer. The contents of said buffer must
|
* Load a stored print from a data buffer. The contents of said buffer must
|
||||||
* be the untouched contents of a buffer previously supplied to you by the
|
* be the untouched contents of a buffer previously supplied to you by the
|
||||||
* fp_print_data_get_data() function.
|
* fp_print_data_get_data() function.
|
||||||
* \param buf the data buffer
|
*
|
||||||
* \param buflen the length of the buffer
|
* Returns: the stored print represented by the data, or %NULL on error. Must
|
||||||
* \returns the stored print represented by the data, or NULL on error. Must
|
|
||||||
* be freed with fp_print_data_free() after use.
|
* be freed with fp_print_data_free() after use.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
|
API_EXPORTED struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
|
||||||
|
|
@ -305,7 +314,11 @@ static char *get_path_to_print(struct fp_dev *dev, enum fp_finger finger)
|
||||||
return __get_path_to_print(dev->drv->id, dev->devtype, finger);
|
return __get_path_to_print(dev->drv->id, dev->devtype, finger);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
|
* fp_print_data_save:
|
||||||
|
* @data: the stored print to save to disk
|
||||||
|
* @finger: the finger that this print corresponds to
|
||||||
|
*
|
||||||
* Saves a stored print to disk, assigned to a specific finger. Even though
|
* Saves a stored print to disk, assigned to a specific finger. Even though
|
||||||
* you are limited to storing only the 10 human fingers, this is a
|
* you are limited to storing only the 10 human fingers, this is a
|
||||||
* per-device-type limit. For example, you can store the users right index
|
* per-device-type limit. For example, you can store the users right index
|
||||||
|
|
@ -316,9 +329,8 @@ static char *get_path_to_print(struct fp_dev *dev, enum fp_finger finger)
|
||||||
* This function will unconditionally overwrite a fingerprint previously
|
* This function will unconditionally overwrite a fingerprint previously
|
||||||
* saved for the same finger and device type. The print is saved in a hidden
|
* saved for the same finger and device type. The print is saved in a hidden
|
||||||
* directory beneath the current user's home directory.
|
* directory beneath the current user's home directory.
|
||||||
* \param data the stored print to save to disk
|
*
|
||||||
* \param finger the finger that this print corresponds to
|
* Returns: 0 on success, non-zero on error.
|
||||||
* \returns 0 on success, non-zero on error.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_print_data_save(struct fp_print_data *data,
|
API_EXPORTED int fp_print_data_save(struct fp_print_data *data,
|
||||||
enum fp_finger finger)
|
enum fp_finger finger)
|
||||||
|
|
@ -415,7 +427,13 @@ static int load_from_file(char *path, struct fp_print_data **data)
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
|
* fp_print_data_load:
|
||||||
|
* @dev: the device you are loading the print for
|
||||||
|
* @finger: the finger of the file you are loading
|
||||||
|
* @data: output location to put the corresponding stored print. Must be
|
||||||
|
* freed with fp_print_data_free() after use.
|
||||||
|
|
||||||
* Loads a previously stored print from disk. The print must have been saved
|
* Loads a previously stored print from disk. The print must have been saved
|
||||||
* earlier using the fp_print_data_save() function.
|
* earlier using the fp_print_data_save() function.
|
||||||
*
|
*
|
||||||
|
|
@ -423,11 +441,7 @@ static int load_from_file(char *path, struct fp_print_data **data)
|
||||||
* be found. Other error codes (both positive and negative) are possible for
|
* be found. Other error codes (both positive and negative) are possible for
|
||||||
* obscure error conditions (e.g. corruption).
|
* obscure error conditions (e.g. corruption).
|
||||||
*
|
*
|
||||||
* \param dev the device you are loading the print for
|
* Returns: 0 on success, non-zero on error
|
||||||
* \param finger the finger of the file you are loading
|
|
||||||
* \param data output location to put the corresponding stored print. Must be
|
|
||||||
* freed with fp_print_data_free() after use.
|
|
||||||
* \returns 0 on success, non-zero on error
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_print_data_load(struct fp_dev *dev,
|
API_EXPORTED int fp_print_data_load(struct fp_dev *dev,
|
||||||
enum fp_finger finger, struct fp_print_data **data)
|
enum fp_finger finger, struct fp_print_data **data)
|
||||||
|
|
@ -455,11 +469,14 @@ API_EXPORTED int fp_print_data_load(struct fp_dev *dev,
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
|
* fp_print_data_delete:
|
||||||
|
* @dev: the device that the print belongs to
|
||||||
|
* @finger: the finger of the file you are deleting
|
||||||
|
|
||||||
* Removes a stored print from disk previously saved with fp_print_data_save().
|
* Removes a stored print from disk previously saved with fp_print_data_save().
|
||||||
* \param dev the device that the print belongs to
|
*
|
||||||
* \param finger the finger of the file you are deleting
|
* Returns: 0 on success, negative on error
|
||||||
* \returns 0 on success, negative on error
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_print_data_delete(struct fp_dev *dev,
|
API_EXPORTED int fp_print_data_delete(struct fp_dev *dev,
|
||||||
enum fp_finger finger)
|
enum fp_finger finger)
|
||||||
|
|
@ -477,18 +494,20 @@ API_EXPORTED int fp_print_data_delete(struct fp_dev *dev,
|
||||||
return r;
|
return r;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
* Attempts to load a stored print based on a \ref dscv_print
|
* fp_print_data_from_dscv_print:
|
||||||
|
* @print: the discovered print
|
||||||
|
* @data: output location to point to the corresponding stored print. Must
|
||||||
|
* be freed with fp_print_data_free() after use.
|
||||||
|
|
||||||
|
* Attempts to load a stored print based on a #fp_dscv_print
|
||||||
* "discovered print" record.
|
* "discovered print" record.
|
||||||
*
|
*
|
||||||
* A return code of -ENOENT indicates that the file referred to by the
|
* A return code of -ENOENT indicates that the file referred to by the
|
||||||
* discovered print could not be found. Other error codes (both positive and
|
* discovered print could not be found. Other error codes (both positive and
|
||||||
* negative) are possible for obscure error conditions (e.g. corruption).
|
* negative) are possible for obscure error conditions (e.g. corruption).
|
||||||
*
|
*
|
||||||
* \param print the discovered print
|
* Returns: 0 on success, non-zero on error.
|
||||||
* \param data output location to point to the corresponding stored print. Must
|
|
||||||
* be freed with fp_print_data_free() after use.
|
|
||||||
* \returns 0 on success, non-zero on error.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
|
API_EXPORTED int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
|
||||||
struct fp_print_data **data)
|
struct fp_print_data **data)
|
||||||
|
|
@ -496,9 +515,11 @@ API_EXPORTED int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
|
||||||
return load_from_file(print->path, data);
|
return load_from_file(print->path, data);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
|
* fp_print_data_free:
|
||||||
|
* @data: the stored print to destroy. If NULL, function simply returns.
|
||||||
|
*
|
||||||
* Frees a stored print. Must be called when you are finished using the print.
|
* Frees a stored print. Must be called when you are finished using the print.
|
||||||
* \param data the stored print to destroy. If NULL, function simply returns.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED void fp_print_data_free(struct fp_print_data *data)
|
API_EXPORTED void fp_print_data_free(struct fp_print_data *data)
|
||||||
{
|
{
|
||||||
|
|
@ -507,31 +528,40 @@ API_EXPORTED void fp_print_data_free(struct fp_print_data *data)
|
||||||
g_free(data);
|
g_free(data);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
* Gets the \ref driver_id "driver ID" for a stored print. The driver ID
|
* fp_print_data_get_driver_id:
|
||||||
|
* @data: the stored print
|
||||||
|
|
||||||
|
* Gets the [driver ID](advanced-topics.html#driver_id) for a stored print. The driver ID
|
||||||
* indicates which driver the print originally came from. The print is
|
* indicates which driver the print originally came from. The print is
|
||||||
* only usable with a device controlled by that driver.
|
* only usable with a device controlled by that driver.
|
||||||
* \param data the stored print
|
*
|
||||||
* \returns the driver ID of the driver compatible with the print
|
* Returns: the driver ID of the driver compatible with the print
|
||||||
*/
|
*/
|
||||||
API_EXPORTED uint16_t fp_print_data_get_driver_id(struct fp_print_data *data)
|
API_EXPORTED uint16_t fp_print_data_get_driver_id(struct fp_print_data *data)
|
||||||
{
|
{
|
||||||
return data->driver_id;
|
return data->driver_id;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
* Gets the \ref devtype "devtype" for a stored print. The devtype represents
|
* fp_print_data_get_devtype:
|
||||||
|
* @data: the stored print
|
||||||
|
|
||||||
|
* Gets the [devtype](advanced-topics.html#device-types) for a stored print. The devtype represents
|
||||||
* which type of device under the parent driver is compatible with the print.
|
* which type of device under the parent driver is compatible with the print.
|
||||||
* \param data the stored print
|
*
|
||||||
* \returns the devtype of the device range compatible with the print
|
* Returns: the devtype of the device range compatible with the print
|
||||||
*/
|
*/
|
||||||
API_EXPORTED uint32_t fp_print_data_get_devtype(struct fp_print_data *data)
|
API_EXPORTED uint32_t fp_print_data_get_devtype(struct fp_print_data *data)
|
||||||
{
|
{
|
||||||
return data->devtype;
|
return data->devtype;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** @defgroup dscv_print Print discovery
|
/**
|
||||||
* The \ref print_data "stored print" documentation detailed a simple API
|
* SECTION:dscv_print
|
||||||
|
* @title: Print discovery
|
||||||
|
*
|
||||||
|
* The [stored print](libfprint-Stored-prints.html) documentation detailed a simple API
|
||||||
* for storing per-device prints for a single user, namely
|
* for storing per-device prints for a single user, namely
|
||||||
* fp_print_data_save(). It also detailed a load function,
|
* fp_print_data_save(). It also detailed a load function,
|
||||||
* fp_print_data_load(), but usage of this function is limited to scenarios
|
* fp_print_data_load(), but usage of this function is limited to scenarios
|
||||||
|
|
@ -542,7 +572,7 @@ API_EXPORTED uint32_t fp_print_data_get_devtype(struct fp_print_data *data)
|
||||||
* previously saved prints, potentially even before device discovery. These
|
* previously saved prints, potentially even before device discovery. These
|
||||||
* functions are designed to offer this functionality to you.
|
* functions are designed to offer this functionality to you.
|
||||||
*
|
*
|
||||||
* Discovered prints are stored in a <tt>dscv_print</tt> structure, and you
|
* Discovered prints are stored in a #fp_dscv_print structure, and you
|
||||||
* can use functions documented below to access some information about these
|
* can use functions documented below to access some information about these
|
||||||
* prints. You can determine if a discovered print appears to be compatible
|
* prints. You can determine if a discovered print appears to be compatible
|
||||||
* with a device using functions such as fp_dscv_dev_supports_dscv_print() and
|
* with a device using functions such as fp_dscv_dev_supports_dscv_print() and
|
||||||
|
|
@ -643,10 +673,13 @@ static GSList *scan_driver_store_dir(char *drvpath, uint16_t driver_id,
|
||||||
return list;
|
return list;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_print
|
/**
|
||||||
|
* fp_discover_prints:
|
||||||
|
*
|
||||||
* Scans the users home directory and returns a list of prints that were
|
* Scans the users home directory and returns a list of prints that were
|
||||||
* previously saved using fp_print_data_save().
|
* previously saved using fp_print_data_save().
|
||||||
* \returns a NULL-terminated list of discovered prints, must be freed with
|
*
|
||||||
|
* Returns: a %NULL-terminated list of discovered prints, must be freed with
|
||||||
* fp_dscv_prints_free() after use.
|
* fp_dscv_prints_free() after use.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_dscv_print **fp_discover_prints(void)
|
API_EXPORTED struct fp_dscv_print **fp_discover_prints(void)
|
||||||
|
|
@ -704,12 +737,14 @@ API_EXPORTED struct fp_dscv_print **fp_discover_prints(void)
|
||||||
return list;
|
return list;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_print
|
/**
|
||||||
|
* fp_dscv_prints_free:
|
||||||
|
* @prints: the list of discovered prints. If NULL, function simply
|
||||||
|
* returns.
|
||||||
|
*
|
||||||
* Frees a list of discovered prints. This function also frees the discovered
|
* Frees a list of discovered prints. This function also frees the discovered
|
||||||
* prints themselves, so make sure you do not use any discovered prints
|
* prints themselves, so make sure you do not use any discovered prints
|
||||||
* after calling this function.
|
* after calling this function.
|
||||||
* \param prints the list of discovered prints. If NULL, function simply
|
|
||||||
* returns.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED void fp_dscv_prints_free(struct fp_dscv_print **prints)
|
API_EXPORTED void fp_dscv_prints_free(struct fp_dscv_print **prints)
|
||||||
{
|
{
|
||||||
|
|
@ -727,47 +762,59 @@ API_EXPORTED void fp_dscv_prints_free(struct fp_dscv_print **prints)
|
||||||
g_free(prints);
|
g_free(prints);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_print
|
/**
|
||||||
* Gets the \ref driver_id "driver ID" for a discovered print. The driver ID
|
* fp_dscv_print_get_driver_id:
|
||||||
|
* @print: the discovered print
|
||||||
|
*
|
||||||
|
* Gets the [driver ID](advanced-topics.html#driver_id) for a discovered print. The driver ID
|
||||||
* indicates which driver the print originally came from. The print is only
|
* indicates which driver the print originally came from. The print is only
|
||||||
* usable with a device controlled by that driver.
|
* usable with a device controlled by that driver.
|
||||||
* \param print the discovered print
|
*
|
||||||
* \returns the driver ID of the driver compatible with the print
|
* Returns: the driver ID of the driver compatible with the print
|
||||||
*/
|
*/
|
||||||
API_EXPORTED uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print)
|
API_EXPORTED uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print)
|
||||||
{
|
{
|
||||||
return print->driver_id;
|
return print->driver_id;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_print
|
/**
|
||||||
* Gets the \ref devtype "devtype" for a discovered print. The devtype
|
* fp_dscv_print_get_devtype:
|
||||||
|
* @print: the discovered print
|
||||||
|
*
|
||||||
|
* Gets the [devtype](advanced-topics.html#device-types) for a discovered print. The devtype
|
||||||
* represents which type of device under the parent driver is compatible
|
* represents which type of device under the parent driver is compatible
|
||||||
* with the print.
|
* with the print.
|
||||||
* \param print the discovered print
|
*
|
||||||
* \returns the devtype of the device range compatible with the print
|
* Returns: the devtype of the device range compatible with the print
|
||||||
*/
|
*/
|
||||||
API_EXPORTED uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print)
|
API_EXPORTED uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print)
|
||||||
{
|
{
|
||||||
return print->devtype;
|
return print->devtype;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_print
|
/**
|
||||||
|
* fp_dscv_print_get_finger:
|
||||||
|
* @print: discovered print
|
||||||
|
*
|
||||||
* Gets the finger code for a discovered print.
|
* Gets the finger code for a discovered print.
|
||||||
* \param print discovered print
|
*
|
||||||
* \returns a finger code from #fp_finger
|
* Returns: a finger code from #fp_finger
|
||||||
*/
|
*/
|
||||||
API_EXPORTED enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print)
|
API_EXPORTED enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print)
|
||||||
{
|
{
|
||||||
return print->finger;
|
return print->finger;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dscv_print
|
/**
|
||||||
|
* fp_dscv_print_delete:
|
||||||
|
* @print: the discovered print to remove from disk
|
||||||
|
*
|
||||||
* Removes a discovered print from disk. After successful return of this
|
* Removes a discovered print from disk. After successful return of this
|
||||||
* function, functions such as fp_dscv_print_get_finger() will continue to
|
* function, functions such as fp_dscv_print_get_finger() will continue to
|
||||||
* operate as before, however calling fp_print_data_from_dscv_print() will
|
* operate as before, however calling fp_print_data_from_dscv_print() will
|
||||||
* fail for obvious reasons.
|
* fail for obvious reasons.
|
||||||
* \param print the discovered print to remove from disk
|
*
|
||||||
* \returns 0 on success, negative on error
|
* Returns: 0 on success, negative on error
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dscv_print_delete(struct fp_dscv_print *print)
|
API_EXPORTED int fp_dscv_print_delete(struct fp_dscv_print *print)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -27,42 +27,86 @@ extern "C" {
|
||||||
#include <stdint.h>
|
#include <stdint.h>
|
||||||
#include <sys/time.h>
|
#include <sys/time.h>
|
||||||
|
|
||||||
/* structs that applications are not allowed to peek into */
|
/**
|
||||||
|
* fp_dscv_dev:
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct fp_dscv_dev;
|
struct fp_dscv_dev;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_dscv_print:
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct fp_dscv_print;
|
struct fp_dscv_print;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_dev:
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct fp_dev;
|
struct fp_dev;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_driver:
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct fp_driver;
|
struct fp_driver;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_print_data:
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct fp_print_data;
|
struct fp_print_data;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_img:
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct fp_img;
|
struct fp_img;
|
||||||
|
|
||||||
/* misc/general stuff */
|
/* misc/general stuff */
|
||||||
|
|
||||||
/** \ingroup print_data
|
/**
|
||||||
|
* 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
|
* 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
|
* purposely not available as strings, to avoid getting the library tangled up
|
||||||
* in localization efforts.
|
* in localization efforts.
|
||||||
*/
|
*/
|
||||||
enum fp_finger {
|
enum fp_finger {
|
||||||
LEFT_THUMB = 1, /** thumb (left hand) */
|
LEFT_THUMB = 1,
|
||||||
LEFT_INDEX, /** index finger (left hand) */
|
LEFT_INDEX,
|
||||||
LEFT_MIDDLE, /** middle finger (left hand) */
|
LEFT_MIDDLE,
|
||||||
LEFT_RING, /** ring finger (left hand) */
|
LEFT_RING,
|
||||||
LEFT_LITTLE, /** little finger (left hand) */
|
LEFT_LITTLE,
|
||||||
RIGHT_THUMB, /** thumb (right hand) */
|
RIGHT_THUMB,
|
||||||
RIGHT_INDEX, /** index finger (right hand) */
|
RIGHT_INDEX,
|
||||||
RIGHT_MIDDLE, /** middle finger (right hand) */
|
RIGHT_MIDDLE,
|
||||||
RIGHT_RING, /** ring finger (right hand) */
|
RIGHT_RING,
|
||||||
RIGHT_LITTLE, /** little finger (right hand) */
|
RIGHT_LITTLE,
|
||||||
};
|
};
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* 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
|
* 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
|
* either swiping or pressing the finger on the device. This is useful for
|
||||||
* front-ends.
|
* front-ends.
|
||||||
*/
|
*/
|
||||||
enum fp_scan_type {
|
enum fp_scan_type {
|
||||||
FP_SCAN_TYPE_PRESS = 0, /** press */
|
FP_SCAN_TYPE_PRESS = 0,
|
||||||
FP_SCAN_TYPE_SWIPE, /** swipe */
|
FP_SCAN_TYPE_SWIPE,
|
||||||
};
|
};
|
||||||
|
|
||||||
/* Drivers */
|
/* Drivers */
|
||||||
|
|
@ -85,6 +129,12 @@ struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
|
||||||
struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
|
struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
|
||||||
struct fp_dscv_print *print);
|
struct fp_dscv_print *print);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_dscv_dev_get_driver_id:
|
||||||
|
* @dev: a discovered fingerprint device
|
||||||
|
*
|
||||||
|
* Returns: the ID for the underlying driver for that device
|
||||||
|
*/
|
||||||
static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
|
static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
|
||||||
{
|
{
|
||||||
return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
|
return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
|
||||||
|
|
@ -107,68 +157,75 @@ 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_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);
|
int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Image capture result codes returned from fp_dev_img_capture().
|
* fp_capture_result:
|
||||||
|
* Whether a capture failed or completed.
|
||||||
|
*
|
||||||
|
* @FP_CAPTURE_COMPLETE: Capture completed successfully, the capture data has been returned to the caller.
|
||||||
|
* @FP_CAPTURE_FAIL: Capture failed
|
||||||
|
*
|
||||||
*/
|
*/
|
||||||
enum fp_capture_result {
|
enum fp_capture_result {
|
||||||
/** Capture completed successfully, the capture data has been
|
|
||||||
* returned to the caller. */
|
|
||||||
FP_CAPTURE_COMPLETE = 0,
|
FP_CAPTURE_COMPLETE = 0,
|
||||||
/** Capture failed for some reason */
|
|
||||||
FP_CAPTURE_FAIL,
|
FP_CAPTURE_FAIL,
|
||||||
};
|
};
|
||||||
|
|
||||||
int fp_dev_supports_imaging(struct fp_dev *dev);
|
int fp_dev_supports_imaging(struct fp_dev *dev);
|
||||||
int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
|
int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
|
||||||
struct fp_img **image);
|
struct fp_img **img);
|
||||||
int fp_dev_get_img_width(struct fp_dev *dev);
|
int fp_dev_get_img_width(struct fp_dev *dev);
|
||||||
int fp_dev_get_img_height(struct fp_dev *dev);
|
int fp_dev_get_img_height(struct fp_dev *dev);
|
||||||
|
|
||||||
/** \ingroup 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().
|
* Enrollment result codes returned from fp_enroll_finger().
|
||||||
* Result codes with RETRY in the name suggest that the scan failed due to
|
* 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
|
* 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
|
* problem and then retry the enrollment stage. For more info on the semantics
|
||||||
* of interpreting these result codes and tracking enrollment process, see
|
* of interpreting these result codes and tracking enrollment process, see
|
||||||
* \ref enrolling.
|
* [Enrolling](libfprint-Devices-operations.html#enrolling)
|
||||||
*/
|
*/
|
||||||
enum fp_enroll_result {
|
enum fp_enroll_result {
|
||||||
/** Enrollment completed successfully, the enrollment data has been
|
|
||||||
* returned to the caller. */
|
|
||||||
FP_ENROLL_COMPLETE = 1,
|
FP_ENROLL_COMPLETE = 1,
|
||||||
/** Enrollment failed due to incomprehensible data; this may occur when
|
|
||||||
* the user scans a different finger on each enroll stage. */
|
|
||||||
FP_ENROLL_FAIL,
|
FP_ENROLL_FAIL,
|
||||||
/** Enroll stage passed; more stages are need to complete the process. */
|
|
||||||
FP_ENROLL_PASS,
|
FP_ENROLL_PASS,
|
||||||
/** The enrollment scan did not succeed due to poor scan quality or
|
|
||||||
* other general user scanning problem. */
|
|
||||||
FP_ENROLL_RETRY = 100,
|
FP_ENROLL_RETRY = 100,
|
||||||
/** The enrollment scan did not succeed because the finger swipe was
|
|
||||||
* too short. */
|
|
||||||
FP_ENROLL_RETRY_TOO_SHORT,
|
FP_ENROLL_RETRY_TOO_SHORT,
|
||||||
/** The enrollment scan did not succeed because the finger was not
|
|
||||||
* centered on the scanner. */
|
|
||||||
FP_ENROLL_RETRY_CENTER_FINGER,
|
FP_ENROLL_RETRY_CENTER_FINGER,
|
||||||
/** The verification scan did not succeed due to quality or pressure
|
|
||||||
* problems; the user should remove their finger from the scanner before
|
|
||||||
* retrying. */
|
|
||||||
FP_ENROLL_RETRY_REMOVE_FINGER,
|
FP_ENROLL_RETRY_REMOVE_FINGER,
|
||||||
};
|
};
|
||||||
|
|
||||||
int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
|
int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
|
||||||
struct fp_img **img);
|
struct fp_img **img);
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Performs an enroll stage. See \ref enrolling for an explanation of enroll
|
* fp_enroll_finger:
|
||||||
* stages. This function is just a shortcut to calling fp_enroll_finger_img()
|
* @dev: the device
|
||||||
* with a NULL image parameter. Be sure to read the description of
|
* @print_data: a location to return the resultant enrollment data from
|
||||||
* fp_enroll_finger_img() in order to understand its behaviour.
|
|
||||||
*
|
|
||||||
* \param dev the device
|
|
||||||
* \param print_data a location to return the resultant enrollment data from
|
|
||||||
* the final stage. Must be freed with fp_print_data_free() after use.
|
* the final stage. Must be freed with fp_print_data_free() after use.
|
||||||
* \return negative code on error, otherwise a code from #fp_enroll_result
|
*
|
||||||
|
* Performs an enroll stage. See [Enrolling](libfprint-Devices-operations.html#enrolling)
|
||||||
|
* for an explanation of enroll stages. This function is just a shortcut to
|
||||||
|
* calling fp_enroll_finger_img() with a %NULL image parameter. Be sure to read
|
||||||
|
* the description of fp_enroll_finger_img() in order to understand its behaviour.
|
||||||
|
*
|
||||||
|
* Returns: negative code on error, otherwise a code from #fp_enroll_result
|
||||||
*/
|
*/
|
||||||
static inline int fp_enroll_finger(struct fp_dev *dev,
|
static inline int fp_enroll_finger(struct fp_dev *dev,
|
||||||
struct fp_print_data **print_data)
|
struct fp_print_data **print_data)
|
||||||
|
|
@ -176,7 +233,23 @@ static inline int fp_enroll_finger(struct fp_dev *dev,
|
||||||
return fp_enroll_finger_img(dev, print_data, NULL);
|
return fp_enroll_finger_img(dev, print_data, NULL);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* 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
|
* Verification result codes returned from fp_verify_finger(). Return codes
|
||||||
* are also shared with fp_identify_finger().
|
* are also shared with fp_identify_finger().
|
||||||
* Result codes with RETRY in the name suggest that the scan failed due to
|
* Result codes with RETRY in the name suggest that the scan failed due to
|
||||||
|
|
@ -184,39 +257,28 @@ static inline int fp_enroll_finger(struct fp_dev *dev,
|
||||||
* problem and then retry the verify operation.
|
* problem and then retry the verify operation.
|
||||||
*/
|
*/
|
||||||
enum fp_verify_result {
|
enum fp_verify_result {
|
||||||
/** 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_NO_MATCH = 0,
|
FP_VERIFY_NO_MATCH = 0,
|
||||||
/** 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_MATCH = 1,
|
FP_VERIFY_MATCH = 1,
|
||||||
/** The scan did not succeed due to poor scan quality or other general
|
|
||||||
* user scanning problem. */
|
|
||||||
FP_VERIFY_RETRY = FP_ENROLL_RETRY,
|
FP_VERIFY_RETRY = FP_ENROLL_RETRY,
|
||||||
/** The scan did not succeed because the finger swipe was too short. */
|
|
||||||
FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
|
FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
|
||||||
/** The scan did not succeed because the finger was not centered on the
|
|
||||||
* scanner. */
|
|
||||||
FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
|
FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
|
||||||
/** The scan did not succeed due to quality or pressure problems; the user
|
|
||||||
* should remove their finger from the scanner before retrying. */
|
|
||||||
FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
|
FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
|
||||||
};
|
};
|
||||||
|
|
||||||
int fp_verify_finger_img(struct fp_dev *dev,
|
int fp_verify_finger_img(struct fp_dev *dev,
|
||||||
struct fp_print_data *enrolled_print, struct fp_img **img);
|
struct fp_print_data *enrolled_print, struct fp_img **img);
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_verify_finger:
|
||||||
|
* @dev: the device to perform the scan.
|
||||||
|
* @enrolled_print: the print to verify against. Must have been previously
|
||||||
|
* enrolled with a device compatible to the device selected to perform the scan.
|
||||||
|
*
|
||||||
* Performs a new scan and verify it against a previously enrolled print. This
|
* Performs a new scan and verify it against a previously enrolled print. This
|
||||||
* function is just a shortcut to calling fp_verify_finger_img() with a NULL
|
* function is just a shortcut to calling fp_verify_finger_img() with a NULL
|
||||||
* image output parameter.
|
* image output parameter.
|
||||||
* \param dev the device to perform the scan.
|
*
|
||||||
* \param enrolled_print the print to verify against. Must have been previously
|
* Returns: negative code on error, otherwise a code from #fp_verify_result
|
||||||
* enrolled with a device compatible to the device selected to perform the scan.
|
|
||||||
* \return negative code on error, otherwise a code from #fp_verify_result
|
|
||||||
* \sa fp_verify_finger_img()
|
* \sa fp_verify_finger_img()
|
||||||
*/
|
*/
|
||||||
static inline int fp_verify_finger(struct fp_dev *dev,
|
static inline int fp_verify_finger(struct fp_dev *dev,
|
||||||
|
|
@ -230,19 +292,22 @@ int fp_identify_finger_img(struct fp_dev *dev,
|
||||||
struct fp_print_data **print_gallery, size_t *match_offset,
|
struct fp_print_data **print_gallery, size_t *match_offset,
|
||||||
struct fp_img **img);
|
struct fp_img **img);
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Performs a new scan and attempts to identify the scanned finger against a
|
* fp_identify_finger:
|
||||||
* collection of previously enrolled fingerprints. This function is just a
|
* @dev: the device to perform the scan.
|
||||||
* shortcut to calling fp_identify_finger_img() with a NULL image output
|
* @print_gallery: %NULL-terminated array of pointers to the prints to
|
||||||
* parameter.
|
|
||||||
* \param dev the device to perform the scan.
|
|
||||||
* \param print_gallery NULL-terminated array of pointers to the prints to
|
|
||||||
* identify against. Each one must have been previously enrolled with a device
|
* identify against. Each one must have been previously enrolled with a device
|
||||||
* compatible to the device selected to perform the scan.
|
* compatible to the device selected to perform the scan.
|
||||||
* \param match_offset output location to store the array index of the matched
|
* @match_offset: output location to store the array index of the matched
|
||||||
* gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
|
* gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
|
||||||
* returned.
|
* returned.
|
||||||
* \return negative code on error, otherwise a code from #fp_verify_result
|
|
||||||
|
* Performs a new scan and attempts to identify the scanned finger against a
|
||||||
|
* collection of previously enrolled fingerprints. This function is just a
|
||||||
|
* shortcut to calling fp_identify_finger_img() with a %NULL image output
|
||||||
|
* parameter.
|
||||||
|
*
|
||||||
|
* Returns: negative code on error, otherwise a code from #fp_verify_result
|
||||||
* \sa fp_identify_finger_img()
|
* \sa fp_identify_finger_img()
|
||||||
*/
|
*/
|
||||||
static inline int fp_identify_finger(struct fp_dev *dev,
|
static inline int fp_identify_finger(struct fp_dev *dev,
|
||||||
|
|
@ -267,7 +332,11 @@ uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
|
||||||
|
|
||||||
/* Image handling */
|
/* Image handling */
|
||||||
|
|
||||||
/** \ingroup img */
|
/**
|
||||||
|
* fp_minutia:
|
||||||
|
*
|
||||||
|
* FIXME
|
||||||
|
*/
|
||||||
struct fp_minutia {
|
struct fp_minutia {
|
||||||
int x;
|
int x;
|
||||||
int y;
|
int y;
|
||||||
|
|
@ -294,6 +363,10 @@ void fp_img_free(struct fp_img *img);
|
||||||
|
|
||||||
/* Polling and timing */
|
/* Polling and timing */
|
||||||
|
|
||||||
|
/**
|
||||||
|
* fp_pollfd:
|
||||||
|
*
|
||||||
|
*/
|
||||||
struct fp_pollfd {
|
struct fp_pollfd {
|
||||||
int fd;
|
int fd;
|
||||||
short events;
|
short events;
|
||||||
|
|
|
||||||
|
|
@ -28,19 +28,22 @@
|
||||||
#include "nbis/include/bozorth.h"
|
#include "nbis/include/bozorth.h"
|
||||||
#include "nbis/include/lfs.h"
|
#include "nbis/include/lfs.h"
|
||||||
|
|
||||||
/** @defgroup img Image operations
|
/**
|
||||||
|
* SECTION:img
|
||||||
|
* @title: Image operations
|
||||||
|
*
|
||||||
* libfprint offers several ways of retrieving images from imaging devices,
|
* libfprint offers several ways of retrieving images from imaging devices,
|
||||||
* one example being the fp_dev_img_capture() function. The functions
|
* one example being the fp_dev_img_capture() function. The functions
|
||||||
* documented below allow you to work with such images.
|
* documented below allow you to work with such images.
|
||||||
*
|
*
|
||||||
* \section img_fmt Image format
|
* # Image format # {#img_fmt}
|
||||||
* All images are represented as 8-bit greyscale data.
|
* All images are represented as 8-bit greyscale data.
|
||||||
*
|
*
|
||||||
* \section img_std Image standardization
|
* # Image standardization # {#img_std}
|
||||||
* In some contexts, images you are provided through libfprint are raw images
|
* In some contexts, images you are provided through libfprint are raw images
|
||||||
* from the hardware. The orientation of these varies from device-to-device,
|
* from the hardware. The orientation of these varies from device-to-device,
|
||||||
* as does the color scheme (black-on-white or white-on-black?). libfprint
|
* as does the color scheme (black-on-white or white-on-black?). libfprint
|
||||||
* provides the fp_img_standardize function to convert images into standard
|
* provides the fp_img_standardize() function to convert images into standard
|
||||||
* form, which is defined to be: finger flesh as black on white surroundings,
|
* form, which is defined to be: finger flesh as black on white surroundings,
|
||||||
* natural upright orientation.
|
* natural upright orientation.
|
||||||
*/
|
*/
|
||||||
|
|
@ -82,9 +85,11 @@ struct fp_img *fpi_img_resize(struct fp_img *img, size_t newsize)
|
||||||
return g_realloc(img, sizeof(*img) + newsize);
|
return g_realloc(img, sizeof(*img) + newsize);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
|
* fp_img_free:
|
||||||
|
* @img: the image to destroy. If NULL, function simply returns.
|
||||||
|
*
|
||||||
* Frees an image. Must be called when you are finished working with an image.
|
* Frees an image. Must be called when you are finished working with an image.
|
||||||
* \param img the image to destroy. If NULL, function simply returns.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED void fp_img_free(struct fp_img *img)
|
API_EXPORTED void fp_img_free(struct fp_img *img)
|
||||||
{
|
{
|
||||||
|
|
@ -98,43 +103,55 @@ API_EXPORTED void fp_img_free(struct fp_img *img)
|
||||||
g_free(img);
|
g_free(img);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
|
* fp_img_get_height:
|
||||||
|
* @img: an image
|
||||||
|
*
|
||||||
* Gets the pixel height of an image.
|
* Gets the pixel height of an image.
|
||||||
* \param img an image
|
*
|
||||||
* \returns the height of the image
|
* Returns: the height of the image
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_img_get_height(struct fp_img *img)
|
API_EXPORTED int fp_img_get_height(struct fp_img *img)
|
||||||
{
|
{
|
||||||
return img->height;
|
return img->height;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
|
* fp_img_get_width:
|
||||||
|
* @img: an image
|
||||||
|
*
|
||||||
* Gets the pixel width of an image.
|
* Gets the pixel width of an image.
|
||||||
* \param img an image
|
*
|
||||||
* \returns the width of the image
|
* Returns: the width of the image
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_img_get_width(struct fp_img *img)
|
API_EXPORTED int fp_img_get_width(struct fp_img *img)
|
||||||
{
|
{
|
||||||
return img->width;
|
return img->width;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
|
* fp_img_get_data:
|
||||||
|
* @img: an image
|
||||||
|
*
|
||||||
* Gets the greyscale data for an image. This data must not be modified or
|
* Gets the greyscale data for an image. This data must not be modified or
|
||||||
* freed, and must not be used after fp_img_free() has been called.
|
* freed, and must not be used after fp_img_free() has been called.
|
||||||
* \param img an image
|
*
|
||||||
* \returns a pointer to libfprint's internal data for the image
|
* Returns: a pointer to libfprint's internal data for the image
|
||||||
*/
|
*/
|
||||||
API_EXPORTED unsigned char *fp_img_get_data(struct fp_img *img)
|
API_EXPORTED unsigned char *fp_img_get_data(struct fp_img *img)
|
||||||
{
|
{
|
||||||
return img->data;
|
return img->data;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
|
* fp_img_save_to_file:
|
||||||
|
* @img: the image to save
|
||||||
|
* @path: the path to save the image. Existing files will be overwritten.
|
||||||
|
*
|
||||||
* A quick convenience function to save an image to a file in
|
* A quick convenience function to save an image to a file in
|
||||||
* <a href="http://netpbm.sourceforge.net/doc/pgm.html">PGM format</a>.
|
* [PGM format](http://netpbm.sourceforge.net/doc/pgm.html).
|
||||||
* \param img the image to save
|
*
|
||||||
* \param path the path to save the image. Existing files will be overwritten.
|
* Returns: 0 on success, non-zero on error.
|
||||||
* \returns 0 on success, non-zero on error.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_img_save_to_file(struct fp_img *img, char *path)
|
API_EXPORTED int fp_img_save_to_file(struct fp_img *img, char *path)
|
||||||
{
|
{
|
||||||
|
|
@ -209,12 +226,14 @@ static void invert_colors(struct fp_img *img)
|
||||||
img->data[i] = 0xff - img->data[i];
|
img->data[i] = 0xff - img->data[i];
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
* \ref img_std "Standardizes" an image by normalizing its orientation, colors,
|
* fp_img_standardize:
|
||||||
|
* @img: the image to standardize
|
||||||
|
*
|
||||||
|
* [Standardizes](libfprint-Image-operations.html#img_std) an image by normalizing its orientation, colors,
|
||||||
* etc. It is safe to call this multiple times on an image, libfprint keeps
|
* etc. It is safe to call this multiple times on an image, libfprint keeps
|
||||||
* track of the work it needs to do to make an image standard and will not
|
* track of the work it needs to do to make an image standard and will not
|
||||||
* perform these operations more than once for a given image.
|
* perform these operations more than once for a given image.
|
||||||
* \param img the image to standardize
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED void fp_img_standardize(struct fp_img *img)
|
API_EXPORTED void fp_img_standardize(struct fp_img *img)
|
||||||
{
|
{
|
||||||
|
|
@ -419,23 +438,25 @@ int fpi_img_compare_print_data_to_gallery(struct fp_print_data *print,
|
||||||
return FP_VERIFY_NO_MATCH;
|
return FP_VERIFY_NO_MATCH;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
|
* fp_img_binarize:
|
||||||
|
* @img: a standardized image
|
||||||
|
*
|
||||||
* Get a binarized form of a standardized scanned image. This is where the
|
* Get a binarized form of a standardized scanned image. This is where the
|
||||||
* fingerprint image has been "enhanced" and is a set of pure black ridges
|
* fingerprint image has been "enhanced" and is a set of pure black ridges
|
||||||
* on a pure white background. Internally, image processing happens on top
|
* on a pure white background. Internally, image processing happens on top
|
||||||
* of the binarized image.
|
* of the binarized image.
|
||||||
*
|
*
|
||||||
* The image must have been \ref img_std "standardized" otherwise this function
|
* The image must have been [standardized](libfprint-Image-operations.html#img_std)
|
||||||
* will fail.
|
* otherwise this function will fail.
|
||||||
*
|
*
|
||||||
* It is safe to binarize an image and free the original while continuing
|
* It is safe to binarize an image and free the original while continuing
|
||||||
* to use the binarized version.
|
* to use the binarized version.
|
||||||
*
|
*
|
||||||
* You cannot binarize an image twice.
|
* You cannot binarize an image twice.
|
||||||
*
|
*
|
||||||
* \param img a standardized image
|
* Returns: a new image representing the binarized form of the original, or
|
||||||
* \returns a new image representing the binarized form of the original, or
|
* %NULL on error. Must be freed with fp_img_free() after use.
|
||||||
* NULL on error. Must be freed with fp_img_free() after use.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_img *fp_img_binarize(struct fp_img *img)
|
API_EXPORTED struct fp_img *fp_img_binarize(struct fp_img *img)
|
||||||
{
|
{
|
||||||
|
|
@ -467,15 +488,19 @@ API_EXPORTED struct fp_img *fp_img_binarize(struct fp_img *img)
|
||||||
return ret;
|
return ret;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup img
|
/**
|
||||||
|
* fp_img_get_minutiae:
|
||||||
|
* @img: a standardized image
|
||||||
|
* @nr_minutiae: an output location to store minutiae list length
|
||||||
|
*
|
||||||
* Get a list of minutiae detected in an image. A minutia point is a feature
|
* Get a list of minutiae detected in an image. A minutia point is a feature
|
||||||
* detected on a fingerprint, typically where ridges end or split.
|
* detected on a fingerprint, typically where ridges end or split.
|
||||||
* libfprint's image processing code relies upon comparing sets of minutiae,
|
* libfprint's image processing code relies upon comparing sets of minutiae,
|
||||||
* so accurate placement of minutia points is critical for good imaging
|
* so accurate placement of minutia points is critical for good imaging
|
||||||
* performance.
|
* performance.
|
||||||
*
|
*
|
||||||
* The image must have been \ref img_std "standardized" otherwise this function
|
* The image must have been [standardized](libfprint-Image-operations.html#img_std)
|
||||||
* will fail.
|
* otherwise this function will fail.
|
||||||
*
|
*
|
||||||
* You cannot pass a binarized image to this function. Instead, pass the
|
* You cannot pass a binarized image to this function. Instead, pass the
|
||||||
* original image.
|
* original image.
|
||||||
|
|
@ -485,9 +510,7 @@ API_EXPORTED struct fp_img *fp_img_binarize(struct fp_img *img)
|
||||||
* valid while the parent image has not been freed, and the minutiae data
|
* valid while the parent image has not been freed, and the minutiae data
|
||||||
* must not be modified or freed.
|
* must not be modified or freed.
|
||||||
*
|
*
|
||||||
* \param img a standardized image
|
* Returns: a list of minutiae points. Must not be modified or freed.
|
||||||
* \param nr_minutiae an output location to store minutiae list length
|
|
||||||
* \returns a list of minutiae points. Must not be modified or freed.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_minutia **fp_img_get_minutiae(struct fp_img *img,
|
API_EXPORTED struct fp_minutia **fp_img_get_minutiae(struct fp_img *img,
|
||||||
int *nr_minutiae)
|
int *nr_minutiae)
|
||||||
|
|
|
||||||
|
|
@ -30,7 +30,9 @@
|
||||||
#include "fp_internal.h"
|
#include "fp_internal.h"
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @defgroup poll Polling and timing operations
|
* SECTION:events
|
||||||
|
* @title: Initialisation and events handling
|
||||||
|
*
|
||||||
* These functions are only applicable to users of libfprint's asynchronous
|
* These functions are only applicable to users of libfprint's asynchronous
|
||||||
* API.
|
* API.
|
||||||
*
|
*
|
||||||
|
|
@ -50,10 +52,10 @@
|
||||||
* If there are no events pending, fp_handle_events() will block for a few
|
* If there are no events pending, fp_handle_events() will block for a few
|
||||||
* seconds (and will handle any new events should anything occur in that time).
|
* seconds (and will handle any new events should anything occur in that time).
|
||||||
* If you wish to customise this timeout, you can use
|
* If you wish to customise this timeout, you can use
|
||||||
* fp_handle_events_timeout() instead. If you wish to do a nonblocking
|
* fp_handle_events_timeout() instead. If you wish to do a non-blocking
|
||||||
* iteration, call fp_handle_events_timeout() with a zero timeout.
|
* iteration, call fp_handle_events_timeout() with a zero timeout.
|
||||||
*
|
*
|
||||||
* TODO: document how application is supposed to know when to call these
|
* FIXME: document how application is supposed to know when to call these
|
||||||
* functions.
|
* functions.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
|
@ -192,14 +194,16 @@ static int handle_timeouts(void)
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup poll
|
/**
|
||||||
|
* fp_handle_events_timeout:
|
||||||
|
* @timeout: Maximum timeout for this blocking function
|
||||||
|
*
|
||||||
* Handle any pending events. If a non-zero timeout is specified, the function
|
* Handle any pending events. If a non-zero timeout is specified, the function
|
||||||
* will potentially block for the specified amount of time, although it may
|
* will potentially block for the specified amount of time, although it may
|
||||||
* return sooner if events have been handled. The function acts as non-blocking
|
* return sooner if events have been handled. The function acts as non-blocking
|
||||||
* for a zero timeout.
|
* for a zero timeout.
|
||||||
*
|
*
|
||||||
* \param timeout Maximum timeout for this blocking function
|
* Returns: 0 on success, non-zero on error.
|
||||||
* \returns 0 on success, non-zero on error.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_handle_events_timeout(struct timeval *timeout)
|
API_EXPORTED int fp_handle_events_timeout(struct timeval *timeout)
|
||||||
{
|
{
|
||||||
|
|
@ -236,12 +240,14 @@ API_EXPORTED int fp_handle_events_timeout(struct timeval *timeout)
|
||||||
return handle_timeouts();
|
return handle_timeouts();
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup poll
|
/**
|
||||||
|
* fp_handle_events:
|
||||||
|
*
|
||||||
* Convenience function for calling fp_handle_events_timeout() with a sensible
|
* Convenience function for calling fp_handle_events_timeout() with a sensible
|
||||||
* default timeout value of two seconds (subject to change if we decide another
|
* default timeout value of two seconds (subject to change if we decide another
|
||||||
* value is more sensible).
|
* value is more sensible).
|
||||||
*
|
*
|
||||||
* \returns 0 on success, non-zero on error.
|
* Returns: 0 on success, non-zero on error.
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_handle_events(void)
|
API_EXPORTED int fp_handle_events(void)
|
||||||
{
|
{
|
||||||
|
|
@ -251,10 +257,14 @@ API_EXPORTED int fp_handle_events(void)
|
||||||
return fp_handle_events_timeout(&tv);
|
return fp_handle_events_timeout(&tv);
|
||||||
}
|
}
|
||||||
|
|
||||||
/* FIXME: docs
|
/**
|
||||||
* returns 0 if no timeouts active
|
* fp_get_next_timeout:
|
||||||
* returns 1 if timeout returned
|
* @tv: a %timeval structure containing the duration to the next timeout.
|
||||||
* zero timeout means events are to be handled immediately */
|
*
|
||||||
|
* A zero filled @tv timeout means events are to be handled immediately
|
||||||
|
*
|
||||||
|
* Returns: returns 0 if no timeouts active, or 1 if timeout returned.
|
||||||
|
*/
|
||||||
API_EXPORTED int fp_get_next_timeout(struct timeval *tv)
|
API_EXPORTED int fp_get_next_timeout(struct timeval *tv)
|
||||||
{
|
{
|
||||||
struct timeval fprint_timeout;
|
struct timeval fprint_timeout;
|
||||||
|
|
@ -286,16 +296,18 @@ API_EXPORTED int fp_get_next_timeout(struct timeval *tv)
|
||||||
return 1;
|
return 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup poll
|
/**
|
||||||
|
* fp_get_pollfds:
|
||||||
|
* @pollfds: output location for a list of pollfds. If non-%NULL, must be
|
||||||
|
* released with free() when done.
|
||||||
|
*
|
||||||
* Retrieve a list of file descriptors that should be polled for events
|
* Retrieve a list of file descriptors that should be polled for events
|
||||||
* interesting to libfprint. This function is only for users who wish to
|
* interesting to libfprint. This function is only for users who wish to
|
||||||
* combine libfprint's file descriptor set with other event sources - more
|
* combine libfprint's file descriptor set with other event sources - more
|
||||||
* simplistic users will be able to call fp_handle_events() or a variant
|
* simplistic users will be able to call fp_handle_events() or a variant
|
||||||
* directly.
|
* directly.
|
||||||
*
|
*
|
||||||
* \param pollfds output location for a list of pollfds. If non-NULL, must be
|
* Returns: the number of pollfds in the resultant list, or negative on error.
|
||||||
* released with free() when done.
|
|
||||||
* \returns the number of pollfds in the resultant list, or negative on error.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED size_t fp_get_pollfds(struct fp_pollfd **pollfds)
|
API_EXPORTED size_t fp_get_pollfds(struct fp_pollfd **pollfds)
|
||||||
{
|
{
|
||||||
|
|
@ -326,7 +338,12 @@ API_EXPORTED size_t fp_get_pollfds(struct fp_pollfd **pollfds)
|
||||||
return cnt;
|
return cnt;
|
||||||
}
|
}
|
||||||
|
|
||||||
/* FIXME: docs */
|
/**
|
||||||
|
* fp_set_pollfd_notifiers:
|
||||||
|
* @added_cb:
|
||||||
|
* @removed_cb:
|
||||||
|
*
|
||||||
|
*/
|
||||||
API_EXPORTED void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
|
API_EXPORTED void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
|
||||||
fp_pollfd_removed_cb removed_cb)
|
fp_pollfd_removed_cb removed_cb)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
112
libfprint/sync.c
112
libfprint/sync.c
|
|
@ -37,12 +37,15 @@ static void sync_open_cb(struct fp_dev *dev, int status, void *user_data)
|
||||||
odata->status = status;
|
odata->status = status;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_dev_open:
|
||||||
|
* @ddev: the discovered device to open
|
||||||
|
*
|
||||||
* Opens and initialises a device. This is the function you call in order
|
* Opens and initialises a device. This is the function you call in order
|
||||||
* to convert a \ref dscv_dev "discovered device" into an actual device handle
|
* to convert a #fp_dscv_dev "discovered device" into an actual device handle
|
||||||
* that you can perform operations with.
|
* that you can perform operations with.
|
||||||
* \param ddev the discovered device to open
|
*
|
||||||
* \returns the opened device handle, or NULL on error
|
* Returns: (transfer none): the opened device handle, or %NULL on error
|
||||||
*/
|
*/
|
||||||
API_EXPORTED struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev)
|
API_EXPORTED struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev)
|
||||||
{
|
{
|
||||||
|
|
@ -76,10 +79,12 @@ static void sync_close_cb(struct fp_dev *dev, void *user_data)
|
||||||
*closed = TRUE;
|
*closed = TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_dev_close:
|
||||||
|
* @dev: the device to close. If %NULL, function simply returns.
|
||||||
|
*
|
||||||
* Close a device. You must call this function when you are finished using
|
* Close a device. You must call this function when you are finished using
|
||||||
* a fingerprint device.
|
* a fingerprint device.
|
||||||
* \param dev the device to close. If NULL, function simply returns.
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED void fp_dev_close(struct fp_dev *dev)
|
API_EXPORTED void fp_dev_close(struct fp_dev *dev)
|
||||||
{
|
{
|
||||||
|
|
@ -120,9 +125,17 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data)
|
||||||
*stopped = TRUE;
|
*stopped = TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Performs an enroll stage. See \ref enrolling for an explanation of enroll
|
* fp_enroll_finger_img:
|
||||||
* stages.
|
* @dev: the device
|
||||||
|
* @print_data a location to return the resultant enrollment data from
|
||||||
|
* the final stage. Must be freed with fp_print_data_free() after use.
|
||||||
|
* @img: location to store the scan image. accepts %NULL for no image
|
||||||
|
* storage. If an image is returned, it must be freed with fp_img_free() after
|
||||||
|
* use.
|
||||||
|
*
|
||||||
|
* Performs an enroll stage. See [Enrolling](libfprint-Devices-operations.html#enrolling)
|
||||||
|
* for an explanation of enroll stages.
|
||||||
*
|
*
|
||||||
* If no enrollment is in process, this kicks of the process and runs the
|
* If no enrollment is in process, this kicks of the process and runs the
|
||||||
* first stage. If an enrollment is already in progress, calling this
|
* first stage. If an enrollment is already in progress, calling this
|
||||||
|
|
@ -137,7 +150,7 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data)
|
||||||
* The RETRY codes from #fp_enroll_result may be returned from any enroll
|
* The RETRY codes from #fp_enroll_result may be returned from any enroll
|
||||||
* stage. These codes indicate that the scan was not succesful in that the
|
* stage. These codes indicate that the scan was not succesful in that the
|
||||||
* user did not position their finger correctly or similar. When a RETRY code
|
* user did not position their finger correctly or similar. When a RETRY code
|
||||||
* is returned, the enrollment stage is <b>not</b> advanced, so the next call
|
* is returned, the enrollment stage is <emphasis role="strong">not</emphasis> advanced, so the next call
|
||||||
* into this function will retry the current stage again. The current stage may
|
* into this function will retry the current stage again. The current stage may
|
||||||
* need to be retried several times.
|
* need to be retried several times.
|
||||||
*
|
*
|
||||||
|
|
@ -159,19 +172,13 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data)
|
||||||
* resultant enrollment data. The print_data parameter will not be modified
|
* resultant enrollment data. The print_data parameter will not be modified
|
||||||
* during any other enrollment stages, hence it is actually legal to pass NULL
|
* during any other enrollment stages, hence it is actually legal to pass NULL
|
||||||
* as this argument for all but the final stage.
|
* as this argument for all but the final stage.
|
||||||
*
|
*
|
||||||
* If the device is an imaging device, it can also return the image from
|
* If the device is an imaging device, it can also return the image from
|
||||||
* the scan, even when the enroll fails with a RETRY or FAIL code. It is legal
|
* the scan, even when the enroll fails with a RETRY or FAIL code. It is legal
|
||||||
* to call this function even on non-imaging devices, just don't expect them to
|
* to call this function even on non-imaging devices, just don't expect them to
|
||||||
* provide images.
|
* provide images.
|
||||||
*
|
*
|
||||||
* \param dev the device
|
* Returns: negative code on error, otherwise a code from #fp_enroll_result
|
||||||
* \param print_data a location to return the resultant enrollment data from
|
|
||||||
* the final stage. Must be freed with fp_print_data_free() after use.
|
|
||||||
* \param img location to store the scan image. accepts NULL for no image
|
|
||||||
* storage. If an image is returned, it must be freed with fp_img_free() after
|
|
||||||
* use.
|
|
||||||
* \return negative code on error, otherwise a code from #fp_enroll_result
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_enroll_finger_img(struct fp_dev *dev,
|
API_EXPORTED int fp_enroll_finger_img(struct fp_dev *dev,
|
||||||
struct fp_print_data **print_data, struct fp_img **img)
|
struct fp_print_data **print_data, struct fp_img **img)
|
||||||
|
|
@ -302,20 +309,22 @@ static void verify_stop_cb(struct fp_dev *dev, void *user_data)
|
||||||
*stopped = TRUE;
|
*stopped = TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_verify_finger_img:
|
||||||
|
* @dev: the device to perform the scan.
|
||||||
|
* @enrolled_print: the print to verify against. Must have been previously
|
||||||
|
* enrolled with a device compatible to the device selected to perform the scan.
|
||||||
|
* @img: location to store the scan image. accepts %NULL for no image
|
||||||
|
* storage. If an image is returned, it must be freed with fp_img_free() after
|
||||||
|
* use.
|
||||||
|
|
||||||
* Performs a new scan and verify it against a previously enrolled print.
|
* Performs a new scan and verify it against a previously enrolled print.
|
||||||
* If the device is an imaging device, it can also return the image from
|
* If the device is an imaging device, it can also return the image from
|
||||||
* the scan, even when the verify fails with a RETRY code. It is legal to
|
* the scan, even when the verify fails with a RETRY code. It is legal to
|
||||||
* call this function even on non-imaging devices, just don't expect them to
|
* call this function even on non-imaging devices, just don't expect them to
|
||||||
* provide images.
|
* provide images.
|
||||||
*
|
*
|
||||||
* \param dev the device to perform the scan.
|
* Returns: negative code on error, otherwise a code from #fp_verify_result
|
||||||
* \param enrolled_print the print to verify against. Must have been previously
|
|
||||||
* enrolled with a device compatible to the device selected to perform the scan.
|
|
||||||
* \param img location to store the scan image. accepts NULL for no image
|
|
||||||
* storage. If an image is returned, it must be freed with fp_img_free() after
|
|
||||||
* use.
|
|
||||||
* \return negative code on error, otherwise a code from #fp_verify_result
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_verify_finger_img(struct fp_dev *dev,
|
API_EXPORTED int fp_verify_finger_img(struct fp_dev *dev,
|
||||||
struct fp_print_data *enrolled_print, struct fp_img **img)
|
struct fp_print_data *enrolled_print, struct fp_img **img)
|
||||||
|
|
@ -416,7 +425,19 @@ static void identify_stop_cb(struct fp_dev *dev, void *user_data)
|
||||||
*stopped = TRUE;
|
*stopped = TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** \ingroup dev
|
/**
|
||||||
|
* fp_identify_finger_img:
|
||||||
|
* @dev: the device to perform the scan.
|
||||||
|
* @print_gallery: NULL-terminated array of pointers to the prints to
|
||||||
|
* identify against. Each one must have been previously enrolled with a device
|
||||||
|
* compatible to the device selected to perform the scan.
|
||||||
|
* @match_offset: output location to store the array index of the matched
|
||||||
|
* gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
|
||||||
|
* returned.
|
||||||
|
* @img: location to store the scan image. accepts %NULL for no image
|
||||||
|
* storage. If an image is returned, it must be freed with fp_img_free() after
|
||||||
|
* use.
|
||||||
|
|
||||||
* Performs a new scan and attempts to identify the scanned finger against
|
* Performs a new scan and attempts to identify the scanned finger against
|
||||||
* a collection of previously enrolled fingerprints.
|
* a collection of previously enrolled fingerprints.
|
||||||
* If the device is an imaging device, it can also return the image from
|
* If the device is an imaging device, it can also return the image from
|
||||||
|
|
@ -435,17 +456,7 @@ static void identify_stop_cb(struct fp_dev *dev, void *user_data)
|
||||||
* Not all devices support identification. -ENOTSUP will be returned when
|
* Not all devices support identification. -ENOTSUP will be returned when
|
||||||
* this is the case.
|
* this is the case.
|
||||||
*
|
*
|
||||||
* \param dev the device to perform the scan.
|
* Returns: negative code on error, otherwise a code from #fp_verify_result
|
||||||
* \param print_gallery NULL-terminated array of pointers to the prints to
|
|
||||||
* identify against. Each one must have been previously enrolled with a device
|
|
||||||
* compatible to the device selected to perform the scan.
|
|
||||||
* \param match_offset output location to store the array index of the matched
|
|
||||||
* gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
|
|
||||||
* returned.
|
|
||||||
* \param img location to store the scan image. accepts NULL for no image
|
|
||||||
* storage. If an image is returned, it must be freed with fp_img_free() after
|
|
||||||
* use.
|
|
||||||
* \return negative code on error, otherwise a code from #fp_verify_result
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_identify_finger_img(struct fp_dev *dev,
|
API_EXPORTED int fp_identify_finger_img(struct fp_dev *dev,
|
||||||
struct fp_print_data **print_gallery, size_t *match_offset,
|
struct fp_print_data **print_gallery, size_t *match_offset,
|
||||||
|
|
@ -533,23 +544,26 @@ static void capture_stop_cb(struct fp_dev *dev, void *user_data)
|
||||||
fp_dbg("");
|
fp_dbg("");
|
||||||
*stopped = TRUE;
|
*stopped = TRUE;
|
||||||
}
|
}
|
||||||
/** \ingroup dev
|
/**
|
||||||
* Captures an \ref img "image" from a device. The returned image is the raw
|
* fp_dev_img_capture:
|
||||||
* image provided by the device, you may wish to \ref img_std "standardize" it.
|
* @dev: the device
|
||||||
|
* @unconditional: whether to unconditionally capture an image, or to only capture when a finger is detected
|
||||||
|
* @img: a location to return the captured image. Must be freed with
|
||||||
|
* fp_img_free() after use.
|
||||||
*
|
*
|
||||||
* If set, the <tt>unconditional</tt> flag indicates that the device should
|
* Captures a #fp_img "image" from a device. The returned image is the raw
|
||||||
|
* image provided by the device, you may wish to [standardize](libfprint-Image-operations.html#img_std) it.
|
||||||
|
*
|
||||||
|
* If set, the @unconditional flag indicates that the device should
|
||||||
* capture an image unconditionally, regardless of whether a finger is there
|
* capture an image unconditionally, regardless of whether a finger is there
|
||||||
* or not. If unset, this function will block until a finger is detected on
|
* or not. If unset, this function will block until a finger is detected on
|
||||||
* the sensor.
|
* the sensor.
|
||||||
*
|
*
|
||||||
* \param dev the device
|
* See fp_dev_supports_imaging().
|
||||||
* \param unconditional whether to unconditionally capture an image, or to only capture when a finger is detected
|
*
|
||||||
* \param img a location to return the captured image. Must be freed with
|
* Returns: 0 on success, non-zero on error. -ENOTSUP indicates that either the
|
||||||
* fp_img_free() after use.
|
* @unconditional flag was set but the device does not support this, or that the
|
||||||
* \return 0 on success, non-zero on error. -ENOTSUP indicates that either the
|
|
||||||
* unconditional flag was set but the device does not support this, or that the
|
|
||||||
* device does not support imaging.
|
* device does not support imaging.
|
||||||
* \sa fp_dev_supports_imaging()
|
|
||||||
*/
|
*/
|
||||||
API_EXPORTED int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
|
API_EXPORTED int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
|
||||||
struct fp_img **img)
|
struct fp_img **img)
|
||||||
|
|
|
||||||
|
|
@ -101,9 +101,12 @@ endif
|
||||||
libfprint_conf.set('API_EXPORTED', '__attribute__((visibility("default")))')
|
libfprint_conf.set('API_EXPORTED', '__attribute__((visibility("default")))')
|
||||||
configure_file(output: 'config.h', configuration: libfprint_conf)
|
configure_file(output: 'config.h', configuration: libfprint_conf)
|
||||||
|
|
||||||
subdir('doc')
|
|
||||||
subdir('libfprint')
|
subdir('libfprint')
|
||||||
subdir('examples')
|
subdir('examples')
|
||||||
|
if get_option('doc')
|
||||||
|
gnome = import('gnome')
|
||||||
|
subdir('doc')
|
||||||
|
endif
|
||||||
|
|
||||||
pkgconfig = import('pkgconfig')
|
pkgconfig = import('pkgconfig')
|
||||||
pkgconfig.generate(
|
pkgconfig.generate(
|
||||||
|
|
|
||||||
|
|
@ -22,3 +22,7 @@ option('debug_log',
|
||||||
description: 'Debug message logging',
|
description: 'Debug message logging',
|
||||||
type: 'boolean',
|
type: 'boolean',
|
||||||
value: false)
|
value: false)
|
||||||
|
option('doc',
|
||||||
|
description: 'Whether to build the API documentation',
|
||||||
|
type: 'boolean',
|
||||||
|
value: true)
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue