Stored prints: libfprint Reference Manual

## Stored prints Stored prints — Stored prints functions |

## 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. Storage needs to be handled by the API user by using the `fp_print_data_get_data()` and `fp_print_data_from_data()`. This API allows to convert print data into byte strings, 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.

The provided API to store data on disk is deprecated and should not be used anymore. This API stored the prints in the current user's home directory.

## 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);

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

Data storage should be handled outside of libfprint. See stored prints description for more information.

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);

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

Data storage should be handled outside of libfprint. See stored prints description for more information.

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);

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

Data storage should be handled outside of libfprint. See stored prints description for more information.

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;

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