FpDevice: libfprint Reference Manual

## FpDevice FpDevice — Fingerpint device routines |

## Functions

GQuark | fp_device_retry_quark ()
GQuark | fp_device_error_quark ()
void | (*FpEnrollProgress) ()
void | (*FpMatchCb) ()
const gchar * | fp_device_get_driver ()
const gchar * | fp_device_get_device_id ()
const gchar * | fp_device_get_name ()
FpScanType | fp_device_get_scan_type ()
gint | fp_device_get_nr_enroll_stages ()
FpFingerStatusFlags | fp_device_get_finger_status ()
FpDeviceFeature | fp_device_get_features ()
gboolean | fp_device_has_feature ()
gboolean | fp_device_has_storage ()
gboolean | fp_device_supports_identify ()
gboolean | fp_device_supports_capture ()
gboolean | fp_device_is_open ()
void | fp_device_open ()
void | fp_device_close ()
void | fp_device_enroll ()
void | fp_device_verify ()
void | fp_device_identify ()
void | fp_device_capture ()
void | fp_device_delete_print ()
void | fp_device_list_prints ()
void | fp_device_clear_storage ()
void | fp_device_suspend ()
void | fp_device_resume ()
gboolean | fp_device_open_finish ()
gboolean | fp_device_close_finish ()
FpPrint * | fp_device_enroll_finish ()
gboolean | fp_device_verify_finish ()
gboolean | fp_device_identify_finish ()
FpImage * | fp_device_capture_finish ()
gboolean | fp_device_delete_print_finish ()
GPtrArray * | fp_device_list_prints_finish ()
gboolean | fp_device_clear_storage_finish ()
gboolean | fp_device_suspend_finish ()
gboolean | fp_device_resume_finish ()
gboolean | fp_device_open_sync ()
gboolean | fp_device_close_sync ()
FpPrint * | fp_device_enroll_sync ()
gboolean | fp_device_verify_sync ()
gboolean | fp_device_identify_sync ()
FpImage * | fp_device_capture_sync ()
gboolean | fp_device_delete_print_sync ()
GPtrArray * | fp_device_list_prints_sync ()
gboolean | fp_device_clear_storage_sync ()
gboolean | fp_device_suspend_sync ()
gboolean | fp_device_resume_sync ()

## Properties

char * | device-id | Read
char * | driver | Read
FpFingerStatusFlags | finger-status | Read
guint64 | fpi-driver-data | Write / Construct Only
char * | fpi-environ | Write / Construct Only
char * | fpi-udev-data-hidraw | Read / Write / Construct Only
char * | fpi-udev-data-spidev | Read / Write / Construct Only
GUsbDevice * | fpi-usb-device | Read / Write / Construct Only
char * | name | Read
guint | nr-enroll-stages | Read
gboolean | open | Read
gboolean | removed | Read
FpScanType | scan-type | Read
FpTemperature | temperature | Read

## Signals

void | removed | Run Last

## Types and Values

#define | FP_TYPE_DEVICE
#define | FP_DEVICE_RETRY
#define | FP_DEVICE_ERROR
enum | FpDeviceType
enum | FpDeviceFeature
enum | FpScanType
enum | FpDeviceRetry
enum | FpDeviceError
enum | FpFingerStatusFlags
| FpDevice
enum | FpTemperature

## Object Hierarchy

        GObject
        ╰── FpDevice
            ╰── FpImageDevice

## Implemented Interfaces

FpDevice implements GAsyncInitable.

## Description

These are the public FpDevice routines.

## Functions

### fp_device_retry_quark ()

    GQuark
    fp_device_retry_quark (void);

#### Returns

Quark representing a retryable error.

### fp_device_error_quark ()

    GQuark
    fp_device_error_quark (void);

#### Returns

Quark representing a device error.

### FpEnrollProgress ()

    void
    (*FpEnrollProgress) (FpDevice *device,
                         gint completed_stages,
                         FpPrint *print,
                         gpointer user_data,
                         GError *error);

The passed error is guaranteed to be of type `FP_DEVICE_RETRY` if set.

#### Parameters

device | a FpDevice |
completed_stages | Number of completed stages |
print | The last scanned print. | [nullable][transfer none]
user_data | User provided data. | [nullable][transfer none]
error | GError or `NULL`. | [nullable][transfer none]

### FpMatchCb ()

    void
    (*FpMatchCb) (FpDevice *device,
                  FpPrint *match,
                  FpPrint *print,
                  gpointer user_data,
                  GError *error);

Report the result of a match (identify or verify) operation.

If `match` is non-`NULL`, then it is set to the matching FpPrint as passed to the match operation. In this case `error` will always be `NULL`.

If `error` is not `NULL` then its domain is guaranteed to be `FP_DEVICE_RETRY`. All other error conditions will not be reported using this callback. If such an error occurs before a match/no-match decision can be made, then this callback will not be called. Should an error happen afterwards, then you will get a match report through this callback and an error when the operation finishes.

If `match` and `error` are `NULL`, then a finger was presented but it did not match any known print.

`print` represents the newly scanned print. The driver may or may not provide this information. Image based devices will provide it and it allows access to the raw data.

This callback exists because it makes sense for drivers to wait e.g. on finger removal before completing the match operation. However, the success/failure can often be reported at an earlier time, and there is no need to make the user wait.

#### Parameters

device | a FpDevice |
match | The matching print if any matched `print` . | [nullable][transfer none]
print | The newly scanned print. | [nullable][transfer none]
user_data | User provided data. | [nullable][transfer none]
error | GError or `NULL`. | [nullable][transfer none]

### fp_device_get_driver ()

    const gchar *
    fp_device_get_driver (FpDevice *device);

#### Parameters

device | A FpDevice |

#### Returns

The ID of the driver.

[transfer none]

### fp_device_get_device_id ()

    const gchar *
    fp_device_get_device_id (FpDevice *device);

#### Parameters

device | A FpDevice |

#### Returns

The ID of the device.

[transfer none]

### fp_device_get_name ()

    const gchar *
    fp_device_get_name (FpDevice *device);

#### Parameters

device | A FpDevice |

#### Returns

The human readable name of the device.

[transfer none]

### fp_device_get_scan_type ()

    FpScanType
    fp_device_get_scan_type (FpDevice *device);

Retrieves the scan type of the device.

#### Parameters

device | A FpDevice |

#### Returns

The FpScanType

### fp_device_get_nr_enroll_stages ()

    gint
    fp_device_get_nr_enroll_stages (FpDevice *device);

Retrieves the number of enroll stages for this device.

#### Parameters

device | A FpDevice |

#### Returns

The number of enroll stages

### fp_device_get_finger_status ()

    FpFingerStatusFlags
    fp_device_get_finger_status (FpDevice *device);

Retrieves the finger status flags for the device. This can be used by the UI to present the relevant feedback, although it is not guaranteed to be a relevant value when not performing any action.

#### Parameters

device | A FpDevice |

#### Returns

The current FpFingerStatusFlags

### fp_device_get_features ()

    FpDeviceFeature
    fp_device_get_features (FpDevice *device);

Gets the FpDeviceFeature's supported by the `device` .

#### Parameters

device | a FpDevice |

#### Returns

FpDeviceFeature flags of supported features

### fp_device_has_feature ()

    gboolean
    fp_device_has_feature (FpDevice *device,
                           FpDeviceFeature feature);

Checks if `device` supports the requested FpDeviceFeature's. See `fp_device_get_features()`

#### Parameters

device | a FpDevice |
feature | FpDeviceFeature flags to check against device supported features |

#### Returns

`TRUE` if supported, `FALSE` otherwise

### fp_device_has_storage ()

    gboolean
    fp_device_has_storage (FpDevice *device);

`fp_device_has_storage` has been deprecated since version 1.92.0 and should not be used in newly-written code.

Use `fp_device_has_feature()` instead.

Whether the device has on-chip storage. If it has, you can list the prints stored on the with `fp_device_list_prints()` and you should always delete prints from the device again using `fp_device_delete_print()`.

#### Parameters

device | A FpDevice |

### fp_device_supports_identify ()

    gboolean
    fp_device_supports_identify (FpDevice *device);

`fp_device_supports_identify` has been deprecated since version 1.92.0 and should not be used in newly-written code.

Use `fp_device_has_feature()` instead.

Check whether the device supports identification.

#### Parameters

device | A FpDevice |

#### Returns

Whether the device supports identification

### fp_device_supports_capture ()

    gboolean
    fp_device_supports_capture (FpDevice *device);

`fp_device_supports_capture` has been deprecated since version 1.92.0 and should not be used in newly-written code.

Use `fp_device_has_feature()` instead.

Check whether the device supports capturing images.

#### Parameters

device | A FpDevice |

#### Returns

Whether the device supports image capture

### fp_device_is_open ()

    gboolean
    fp_device_is_open (FpDevice *device);

#### Parameters

device | A FpDevice |

#### Returns

Whether the device is open or not

### fp_device_open ()

    void
    fp_device_open (FpDevice *device,
                    GCancellable *cancellable,
                    GAsyncReadyCallback callback,
                    gpointer user_data);

Start an asynchronous operation to open the device. The callback will be called once the operation has finished. Retrieve the result with `fp_device_open_finish()`.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_close ()

    void
    fp_device_close (FpDevice *device,
                     GCancellable *cancellable,
                     GAsyncReadyCallback callback,
                     gpointer user_data);

Start an asynchronous operation to close the device. The callback will be called once the operation has finished. Retrieve the result with `fp_device_close_finish()`.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_enroll ()

    void
    fp_device_enroll (FpDevice *device,
                      FpPrint *template_print,
                      GCancellable *cancellable,
                      FpEnrollProgress progress_cb,
                      gpointer progress_data,
                      GDestroyNotify progress_destroy,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Start an asynchronous operation to enroll a print. The callback will be called once the operation has finished. Retrieve the result with `fp_device_enroll_finish()`.

The `template_print` parameter is a FpPrint with available metadata filled in and, optionally, with existing fingerprint data to be updated with newly enrolled fingerprints if a device driver supports it. The driver may make use of the metadata, when e.g. storing the print on device memory. It is undefined whether this print is filled in by the driver and returned, or whether the driver will return a newly created print after enrollment succeeded.

#### Parameters

device | a FpDevice |
template_print | a FpPrint. | [transfer floating]
cancellable | a GCancellable, or `NULL`. | [nullable]
progress_cb | progress reporting callback. | [nullable][closure progress_data][scope notified]
progress_data | user data for `progress_cb` |
progress_destroy | Destroy notify for `progress_data` . | [destroy progress_data]
callback | the function to call on completion. | [scope async]
user_data | the data to pass to `callback` |

### fp_device_verify ()

    void
    fp_device_verify (FpDevice *device,
                      FpPrint *enrolled_print,
                      GCancellable *cancellable,
                      FpMatchCb match_cb,
                      gpointer match_data,
                      GDestroyNotify match_destroy,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Start an asynchronous operation to verify a print. The callback will be called once the operation has finished. Retrieve the result with `fp_device_verify_finish()`.

#### Parameters

device | a FpDevice |
enrolled_print | a FpPrint to verify |
cancellable | a GCancellable, or `NULL`. | [nullable]
match_cb | match reporting callback. | [nullable][scope notified][closure match_data]
match_data | user data for `match_cb` |
match_destroy | Destroy notify for `match_data` . | [destroy match_data]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_identify ()

    void
    fp_device_identify (FpDevice *device,
                        GPtrArray *prints,
                        GCancellable *cancellable,
                        FpMatchCb match_cb,
                        gpointer match_data,
                        GDestroyNotify match_destroy,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Start an asynchronous operation to identify prints. The callback will be called once the operation has finished. Retrieve the result with `fp_device_identify_finish()`.

#### Parameters

device | a FpDevice |
prints | GPtrArray of FpPrint. | [element-type FpPrint][transfer none]
cancellable | a GCancellable, or `NULL`. | [nullable]
match_cb | match reporting callback. | [nullable][scope notified][closure match_data]
match_data | user data for `match_cb` |
match_destroy | Destroy notify for `match_data` . | [destroy match_data]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_capture ()

    void
    fp_device_capture (FpDevice *device,
                       gboolean wait_for_finger,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data);

Start an asynchronous operation to capture an image. The callback will be called once the operation has finished. Retrieve the result with `fp_device_capture_finish()`.

#### Parameters

device | a FpDevice |
wait_for_finger | Whether to wait for a finger or not |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_delete_print ()

    void
    fp_device_delete_print (FpDevice *device,
                            FpPrint *enrolled_print,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Start an asynchronous operation to delete a print from the device. The callback will be called once the operation has finished. Retrieve the result with `fp_device_delete_print_finish()`.

This only makes sense on devices that store prints on-chip, but is safe to always call.

#### Parameters

device | a FpDevice |
enrolled_print | a FpPrint to delete |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_list_prints ()

    void
    fp_device_list_prints (FpDevice *device,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Start an asynchronous operation to list all prints stored on the device. This only makes sense on devices that store prints on-chip.

Retrieve the result with `fp_device_list_prints_finish()`.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_clear_storage ()

    void
    fp_device_clear_storage (FpDevice *device,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Start an asynchronous operation to delete all prints from the device. The callback will be called once the operation has finished. Retrieve the result with `fp_device_clear_storage_finish()`.

This only makes sense on devices that store prints on-chip, but is safe to always call.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_suspend ()

    void
    fp_device_suspend (FpDevice *device,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data);

Prepare the device for system suspend. Retrieve the result with `fp_device_suspend_finish()`.

The suspend method can be called at any time (even if the device is not opened) and must be paired with a corresponding resume call. It is undefined when or how any ongoing operation is finished. This call might wait for an ongoing operation to finish, might cancel the ongoing operation or may prepare the device so that the host is resumed when the operation can be finished.

If an ongoing operation must be cancelled then it will complete with an error code of FP_DEVICE_ERROR_BUSY before the suspend async routine finishes.

Any operation started while the device is suspended will fail with FP_DEVICE_ERROR_BUSY, this includes calls to open or close the device.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`, currently not used. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_resume ()

    void
    fp_device_resume (FpDevice *device,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Resume device after system suspend. Retrieve the result with `fp_device_suspend_finish()`.

Note that it is not defined when any ongoing operation may return (success or error). You must be ready to handle this before, during or after the resume operation.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`, currently not used. | [nullable]
callback | the function to call on completion |
user_data | the data to pass to `callback` |

### fp_device_open_finish ()

    gboolean
    fp_device_open_finish (FpDevice *device,
                           GAsyncResult *result,
                           GError **error);

Finish an asynchronous operation to open the device. See `fp_device_open()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_close_finish ()

    gboolean
    fp_device_close_finish (FpDevice *device,
                            GAsyncResult *result,
                            GError **error);

Finish an asynchronous operation to close the device. See `fp_device_close()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_enroll_finish ()

    FpPrint *
    fp_device_enroll_finish (FpDevice *device,
                             GAsyncResult *result,
                             GError **error);

Finish an asynchronous operation to enroll a print. You should check for an error of type `FP_DEVICE_RETRY` to prompt the user again if there was an interaction issue. See `fp_device_enroll()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

The enrolled FpPrint, or `NULL` on error.

[transfer full]

### fp_device_verify_finish ()

    gboolean
    fp_device_verify_finish (FpDevice *device,
                             GAsyncResult *result,
                             gboolean *match,
                             FpPrint **print,
                             GError **error);

Finish an asynchronous operation to verify an enrolled print. You should check for an error of type `FP_DEVICE_RETRY` to prompt the user again if there was an interaction issue.

With `print` you can fetch the newly created print and retrieve the image data if available.

See `fp_device_verify()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
match | Whether the user presented the correct finger. | [out]
print | Location to store the scanned print, or `NULL` to ignore. | [out][transfer full][nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_identify_finish ()

    gboolean
    fp_device_identify_finish (FpDevice *device,
                               GAsyncResult *result,
                               FpPrint **match,
                               FpPrint **print,
                               GError **error);

Finish an asynchronous operation to identify a print. You should check for an error of type `FP_DEVICE_RETRY` to prompt the user again if there was an interaction issue.

Use `match` to find the print that matched. With `print` you can fetch the newly created print and retrieve the image data if available.

See `fp_device_identify()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
match | Location for the matched FpPrint, or `NULL`. | [out][transfer full][nullable]
print | Location for the new FpPrint, or `NULL`. | [out][transfer full][nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_capture_finish ()

    FpImage *
    fp_device_capture_finish (FpDevice *device,
                              GAsyncResult *result,
                              GError **error);

Finish an asynchronous operation to capture an image. You should check for an error of type `FP_DEVICE_RETRY` to prompt the user again if there was an interaction issue.

See `fp_device_capture()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

FpImage or `NULL` on error.

[transfer full]

### fp_device_delete_print_finish ()

    gboolean
    fp_device_delete_print_finish (FpDevice *device,
                                   GAsyncResult *result,
                                   GError **error);

Finish an asynchronous operation to delete an enrolled print.

See `fp_device_delete_print()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_list_prints_finish ()

    GPtrArray *
    fp_device_list_prints_finish (FpDevice *device,
                                  GAsyncResult *result,
                                  GError **error);

Finish an asynchronous operation to list all device stored prints.

See `fp_device_list_prints()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

Array of prints or `NULL` on error.

[element-type FpPrint][transfer container]

### fp_device_clear_storage_finish ()

    gboolean
    fp_device_clear_storage_finish (FpDevice *device,
                                    GAsyncResult *result,
                                    GError **error);

Finish an asynchronous operation to delete all enrolled prints.

See `fp_device_clear_storage()`.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_suspend_finish ()

    gboolean
    fp_device_suspend_finish (FpDevice *device,
                              GAsyncResult *result,
                              GError **error);

Finish an asynchronous operation to prepare the device for suspend. See `fp_device_suspend()`.

The API user should accept an error of FP_DEVICE_ERROR_NOT_SUPPORTED.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_resume_finish ()

    gboolean
    fp_device_resume_finish (FpDevice *device,
                             GAsyncResult *result,
                             GError **error);

Finish an asynchronous operation to resume the device after suspend. See `fp_device_resume()`.

The API user should accept an error of FP_DEVICE_ERROR_NOT_SUPPORTED.

#### Parameters

device | A FpDevice |
result | A GAsyncResult |
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_open_sync ()

    gboolean
    fp_device_open_sync (FpDevice *device,
                         GCancellable *cancellable,
                         GError **error);

Open the device synchronously.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_close_sync ()

    gboolean
    fp_device_close_sync (FpDevice *device,
                          GCancellable *cancellable,
                          GError **error);

Close the device synchronously.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_enroll_sync ()

    FpPrint *
    fp_device_enroll_sync (FpDevice *device,
                           FpPrint *template_print,
                           GCancellable *cancellable,
                           FpEnrollProgress progress_cb,
                           gpointer progress_data,
                           GError **error);

Enroll a new print. See `fp_device_enroll()`. It is undefined whether `template_print` is updated or a newly created FpPrint is returned.

#### Parameters

device | a FpDevice |
template_print | A FpPrint to fill in or use as a template. | [transfer floating]
cancellable | a GCancellable, or `NULL`. | [nullable]
progress_cb | progress reporting callback. | [nullable][scope call]
progress_data | user data for `progress_cb` |
error | Return location for errors, or `NULL` to ignore |

#### Returns

A FpPrint on success, `NULL` otherwise.

[transfer full]

### fp_device_verify_sync ()

    gboolean
    fp_device_verify_sync (FpDevice *device,
                           FpPrint *enrolled_print,
                           GCancellable *cancellable,
                           FpMatchCb match_cb,
                           gpointer match_data,
                           gboolean *match,
                           FpPrint **print,
                           GError **error);

Verify a given print synchronously.

#### Parameters

device | a FpDevice |
enrolled_print | a FpPrint to verify |
cancellable | a GCancellable, or `NULL`. | [nullable]
match_cb | match reporting callback. | [nullable][scope call][closure match_data]
match_data | user data for `match_cb` |
match | Whether the user presented the correct finger. | [out]
print | Location to store the scanned print, or `NULL` to ignore. | [out][transfer full][nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_identify_sync ()

    gboolean
    fp_device_identify_sync (FpDevice *device,
                             GPtrArray *prints,
                             GCancellable *cancellable,
                             FpMatchCb match_cb,
                             gpointer match_data,
                             FpPrint **match,
                             FpPrint **print,
                             GError **error);

Identify a print synchronously.

#### Parameters

device | a FpDevice |
prints | GPtrArray of FpPrint. | [element-type FpPrint][transfer none]
cancellable | a GCancellable, or `NULL`. | [nullable]
match_cb | match reporting callback. | [nullable][scope call][closure match_data]
match_data | user data for `match_cb` |
match | Location for the matched FpPrint, or `NULL`. | [out][transfer full][nullable]
print | Location for the new FpPrint, or `NULL`. | [out][transfer full][nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_capture_sync ()

    FpImage *
    fp_device_capture_sync (FpDevice *device,
                            gboolean wait_for_finger,
                            GCancellable *cancellable,
                            GError **error);

Start an synchronous operation to capture an image.

#### Parameters

device | a FpDevice |
wait_for_finger | Whether to wait for a finger or not |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

A new FpImage or `NULL` on error.

[transfer full]

### fp_device_delete_print_sync ()

    gboolean
    fp_device_delete_print_sync (FpDevice *device,
                                 FpPrint *enrolled_print,
                                 GCancellable *cancellable,
                                 GError **error);

Delete a given print from the device.

#### Parameters

device | a FpDevice |
enrolled_print | a FpPrint to verify |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_list_prints_sync ()

    GPtrArray *
    fp_device_list_prints_sync (FpDevice *device,
                                GCancellable *cancellable,
                                GError **error);

List device stored prints synchronously.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

Array of prints, or `NULL` on error.

[element-type FpPrint][transfer container]

### fp_device_clear_storage_sync ()

    gboolean
    fp_device_clear_storage_sync (FpDevice *device,
                                  GCancellable *cancellable,
                                  GError **error);

Clear sensor storage.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_suspend_sync ()

    gboolean
    fp_device_suspend_sync (FpDevice *device,
                            GCancellable *cancellable,
                            GError **error);

Prepare device for suspend.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`, currently not used. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

### fp_device_resume_sync ()

    gboolean
    fp_device_resume_sync (FpDevice *device,
                           GCancellable *cancellable,
                           GError **error);

Resume device after suspend.

#### Parameters

device | a FpDevice |
cancellable | a GCancellable, or `NULL`, currently not used. | [nullable]
error | Return location for errors, or `NULL` to ignore |

#### Returns

`FALSE` on error, `TRUE` otherwise.

[type void]

## Types and Values

### FP_TYPE_DEVICE

    #define FP_TYPE_DEVICE (fp_device_get_type ())

### FP_DEVICE_RETRY

    #define FP_DEVICE_RETRY (fp_device_retry_quark ())

### FP_DEVICE_ERROR

    #define FP_DEVICE_ERROR (fp_device_error_quark ())

### enum FpDeviceType

#### Members

FP_DEVICE_TYPE_VIRTUAL | The device is a virtual device |
FP_DEVICE_TYPE_UDEV | The device is a udev device |
FP_DEVICE_TYPE_USB | The device is a USB device |

### enum FpDeviceFeature

#### Members

FP_DEVICE_FEATURE_NONE | Device does not support any feature |
FP_DEVICE_FEATURE_CAPTURE | Supports image capture |
FP_DEVICE_FEATURE_IDENTIFY | Supports finger identification |
FP_DEVICE_FEATURE_VERIFY | Supports finger verification |
FP_DEVICE_FEATURE_STORAGE | Device has a persistent storage |
FP_DEVICE_FEATURE_STORAGE_LIST | Supports listing the storage templates |
FP_DEVICE_FEATURE_STORAGE_DELETE | Supports deleting stored templates |
FP_DEVICE_FEATURE_STORAGE_CLEAR | Supports clearing the whole storage |
FP_DEVICE_FEATURE_DUPLICATES_CHECK | Natively supports duplicates detection |
FP_DEVICE_FEATURE_ALWAYS_ON | Whether the device can run continuously |
FP_DEVICE_FEATURE_UPDATE_PRINT | Supports updating an existing print record using new scans |

### enum FpScanType

#### Members

FP_SCAN_TYPE_SWIPE | Sensor requires swiping the finger. |
FP_SCAN_TYPE_PRESS | Sensor requires placing/pressing down the finger. |

### enum FpDeviceRetry

Error codes representing scan failures resulting in the user needing to retry.

#### Members

FP_DEVICE_RETRY_GENERAL | The scan did not succeed due to poor scan quality or other general user scanning problem. |
FP_DEVICE_RETRY_TOO_SHORT | The scan did not succeed because the finger swipe was too short. |
FP_DEVICE_RETRY_CENTER_FINGER | The scan did not succeed because the finger was not centered on the scanner. |
FP_DEVICE_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. |
FP_DEVICE_RETRY_TOO_FAST | The scan did not succeed because the finger swipe or touch was too fast. |

### enum FpDeviceError

Error codes for device operations. More specific errors from other domains such as G_IO_ERROR or G_USB_DEVICE_ERROR may also be reported.

#### Members

FP_DEVICE_ERROR_GENERAL | A general error occurred. |
FP_DEVICE_ERROR_NOT_SUPPORTED | The device does not support the requested operation. |
FP_DEVICE_ERROR_NOT_OPEN | The device needs to be opened to start this operation. |
FP_DEVICE_ERROR_ALREADY_OPEN | The device has already been opened. |
FP_DEVICE_ERROR_BUSY | The device is busy with another request. |
FP_DEVICE_ERROR_PROTO | Protocol error |
FP_DEVICE_ERROR_DATA_INVALID | The passed data is invalid |
FP_DEVICE_ERROR_DATA_NOT_FOUND | Requested print was not found on device |
FP_DEVICE_ERROR_DATA_FULL | No space on device available for operation |
FP_DEVICE_ERROR_DATA_DUPLICATE | Enrolling template duplicates storaged templates |
FP_DEVICE_ERROR_REMOVED | The device has been removed. |
FP_DEVICE_ERROR_TOO_HOT | The device might be getting too hot |

### enum FpFingerStatusFlags

#### Members

FP_FINGER_STATUS_NONE | Sensor has not the finger on it, nor requires it |
FP_FINGER_STATUS_NEEDED | Sensor waits for the finger |
FP_FINGER_STATUS_PRESENT | Sensor has the finger on it |

### FpDevice

    typedef struct _FpDevice FpDevice;

### enum FpTemperature

When a device is created, it is assumed to be cold. Applications such as fprintd may want to ensure all devices on the system are cold before shutting down in order to ensure that the cool-off period is not violated because the internal libfprint state about the device is lost.

#### Members

FP_TEMPERATURE_COLD | Sensor is considered cold. |
FP_TEMPERATURE_WARM | Sensor is warm, usage time may be limited. |
FP_TEMPERATURE_HOT | Sensor is hot and cannot be used. |

## Property Details

### The `“device-id”` property

      “device-id”                char *

String describing the device, often generic but may be a serial number.

Owner: FpDevice

Flags: Read

Default value: ""

### The `“driver”` property

      “driver”                   char *

String describing the driver.

Owner: FpDevice

Flags: Read

Default value: NULL

### The `“finger-status”` property

      “finger-status”            FpFingerStatusFlags

The status of the finger.

Owner: FpDevice

Flags: Read

### The `“fpi-driver-data”` property

      “fpi-driver-data”          guint64

Private: The driver data from the ID table entry.

Owner: FpDevice

Flags: Write / Construct Only

Default value: 0

### The `“fpi-environ”` property

      “fpi-environ”              char *

Private: The environment variable for the virtual device.

Owner: FpDevice

Flags: Write / Construct Only

Default value: NULL

### The `“fpi-udev-data-hidraw”` property

      “fpi-udev-data-hidraw”     char *

Private: The path to /dev/hidrawN.

Owner: FpDevice

Flags: Read / Write / Construct Only

Default value: NULL

### The `“fpi-udev-data-spidev”` property

      “fpi-udev-data-spidev”     char *

Private: The path to /dev/spidevN.M.

Owner: FpDevice

Flags: Read / Write / Construct Only

Default value: NULL

### The `“fpi-usb-device”` property

      “fpi-usb-device”           GUsbDevice *

Private: The USB device for the device.

Owner: FpDevice

Flags: Read / Write / Construct Only

### The `“name”` property

      “name”                     char *

Human readable name for the device.

Owner: FpDevice

Flags: Read

Default value: NULL

### The `“nr-enroll-stages”` property

      “nr-enroll-stages”         guint

Number of enroll stages needed on the device.

Owner: FpDevice

Flags: Read

Default value: 0

### The `“open”` property

      “open”                     gboolean

Whether the device is open or not.

Owner: FpDevice

Flags: Read

Default value: FALSE

### The `“removed”` property

      “removed”                  gboolean

Whether the device has been removed from the system.

Owner: FpDevice

Flags: Read

Default value: FALSE

### The `“scan-type”` property

      “scan-type”                FpScanType

The scan type of the device.

Owner: FpDevice

Flags: Read

Default value: FP_SCAN_TYPE_SWIPE

### The `“temperature”` property

      “temperature”              FpTemperature

The temperature estimation for device to prevent overheating.

Owner: FpDevice

Flags: Read

Default value: FP_TEMPERATURE_COLD

## Signal Details

### The `“removed”` signal

    void
    user_function (FpDevice *device,
                   gpointer  user_data)

This signal is emitted after the device has been removed and no operation is pending anymore.

The API user is still required to close a removed device. The above guarantee means that the call to close the device can be made immediately from the signal handler.

The close operation will return FP_DEVICE_ERROR_REMOVED, but the device will still be considered closed afterwards.

The device will only be removed from the FpContext after it has been closed by the API user.

#### Parameters

device | the FpDevice instance that emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last