Stored prints: libfprint Reference Manual

## Stored prints Stored prints |

## Functions

size_t | fp_print_data_get_data ()
struct fp_print_data * | fp_print_data_from_data ()
int | fp_print_data_save ()
int | fp_print_data_load ()
int | fp_print_data_delete ()
int | fp_print_data_from_dscv_print ()
void | fp_print_data_free ()
uint16_t | fp_print_data_get_driver_id ()
uint32_t | fp_print_data_get_devtype ()

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