depau/libfprint
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

doc: Port from Doxygen to gtk-doc

Browse source 
Split the introduction into separate chapters, add filler documentation
for async functions, fix mismatched function arguments.
This commit is contained in:
Bastien Nocera 2018-05-17 02:58:59 +02:00
parent dac153d24a
commit 231b8f9f92
18 changed files with 1216 additions and 1847 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

115
doc/advanced-topics.xml Normal file
View 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
View file

File diff suppressed because it is too large Load diff

30
doc/getting-started.xml Normal file
View 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
View 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
View 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
View 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>

80
doc/meson.build
View file

@ -1,17 +1,67 @@
cdata = configuration_data()
cdata.set('SRCDIR', join_paths(meson.source_root(), 'libfprint'))
cdata.set('BUILDDIR', join_paths(meson.build_root(), 'doc'))
subdir('xml')
cfg = configure_file(input: 'doxygen.cfg.in',
output: 'doxygen.cfg',
configuration: cdata,
install: false)
private_headers = [
'config.h',
doxygen = find_program('doxygen')
datadir = join_paths(get_option('datadir'), 'doc', 'libfprint-devel')
custom_target('docs',
input: cfg,
output: 'html',
command: [ doxygen, '@INPUT@' ],
install: true,
install_dir: datadir)
'aeslib.h',
'assembling.h',
'fp_internal.h',
# Drivers
'aes1660.h',
'aes2501.h',
'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
View 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
View 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)

85
libfprint/async.c
View file

@ -36,7 +36,15 @@ void fpi_drvcb_open_complete(struct fp_dev *dev, int status)
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)
{
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->__enroll_stage = -1;
dev->state = DEV_STATE_INITIALIZING;
dev->open_cb = cb;
dev->open_cb = callback;
dev->open_cb_data = user_data;
if (!drv->open) {
@ -87,6 +95,12 @@ void fpi_drvcb_close_complete(struct fp_dev *dev)
g_free(dev);
}
/**
* fp_async_dev_close:
* @dev:
* @callback:
* @user_data
*/
API_EXPORTED void fp_async_dev_close(struct fp_dev *dev,
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,
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);
}
/**
* fp_async_enroll_stop:
* @dev:
* @callback:
* @user_data:
*
* Returns:
*/
API_EXPORTED int fp_async_enroll_stop(struct fp_dev *dev,
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;
}
/**
* fp_async_verify_start:
* @dev:
* @data:
* @callback:
* @user_data:
*
* Returns:
*/
API_EXPORTED int fp_async_verify_start(struct fp_dev *dev,
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);
}
/**
* fp_async_verify_stop:
* @dev:
* @callback:
* @user_data:
*
* Returns:
*/
API_EXPORTED int fp_async_verify_stop(struct fp_dev *dev,
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;
}
/**
* fp_async_identify_start:
* @dev:
* @gallery:
* @callback:
* @user_data:
*
* Returns:
*/
API_EXPORTED int fp_async_identify_start(struct fp_dev *dev,
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_async_identify_stop:
* @dev:
* @callback:
* @user_data:
*
* Returns:
*/
API_EXPORTED int fp_async_identify_stop(struct fp_dev *dev,
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);
}
/**
* fp_async_capture_start:
* @dev:
* @unconditional:
* @callback:
* @user_data:
*
* Returns:
*/
API_EXPORTED int fp_async_capture_start(struct fp_dev *dev, int unconditional,
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);
}
/**
* fp_async_capture_stop:
* @dev:
* @callback:
* @user_data:
*
* Returns:
*/
API_EXPORTED int fp_async_capture_stop(struct fp_dev *dev,
fp_capture_stop_cb callback, void *user_data)
{

492
libfprint/core.c
View file

@ -34,163 +34,50 @@ libusb_context *fpi_usb_ctx = NULL;
GSList *opened_devices = NULL;
/**
* \mainpage libfprint API Reference
* libfprint is an open source library to provide access to fingerprint
* scanning devices. For more info, see the
* <a href="http://www.reactivated.net/fprint/Libfprint">libfprint project
* homepage</a>.
* SECTION:discovery
* @title: Device discovery
*
* 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.
* These functions allow you to scan the system for supported fingerprint
* scanning hardware. This is your starting point when integrating libfprint
* into your software.
*
* This documentation is not aimed at developers wishing to develop and
* contribute fingerprint device drivers to libfprint.
*
* 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
* <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).
* 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 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
* interface primarily with libfprint's representation of devices, detailed
* on this page.
*
* \section enrolling Enrolling
* # Enrolling # {#enrolling}
*
* Enrolling is represented within libfprint as a multi-stage process. This
* slightly complicates things for application developers, but is required
* for a smooth process.
*
* Some devices require the user to scan their finger multiple times in
* 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
* as a stage, so a device that requires 3 scans for enrollment corresponds
* 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
* details.
*
* \section imaging Imaging
* # Imaging # {#imaging}
*
* libfprint provides you with some ways to retrieve images of scanned
* 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
@ -224,59 +112,6 @@ GSList *opened_devices = NULL;
* on a particular device. Your application must be able to cope with the
* fact that libfprint does support regular operations (e.g. enrolling and
* 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;
@ -524,10 +359,13 @@ static struct fp_dscv_dev *discover_dev(libusb_device *udev)
return ddev;
}
/** \ingroup dscv_dev
/**
* fp_discover_devs:
*
* Scans the system and returns a list of discovered devices. This is your
* 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.
*/
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;
}
/** \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
* discovered devices that it included, so make sure you have opened your
* discovered device <b>before</b> freeing the list.
* \param devs the list of discovered devices. If NULL, function simply
* returns.
* discovered device <emphasis role="strong">before</emphasis> freeing the list.
*/
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);
}
/** \ingroup dscv_dev
* Gets the \ref drv "driver" for a discovered device.
* \param dev the discovered device
* \returns the driver backing the device
/**
* fp_dscv_dev_get_driver:
* @dev: the discovered 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)
{
return dev->drv;
}
/** \ingroup dscv_dev
* Gets the \ref devtype "devtype" for a discovered device.
* \param dev the discovered device
* \returns the devtype of the device
/**
* fp_dscv_dev_get_devtype:
* @dev: the discovered 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)
{
@ -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.
* \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,
struct fp_print_data *data)
struct fp_print_data *print)
{
return fpi_print_data_compatible(dev->drv->id, dev->devtype,
fpi_driver_get_data_type(dev->drv), data->driver_id, data->devtype,
data->type);
fpi_driver_get_data_type(dev->drv), print->driver_id, print->devtype,
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.
* \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,
struct fp_dscv_print *data)
struct fp_dscv_print *print)
{
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
* compatible with a \ref 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
* NULL if no apparently compatible devices could be found
* compatible with a #fp_print_data "stored print".
*
* Returns: the first discovered device that appears to support the print, or
* %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,
struct fp_print_data *data)
struct fp_print_data *print)
{
struct fp_dscv_dev *ddev;
int 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 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
* compatible with a \ref 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
* NULL if no apparently compatible devices could be found
* compatible with a #fp_dscv_print "discovered print".
*
* Returns: the first discovered device that appears to support the print, or
* %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,
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;
}
/** \ingroup dev
* Get the \ref drv "driver" for a fingerprint device.
* \param dev the device
* \returns the driver controlling the device
/**
* fp_dev_get_driver:
* @dev: 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)
{
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.
* \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)
{
return dev->nr_enroll_stages;
}
/** \ingroup dev
* Gets the \ref devtype "devtype" for a device.
* \param dev the device
* \returns the devtype
/**
* fp_dev_get_devtype:
* @dev: the device
*
* 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)
{
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.
* \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,
struct fp_print_data *data)
@ -749,54 +619,69 @@ API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev,
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.
* \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,
struct fp_dscv_print *data)
struct fp_dscv_print *print)
{
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"
* \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)
{
return drv->name;
}
/** \ingroup drv
/**
* fp_driver_get_full_name:
* @drv: the driver
*
* 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)
{
return drv->full_name;
}
/** \ingroup drv
/**
* fp_driver_get_driver_id:
* @drv: the 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)
{
return drv->id;
}
/** \ingroup drv
/**
* fp_driver_get_scan_type:
* @drv: 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)
{
@ -810,14 +695,17 @@ static struct fp_img_dev *dev_to_img_dev(struct fp_dev *dev)
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
* capabilities you are able to perform imaging operations such as retrieving
* scan images using fp_dev_img_capture(). However, not all devices are
* imaging devices - some do all processing in hardware. This function will
* 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
*/
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;
}
/** \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
* 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)
{
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.
* 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.
* \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.
*/
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);
}
/** \ingroup dev
/**
* fp_dev_get_img_height:
* @dev: the fingerprint device
*
* Gets the expected height of images that will be captured from the device.
* 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.
* \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.
*/
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);
}
/** \ingroup core
/**
* fp_set_debug:
* @level: the verbosity level
*
* Set message verbosity.
* - Level 0: no messages ever printed by the library (default)
* - 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
* 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)
{
@ -915,10 +812,13 @@ API_EXPORTED void fp_set_debug(int level)
libusb_set_debug(fpi_usb_ctx, level);
}
/** \ingroup core
/**
* fp_init:
*
* Initialise libfprint. This function must be called before you attempt to
* 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)
{
@ -943,7 +843,9 @@ API_EXPORTED int fp_init(void)
return 0;
}
/** \ingroup core
/**
* fp_exit:
*
* Deinitialise libfprint. This function should be called during your program
* exit sequence. You must not use any libfprint functions after calling this
* function, unless you call fp_init() again.

173
libfprint/data.c
View file

@ -32,8 +32,11 @@
#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
* 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));
}
/** \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.
* 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().
* \param data the stored print
* \param ret output location for the data buffer. Must be freed with free()
* after use.
* \returns the size of the freshly allocated buffer, or 0 on error.
*
* 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,
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
* be the untouched contents of a buffer previously supplied to you by the
* 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.
*/
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);
}
/** \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
* 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
@ -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
* saved for the same finger and device type. The print is saved in a hidden
* 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,
enum fp_finger finger)
@ -415,7 +427,13 @@ static int load_from_file(char *path, struct fp_print_data **data)
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
* 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
* obscure error conditions (e.g. corruption).
*
* \param dev the device you are loading the print for
* \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
* Returns: 0 on success, non-zero on error
*/
API_EXPORTED int fp_print_data_load(struct fp_dev *dev,
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;
}
/** \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().
* \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,
enum fp_finger finger)
@ -477,18 +494,20 @@ API_EXPORTED int fp_print_data_delete(struct fp_dev *dev,
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.
*
* 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
* negative) are possible for obscure error conditions (e.g. corruption).
*
* \param print the discovered print
* \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.
* Returns: 0 on success, non-zero on error.
*/
API_EXPORTED int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
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);
}
/** \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.
* \param data the stored print to destroy. If NULL, function simply returns.
*/
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);
}
/** \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
* 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)
{
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.
* \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)
{
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
* fp_print_data_save(). It also detailed a load function,
* 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
* 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
* 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
@ -643,10 +673,13 @@ static GSList *scan_driver_store_dir(char *drvpath, uint16_t driver_id,
return list;
}
/** \ingroup dscv_print
/**
* fp_discover_prints:
*
* Scans the users home directory and returns a list of prints that were
* 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.
*/
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;
}
/** \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
* prints themselves, so make sure you do not use any discovered prints
* 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)
{
@ -727,47 +762,59 @@ API_EXPORTED void fp_dscv_prints_free(struct fp_dscv_print **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
* 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)
{
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
* 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)
{
return print->devtype;
}
/** \ingroup dscv_print
/**
* fp_dscv_print_get_finger:
* @print: 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)
{
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
* function, functions such as fp_dscv_print_get_finger() will continue to
* operate as before, however calling fp_print_data_from_dscv_print() will
* 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)
{

225
libfprint/fprint.h
View file

@ -27,42 +27,86 @@ extern "C" {
#include <stdint.h>
#include <sys/time.h>
/* structs that applications are not allowed to peek into */
/**
* fp_dscv_dev:
*
*/
struct fp_dscv_dev;
/**
* fp_dscv_print:
*
*/
struct fp_dscv_print;
/**
* fp_dev:
*
*/
struct fp_dev;
/**
* fp_driver:
*
*/
struct fp_driver;
/**
* fp_print_data:
*
*/
struct fp_print_data;
/**
* fp_img:
*
*/
struct fp_img;
/* 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
* purposely not available as strings, to avoid getting the library tangled up
* in localization efforts.
*/
enum fp_finger {
LEFT_THUMB = 1, /** thumb (left hand) */
LEFT_INDEX, /** index finger (left hand) */
LEFT_MIDDLE, /** middle finger (left hand) */
LEFT_RING, /** ring finger (left hand) */
LEFT_LITTLE, /** little finger (left hand) */
RIGHT_THUMB, /** thumb (right hand) */
RIGHT_INDEX, /** index finger (right hand) */
RIGHT_MIDDLE, /** middle finger (right hand) */
RIGHT_RING, /** ring finger (right hand) */
RIGHT_LITTLE, /** little finger (right hand) */
LEFT_THUMB = 1,
LEFT_INDEX,
LEFT_MIDDLE,
LEFT_RING,
LEFT_LITTLE,
RIGHT_THUMB,
RIGHT_INDEX,
RIGHT_MIDDLE,
RIGHT_RING,
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
* either swiping or pressing the finger on the device. This is useful for
* front-ends.
*/
enum fp_scan_type {
FP_SCAN_TYPE_PRESS = 0, /** press */
FP_SCAN_TYPE_SWIPE, /** swipe */
FP_SCAN_TYPE_PRESS = 0,
FP_SCAN_TYPE_SWIPE,
};
/* 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_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)
{
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_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 {
/** Capture completed successfully, the capture data has been
* returned to the caller. */
FP_CAPTURE_COMPLETE = 0,
/** Capture failed for some reason */
FP_CAPTURE_FAIL,
};
int fp_dev_supports_imaging(struct fp_dev *dev);
int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
struct fp_img **image);
struct fp_img **img);
int fp_dev_get_img_width(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().
* Result codes with RETRY in the name suggest that the scan failed due to
* user error. Applications will generally want to inform the user of the
* problem and then retry the enrollment stage. For more info on the semantics
* of interpreting these result codes and tracking enrollment process, see
* \ref enrolling.
* [Enrolling](libfprint-Devices-operations.html#enrolling)
*/
enum fp_enroll_result {
/** Enrollment completed successfully, the enrollment data has been
* returned to the caller. */
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,
/** Enroll stage passed; more stages are need to complete the process. */
FP_ENROLL_PASS,
/** The enrollment scan did not succeed due to poor scan quality or
* other general user scanning problem. */
FP_ENROLL_RETRY = 100,
/** The enrollment scan did not succeed because the finger swipe was
* 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,
/** 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,
};
int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
struct fp_img **img);
/** \ingroup dev
* Performs an enroll stage. See \ref 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.
*
* \param dev the device
* \param print_data a location to return the resultant enrollment data from
/**
* fp_enroll_finger:
* @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.
* \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,
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);
}
/** \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
* are also shared with fp_identify_finger().
* 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.
*/
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,
/** 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,
/** The scan did not succeed due to poor scan quality or other general
* user scanning problem. */
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,
/** The scan did not succeed because the finger was not centered on the
* scanner. */
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,
};
int fp_verify_finger_img(struct fp_dev *dev,
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
* function is just a shortcut to calling fp_verify_finger_img() with a NULL
* image output parameter.
* \param dev the device to perform the scan.
* \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.
* \return negative code on error, otherwise a code from #fp_verify_result
*
* Returns: negative code on error, otherwise a code from #fp_verify_result
* \sa fp_verify_finger_img()
*/
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_img **img);
/** \ingroup dev
* 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.
* \param dev the device to perform the scan.
* \param print_gallery NULL-terminated array of pointers to the prints to
/**
* fp_identify_finger:
* @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.
* \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
* 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()
*/
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 */
/** \ingroup img */
/**
* fp_minutia:
*
* FIXME
*/
struct fp_minutia {
int x;
int y;
@ -294,6 +363,10 @@ void fp_img_free(struct fp_img *img);
/* Polling and timing */
/**
* fp_pollfd:
*
*/
struct fp_pollfd {
int fd;
short events;

93
libfprint/img.c
View file

@ -28,19 +28,22 @@
#include "nbis/include/bozorth.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,
* one example being the fp_dev_img_capture() function. The functions
* 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.
*
* \section img_std Image standardization
* # Image standardization # {#img_std}
* In some contexts, images you are provided through libfprint are raw images
* 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
* 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,
* 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);
}
/** \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.
* \param img the image to destroy. If NULL, function simply returns.
*/
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);
}
/** \ingroup img
/**
* fp_img_get_height:
* @img: 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)
{
return img->height;
}
/** \ingroup img
/**
* fp_img_get_width:
* @img: 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)
{
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
* 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)
{
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 href="http://netpbm.sourceforge.net/doc/pgm.html">PGM format</a>.
* \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.
* [PGM format](http://netpbm.sourceforge.net/doc/pgm.html).
*
* Returns: 0 on success, non-zero on error.
*/
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];
}
/** \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
* 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.
* \param img the image to standardize
*/
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;
}
/** \ingroup img
/**
* fp_img_binarize:
* @img: a standardized image
*
* 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
* on a pure white background. Internally, image processing happens on top
* of the binarized image.
*
* The image must have been \ref img_std "standardized" otherwise this function
* will fail.
* The image must have been [standardized](libfprint-Image-operations.html#img_std)
* otherwise this function will fail.
*
* It is safe to binarize an image and free the original while continuing
* to use the binarized version.
*
* You cannot binarize an image twice.
*
* \param img a standardized image
* \returns a new image representing the binarized form of the original, or
* NULL on error. Must be freed with fp_img_free() after use.
* Returns: a new image representing the binarized form of the original, or
* %NULL on error. Must be freed with fp_img_free() after use.
*/
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;
}
/** \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
* detected on a fingerprint, typically where ridges end or split.
* libfprint's image processing code relies upon comparing sets of minutiae,
* so accurate placement of minutia points is critical for good imaging
* performance.
*
* The image must have been \ref img_std "standardized" otherwise this function
* will fail.
* The image must have been [standardized](libfprint-Image-operations.html#img_std)
* otherwise this function will fail.
*
* You cannot pass a binarized image to this function. Instead, pass the
* 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
* must not be modified or freed.
*
* \param img a standardized image
* \param nr_minutiae an output location to store minutiae list length
* \returns a list of minutiae points. Must not be modified or freed.
* 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,
int *nr_minutiae)

51
libfprint/poll.c
View file

@ -30,7 +30,9 @@
#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
* API.
*
@ -50,10 +52,10 @@
* 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).
* 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.
*
* 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.
*/
@ -192,14 +194,16 @@ static int handle_timeouts(void)
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
* 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
* 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)
{
@ -236,12 +240,14 @@ API_EXPORTED int fp_handle_events_timeout(struct timeval *timeout)
return handle_timeouts();
}
/** \ingroup poll
/**
* fp_handle_events:
*
* Convenience function for calling fp_handle_events_timeout() with a sensible
* default timeout value of two seconds (subject to change if we decide another
* 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)
{
@ -251,10 +257,14 @@ API_EXPORTED int fp_handle_events(void)
return fp_handle_events_timeout(&tv);
}
/* FIXME: docs
* returns 0 if no timeouts active
* returns 1 if timeout returned
* zero timeout means events are to be handled immediately */
/**
* fp_get_next_timeout:
* @tv: a %timeval structure containing the duration to the next timeout.
*
* 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)
{
struct timeval fprint_timeout;
@ -286,16 +296,18 @@ API_EXPORTED int fp_get_next_timeout(struct timeval *tv)
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
* interesting to libfprint. This function is only for users who wish to
* combine libfprint's file descriptor set with other event sources - more
* simplistic users will be able to call fp_handle_events() or a variant
* directly.
*
* \param pollfds output location for a list of pollfds. If non-NULL, must be
* released with free() when done.
* \returns the number of pollfds in the resultant list, or negative on error.
* Returns: the number of pollfds in the resultant list, or negative on error.
*/
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;
}
/* FIXME: docs */
/**
* fp_set_pollfd_notifiers:
* @added_cb:
* @removed_cb:
*
*/
API_EXPORTED void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
fp_pollfd_removed_cb removed_cb)
{

110
libfprint/sync.c
View file

@ -37,12 +37,15 @@ static void sync_open_cb(struct fp_dev *dev, int status, void *user_data)
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
* 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.
* \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)
{
@ -76,10 +79,12 @@ static void sync_close_cb(struct fp_dev *dev, void *user_data)
*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
* a fingerprint device.
* \param dev the device to close. If NULL, function simply returns.
*/
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;
}
/** \ingroup dev
* Performs an enroll stage. See \ref enrolling for an explanation of enroll
* stages.
/**
* fp_enroll_finger_img:
* @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
* 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
* 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
* 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
* need to be retried several times.
*
@ -165,13 +178,7 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data)
* to call this function even on non-imaging devices, just don't expect them to
* provide images.
*
* \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.
* \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
* Returns: negative code on error, otherwise a code from #fp_enroll_result
*/
API_EXPORTED int fp_enroll_finger_img(struct fp_dev *dev,
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;
}
/** \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.
* 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
* call this function even on non-imaging devices, just don't expect them to
* provide images.
*
* \param dev the device to perform the scan.
* \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
* Returns: negative code on error, otherwise a code from #fp_verify_result
*/
API_EXPORTED int fp_verify_finger_img(struct fp_dev *dev,
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;
}
/** \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
* a collection of previously enrolled fingerprints.
* 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
* this is the case.
*
* \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
* 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
* Returns: negative code on error, otherwise a code from #fp_verify_result
*/
API_EXPORTED int fp_identify_finger_img(struct fp_dev *dev,
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("");
*stopped = TRUE;
}
/** \ingroup dev
* Captures an \ref img "image" from a device. The returned image is the raw
* image provided by the device, you may wish to \ref img_std "standardize" it.
/**
* fp_dev_img_capture:
* @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
* or not. If unset, this function will block until a finger is detected on
* the sensor.
*
* \param dev the device
* \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
* fp_img_free() after use.
* \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
* See fp_dev_supports_imaging().
*
* Returns: 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.
* \sa fp_dev_supports_imaging()
*/
API_EXPORTED int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
struct fp_img **img)

5
meson.build
View file

@ -101,9 +101,12 @@ endif
libfprint_conf.set('API_EXPORTED', '__attribute__((visibility("default")))')
configure_file(output: 'config.h', configuration: libfprint_conf)
subdir('doc')
subdir('libfprint')
subdir('examples')
if get_option('doc')
gnome = import('gnome')
subdir('doc')
endif
pkgconfig = import('pkgconfig')
pkgconfig.generate(

4
meson_options.txt
View file

@ -22,3 +22,7 @@ option('debug_log',
description: 'Debug message logging',
type: 'boolean',
value: false)
option('doc',
description: 'Whether to build the API documentation',
type: 'boolean',
value: true)