Stored prints

Stored prints

Functions

Types and Values

enum fp_finger
struct fp_print_data

Includes

#include <fprint.h>

Description

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

This page documents the various operations you can do with a stored print. Note that by default, "stored prints" are not actually stored anywhere except in RAM. For the simple scenarios, libfprint provides a simple API for you to save and load the stored prints referring to a single user in their home directory. For more advanced users, libfprint provides APIs for you to convert print data to a byte string, and to reconstruct stored prints from such data at a later point. You are welcome to store these byte strings in any fashion that suits you.

Functions

fp_print_data_get_data ()

size_t
fp_print_data_get_data (struct fp_print_data *data,
                        unsigned char **ret);

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

Parameters

data

the stored print

 

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.


fp_print_data_from_data ()

struct fp_print_data *
fp_print_data_from_data (unsigned char *buf,
                         size_t buflen);

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.

Parameters

buf

the data buffer

 

buflen

the length of the buffer

 

Returns

the stored print represented by the data, or NULL on error. Must be freed with fp_print_data_free() after use.


fp_print_data_save ()

int
fp_print_data_save (struct fp_print_data *data,
                    enum fp_finger finger);

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 finger from a DigitalPersona scanner, and you can also save the right index finger from a UPEK scanner. When you later come to load the print, the right one will be automatically selected.

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.

Parameters

data

the stored print to save to disk

 

finger

the finger that this print corresponds to

 

Returns

0 on success, non-zero on error.


fp_print_data_load ()

int
fp_print_data_load (struct fp_dev *dev,
                    enum fp_finger finger,
                    struct fp_print_data **data);

Loads a previously stored print from disk. The print must have been saved earlier using the fp_print_data_save() function.

A return code of -ENOENT indicates that the fingerprint requested could not be found. Other error codes (both positive and negative) are possible for obscure error conditions (e.g. corruption).

Parameters

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.

 

Returns

0 on success, non-zero on error


fp_print_data_delete ()

int
fp_print_data_delete (struct fp_dev *dev,
                      enum fp_finger finger);

Removes a stored print from disk previously saved with fp_print_data_save().

Parameters

dev

the device that the print belongs to

 

finger

the finger of the file you are deleting

 

Returns

0 on success, negative on error


fp_print_data_from_dscv_print ()

int
fp_print_data_from_dscv_print (struct fp_dscv_print *print,
                               struct fp_print_data **data);

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

Do not 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).

Parameters

print

the discovered print

 

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.


fp_print_data_free ()

void
fp_print_data_free (struct fp_print_data *data);

Frees a stored print. Must be called when you are finished using the print.

Parameters

data

the stored print to destroy. If NULL, function simply returns.

 

fp_print_data_get_driver_id ()

uint16_t
fp_print_data_get_driver_id (struct fp_print_data *data);

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

Parameters

data

the stored print

 

Returns

the driver ID of the driver compatible with the print


fp_print_data_get_devtype ()

uint32_t
fp_print_data_get_devtype (struct fp_print_data *data);

Gets the devtype for a stored print. The devtype represents which type of device under the parent driver is compatible with the print.

Parameters

data

the stored print

 

Returns

the devtype of the device range compatible with the print

Types and Values

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

Members

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

 

struct fp_print_data

struct fp_print_data {
	uint16_t driver_id;
	uint32_t devtype;
	enum fp_print_data_type type;
	GSList *prints;
};

fp_print_data is an opaque structure type. You must access it using the functions below.