Devices operations

Devices operations — Device operation functions

Functions

Types and Values

Includes

#include <fprint.h>

Description

In order to interact with fingerprint scanners, your software will interface primarily with libfprint's representation of devices, detailed on this page.

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 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.

The fp_dev_get_nr_enroll_stages() function can be used to find out how many enroll stages are needed.

In order to complete an enroll stage, you call an enroll function such as fp_enroll_finger(). The return of this function does not necessarily indicate that a stage has completed though, as the user may not have produced a good enough scan. Each stage may have to be retried several times.

The exact semantics of the enroll functions are described in the fp_enroll_finger() documentation. You should pay careful attention to the details.


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 such images in your application.

However, you must be aware that not all hardware supported by libfprint operates like this. Most hardware does operate simply by sending fingerprint images to the host computer for further processing, but some devices do all fingerprint processing in hardware and do not present images to the host computer.

You can use fp_dev_supports_imaging() to see if image capture is possible 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.

Functions

fp_dev_get_driver ()

struct fp_driver *
fp_dev_get_driver (struct fp_dev *dev);

Get the fp_driver for a fingerprint device.

Parameters

dev

the struct fp_dev device

 

Returns

the driver controlling the device


fp_dev_get_nr_enroll_stages ()

int
fp_dev_get_nr_enroll_stages (struct fp_dev *dev);

Gets the number of enroll stages required to enroll a fingerprint with the device.

Parameters

dev

the struct fp_dev device

 

Returns

the number of enroll stages


fp_dev_get_devtype ()

uint32_t
fp_dev_get_devtype (struct fp_dev *dev);

Gets the devtype for a device.

Parameters

dev

the struct fp_dev device

 

Returns

the devtype


fp_dev_supports_print_data ()

int
fp_dev_supports_print_data (struct fp_dev *dev,
                            struct fp_print_data *data);

Determines if a stored print is compatible with a certain device.

Parameters

dev

the struct fp_dev device

 

data

the stored print

 

Returns

1 if the print is compatible with the device, 0 if not


fp_dev_supports_imaging ()

int
fp_dev_supports_imaging (struct fp_dev *dev);

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.

Parameters

dev

the struct fp_dev device

 

Returns

1 if the device is an imaging device, 0 if the device does not provide images to the host computer


fp_dev_supports_identification ()

int
fp_dev_supports_identification (struct fp_dev *dev);

Determines if a device is capable of identification through fp_identify_finger() and similar. Not all devices support this functionality.

Parameters

dev

the struct fp_dev device

 

Returns

1 if the device is capable of identification, 0 otherwise.


fp_dev_supports_dscv_print ()

int
fp_dev_supports_dscv_print (struct fp_dev *dev,
                            struct fp_dscv_print *print);

fp_dev_supports_dscv_print is deprecated and should not be used in newly-written code.

Do not use.

Determines if a fp_dscv_print discovered print appears to be compatible with a certain device.

Parameters

dev

the struct fp_dev device

 

print

the discovered print

 

Returns

1 if the print is compatible with the device, 0 if not


fp_dev_get_img_width ()

int
fp_dev_get_img_width (struct fp_dev *dev);

Gets the expected width of images that will be captured from the device. This function will return -1 for devices that are not imaging devices. If the width of images from this device can vary, 0 will be returned.

Parameters

dev

the struct fp_dev device

 

Returns

the expected image width, or 0 for variable, or -1 for non-imaging devices.


fp_dev_get_img_height ()

int
fp_dev_get_img_height (struct fp_dev *dev);

Gets the expected height of images that will be captured from the device. This function will return -1 for devices that are not imaging devices. If the height of images from this device can vary, 0 will be returned.

Parameters

dev

the struct fp_dev device

 

Returns

the expected image height, or 0 for variable, or -1 for non-imaging devices.


fp_operation_stop_cb ()

void
(*fp_operation_stop_cb) (struct fp_dev *dev,
                         void *user_data);

Type definition for a function that will be called when fp_async_dev_close(), fp_async_verify_stop(), fp_async_identify_stop() or fp_async_capture_stop() finishes.

Parameters

dev

the struct fp_dev device

 

user_data

user data passed to the callback

 

fp_img_operation_cb ()

void
(*fp_img_operation_cb) (struct fp_dev *dev,
                        int result,
                        struct fp_img *img,
                        void *user_data);

Type definition for a function that will be called when fp_async_verify_start() or fp_async_capture_start() finished.

Parameters

dev

the struct fp_dev device

 

result

an fp_verify_result for fp_async_verify_start(), or an fp_capture_result for fp_async_capture_start(), or a negative value on error

 

img

the captured fp_img if capture or verification was successful

 

user_data

user data passed to the callback

 

fp_dev_open_cb ()

void
(*fp_dev_open_cb) (struct fp_dev *dev,
                   int status,
                   void *user_data);

Type definition for a function that will be called when fp_async_dev_open finishes.

Parameters

dev

the struct fp_dev device

 

status

0 on success, or a negative value on error

 

user_data

user data passed to the callback

 

fp_enroll_stage_cb ()

void
(*fp_enroll_stage_cb) (struct fp_dev *dev,
                       int result,
                       struct fp_print_data *print,
                       struct fp_img *img,
                       void *user_data);

Type definition for a function that will be called when fp_async_enroll_start() finishes. See fp_enroll_finger_img() for the expected behaviour of your program based on the result .

Parameters

dev

the struct fp_dev device

 

result

a fp_enroll_result on success, or a negative value on failure

 

print

the enrollment data from the final stage

 

img

an fp_img to free with fp_img_free()

 

user_data

user data passed to the callback

 

fp_identify_cb ()

void
(*fp_identify_cb) (struct fp_dev *dev,
                   int result,
                   size_t match_offset,
                   struct fp_img *img,
                   void *user_data);

Type definition for a function that will be called when fp_async_identify_start() finishes.

Parameters

dev

the struct fp_dev device

 

result

a fp_verify_result on success, or a negative value on error.

 

match_offset

the array index of the matched gallery print (if any was found). Only valid if FP_VERIFY_MATCH was returned.

 

img

the scan image, it must be freed with fp_img_free() after use.

 

user_data

user data passed to the callback

 

fp_dev_open ()

struct fp_dev *
fp_dev_open (struct fp_dscv_dev *ddev);

Opens and initialises a device. This is the function you call in order to convert a fp_dscv_dev discovered device into an actual device handle that you can perform operations with.

Parameters

ddev

the struct fp_dscv_dev discovered device to open

 

Returns

the opened device handle, or NULL on error


fp_async_dev_open ()

int
fp_async_dev_open (struct fp_dscv_dev *ddev,
                   fp_dev_open_cb callback,
                   void *user_data);

Opens and initialises a device. This is the function you call in order to convert a fp_dscv_dev discovered device into an actual device handle that you can perform operations with.

The error status of the opening will be provided as an argument to the fp_dev_open_cb callback.

Parameters

ddev

the struct fp_dscv_dev discovered device to open

 

callback

the callback to call when the device has been opened

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error


fp_dev_close ()

void
fp_dev_close (struct fp_dev *dev);

Closes a device. You must call this function when you have finished using a fingerprint device.

Parameters

dev

the struct fp_dev device to close. If NULL, function simply returns

 

fp_async_dev_close ()

void
fp_async_dev_close (struct fp_dev *dev,
                    fp_operation_stop_cb callback,
                    void *user_data);

Closes a device. You must call this function when you have finished using a fingerprint device.

Parameters

dev

the struct fp_dev device

 

callback

the callback to call when the device has been closed

 

user_data

user data to pass to the callback

 

fp_enroll_finger ()

int
fp_enroll_finger (struct fp_dev *dev,
                  struct fp_print_data **print_data);

Performs an enroll stage. See 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.

Parameters

dev

the struct fp_dev 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

 

Returns

negative code on error, otherwise a code from fp_enroll_result


fp_enroll_finger_img ()

int
fp_enroll_finger_img (struct fp_dev *dev,
                      struct fp_print_data **print_data,
                      struct fp_img **img);

Performs an enroll stage. See 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 function runs the next stage, which may well be the last.

A negative error code may be returned from any stage. When this occurs, further calls to the enroll function will start a new enrollment process, i.e. a negative error code indicates that the enrollment process has been aborted. These error codes only ever indicate unexpected internal errors or I/O problems.

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 not advanced, so the next call into this function will retry the current stage again. The current stage may need to be retried several times.

The FP_ENROLL_FAIL code may be returned from any enroll stage. This code indicates that even though the scans themselves have been acceptable, data processing applied to these scans produces incomprehensible results. In other words, the user may have been scanning a different finger for each stage or something like that. Like negative error codes, this return code indicates that the enrollment process has been aborted.

The FP_ENROLL_PASS code will only ever be returned for non-final stages. This return code indicates that the scan was acceptable and the next call into this function will advance onto the next enroll stage.

The FP_ENROLL_COMPLETE code will only ever be returned from the final enroll stage. It indicates that enrollment completed successfully, and that print_data has been assigned to point to the resultant enrollment data. The print_data parameter will not be modified during any other enrollment stages, hence it is actually legal to pass NULL as this argument for all but the final stage.

If the device is an imaging device, it can also return the image from the scan, even when the enroll fails with a RETRY or FAIL code. It is legal to call this function even on non-imaging devices, just don't expect them to provide images.

Parameters

dev

the struct fp_dev 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

 

Returns

negative code on error, otherwise a code from fp_enroll_result


fp_async_enroll_start ()

int
fp_async_enroll_start (struct fp_dev *dev,
                       fp_enroll_stage_cb callback,
                       void *user_data);

Starts an enrollment and calls callback for each enrollment stage. See Enrolling for an explanation of enroll stages.

Parameters

dev

the struct fp_dev device

 

callback

the callback to call for each stage of the enrollment

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error


fp_async_enroll_stop ()

int
fp_async_enroll_stop (struct fp_dev *dev,
                      fp_operation_stop_cb callback,
                      void *user_data);

Stops an ongoing enrollment started with fp_async_enroll_start().

Parameters

dev

the struct fp_dev device

 

callback

the callback to call when the enrollment has been cancelled

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error


fp_verify_finger ()

int
fp_verify_finger (struct fp_dev *dev,
                  struct fp_print_data *enrolled_print);

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.

See also fp_verify_finger_img().

Parameters

dev

the struct fp_dev device to perform the scan on

 

enrolled_print

the print to verify against. Must have been previously enrolled with a device compatible to the device selected to perform the scan

 

Returns

negative code on error, otherwise a code from fp_verify_result


fp_verify_finger_img ()

int
fp_verify_finger_img (struct fp_dev *dev,
                      struct fp_print_data *enrolled_print,
                      struct fp_img **img);

Performs a new scan and verifies 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.

Parameters

dev

the struct fp_dev device to perform the scan on

 

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

 

Returns

negative code on error, otherwise a code from fp_verify_result


fp_async_verify_start ()

int
fp_async_verify_start (struct fp_dev *dev,
                       struct fp_print_data *data,
                       fp_img_operation_cb callback,
                       void *user_data);

Starts a verification and calls callback when the verification has finished. See fp_verify_finger_img() for the synchronous API. When the callback has been called, you must call fp_async_verify_stop().

Parameters

dev

the struct fp_dev device

 

data

the print to verify against. Must have been previously enrolled with a device compatible to the device selected to perform the scan

 

callback

the callback to call when the verification has finished

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error


fp_async_verify_stop ()

int
fp_async_verify_stop (struct fp_dev *dev,
                      fp_operation_stop_cb callback,
                      void *user_data);

Finishes an ongoing verification started with fp_async_verify_start().

Parameters

dev

the struct fp_dev device

 

callback

the callback to call to finish a verification

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error


fp_identify_finger ()

int
fp_identify_finger (struct fp_dev *dev,
                    struct fp_print_data **print_gallery,
                    size_t *match_offset);

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.

See also fp_identify_finger_img().

Parameters

dev

the struct fp_dev device to perform the scan on

 

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

 

Returns

negative code on error, otherwise a code from fp_verify_result


fp_identify_finger_img ()

int
fp_identify_finger_img (struct fp_dev *dev,
                        struct fp_print_data **print_gallery,
                        size_t *match_offset,
                        struct fp_img **img);

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 the scan, even when identification 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.

This function returns codes from fp_verify_result. The return code FP_VERIFY_MATCH indicates that the scanned fingerprint does appear in the print gallery, and the match_offset output parameter will indicate the index into the print gallery array of the matched print.

This function will not necessarily examine the whole print gallery, it will return as soon as it finds a matching print.

Not all devices support identification. -ENOTSUP will be returned when this is the case.

Parameters

dev

the struct fp_dev device to perform the scan on

 

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

 

Returns

negative code on error, otherwise a code from fp_verify_result


fp_async_identify_start ()

int
fp_async_identify_start (struct fp_dev *dev,
                         struct fp_print_data **gallery,
                         fp_identify_cb callback,
                         void *user_data);

Performs a new scan and verifies it against a previously enrolled print. See also: fp_verify_finger_img()

Parameters

dev

the struct fp_dev device

 

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

 

callback

the callback to call when the identification has finished

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error


fp_async_identify_stop ()

int
fp_async_identify_stop (struct fp_dev *dev,
                        fp_operation_stop_cb callback,
                        void *user_data);

Stops an ongoing identification started with fp_async_identify_start().

Parameters

dev

the struct fp_dev device

 

callback

the callback to call when the identification has stopped

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error


fp_dev_img_capture ()

int
fp_dev_img_capture (struct fp_dev *dev,
                    int unconditional,
                    struct fp_img **img);

Captures a fp_img from a device. The returned image is the raw image provided by the device, you may wish to standardize 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.

See fp_dev_supports_imaging().

Parameters

dev

the struct fp_dev 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

 

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


fp_async_capture_start ()

int
fp_async_capture_start (struct fp_dev *dev,
                        int unconditional,
                        fp_img_operation_cb callback,
                        void *user_data);

Start the capture of an fp_img from a device. When the callback has been called, you must call fp_async_capture_stop().

Parameters

dev

the struct fp_dev device

 

unconditional

whether to unconditionally capture an image, or to only capture when a finger is detected

 

callback

the callback to call when the capture has finished

 

user_data

user data to pass to the callback

 

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


fp_async_capture_stop ()

int
fp_async_capture_stop (struct fp_dev *dev,
                       fp_operation_stop_cb callback,
                       void *user_data);

Stops an ongoing verification started with fp_async_capture_start().

Parameters

dev

the struct fp_dev device

 

callback

the callback to call when the capture has been stopped

 

user_data

user data to pass to the callback

 

Returns

0 on success, non-zero on error

Types and Values

struct fp_dev

struct fp_dev;

fp_dev is an opaque structure type. You must access it using the functions in this section.


enum fp_scan_type

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.

Members

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

 

enum fp_capture_result

Whether a capture failed or completed.

Members

FP_CAPTURE_COMPLETE

Capture completed successfully, the capture data has been returned to the caller.

 

FP_CAPTURE_FAIL

Capture failed

 

enum fp_enroll_result

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 Enrolling

Members

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.

 

enum fp_verify_result

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 user error. Applications will generally want to inform the user of the problem and then retry the verify operation.

Members

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.