Skip to content

GitLab

Commit 231b8f9f authored by Bastien Nocera's avatar Bastien Nocera
Browse files
Options

doc: Port from Doxygen to gtk-doc 

Split the introduction into separate chapters, add filler documentation
for async functions, fix mismatched function arguments.
parent dac153d2
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1220 additions and 1851 deletions
doc/advanced-topics.xml 0 → 100644
View file @ 231b8f9f
<?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>
doc/doxygen.cfg.in deleted 100644 → 0
View file @ dac153d2
This diff is collapsed.
doc/getting-started.xml 0 → 100644
View file @ 231b8f9f
<?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>
doc/intro.xml 0 → 100644
View file @ 231b8f9f
<?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>
doc/libfprint-docs.xml 0 → 100644
View file @ 231b8f9f
<?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>
doc/libfprint-sections.txt 0 → 100644
View file @ 231b8f9f
<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>
doc/meson.build
View file @ 231b8f9f
cdata = configuration_data()
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',
output: 'doxygen.cfg',
configuration: cdata,
install: false)
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)
subdir('xml')
private_headers = [
'config.h',
'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)
doc/xml/gtkdocentities.ent.in 0 → 100644
View file @ 231b8f9f
<!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@">
doc/xml/meson.build 0 → 100644
View file @ 231b8f9f
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)
libfprint/async.c
View file @ 231b8f9f
......@@ -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: