<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libfprint: libfprint API Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.1 -->
<script type="text/javascript">
function hasClass(ele,cls) {
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
}
function addClass(ele,cls) {
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
}
function removeClass(ele,cls) {
if (hasClass(ele,cls)) {
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
ele.className=ele.className.replace(reg,' ');
}
}
function toggleVisibility(linkObj) {
var base = linkObj.getAttribute('id');
var summary = document.getElementById(base + '-summary');
var content = document.getElementById(base + '-content');
var trigger = document.getElementById(base + '-trigger');
if ( hasClass(linkObj,'closed') ) {
summary.style.display = 'none';
content.style.display = 'block';
trigger.src = 'open.png';
removeClass(linkObj,'closed');
addClass(linkObj,'opened');
} else if ( hasClass(linkObj,'opened') ) {
summary.style.display = 'block';
content.style.display = 'none';
trigger.src = 'closed.png';
removeClass(linkObj,'opened');
addClass(linkObj,'closed');
}
return false;
}
</script>
<div class="navigation" id="top">
<div class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<h1>libfprint API Reference </h1> </div>
</div>
<div class="contents">
<p>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>.</p>
<p>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.</p>
<p>This documentation is not aimed at developers wishing to develop and contribute fingerprint device drivers to libfprint.</p>
<p>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>.</p>
<h2><a class="anchor" id="enrollment"></a>
Enrollment</h2>
<p>Before you dive into the API, it's worth introducing a couple of concepts.</p>
<p>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.</p>
<h2><a class="anchor" id="verification"></a>
Verification</h2>
<p>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.</p>
<p>As an example scenario, verification can be used to implement what people would picture as fingerprint login (i.e. fingerprint replaces password). For example:</p>
<ul>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<h2><a class="anchor" id="identification"></a>
Identification</h2>
<p>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.</p>
<p>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.</p>
<h2><a class="anchor" id="compat_general"></a>
Device and print compatibility</h2>
<p>Moving off generic conceptual ideas and onto libfprint-specific implementation details, here are some introductory notes regarding how libfprint copes with compatibility of fingerprints.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>In summary, libfprint represents fingerprints in several internal structures and each representation will offer you a way of determining the <a class="el" href="group__drv.html#driver_id">driver ID</a> and <a class="el" href="group__dev.html#devtype">devtype</a> 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.</p>
<h2><a class="anchor" id="sync"></a>
Synchronity/asynchronity</h2>
<p>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.</p>
<p>Alternative asynchronous/non-blocking functionality will be offered in future but has not been implemented yet.</p>
<h2><a class="anchor" id="getting_started"></a>
Getting started</h2>
<p>libfprint includes several simple functional examples under the examples/ directory in the libfprint source distribution. Those are good starting points.</p>
<p>Usually the first thing you want to do is determine which fingerprint devices are present. This is done through <a class="el" href="group__dscv__dev.html">device discovery</a>.</p>
<p>Once you have found a device you would like to operate, you should open it. Refer to <a class="el" href="group__dev.html">device operations</a>. This section also details enrollment, image capture, and verification.</p>
<p>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). </p>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Wed Sep 8 2010 for libfprint by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
</body>
</html>
