fp-device

fp-device

Functions

Types and Values

Description

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 scaned 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_is_open ()

gboolean
fp_device_is_open (FpDevice *device);

Parameters

device

A FpDevice

 

Returns

Whether the device is open or not


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

gboolean
fp_device_supports_identify (FpDevice *device);

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

Check whether the device supports capturing images.

Parameters

device

A FpDevice

 

Returns

Whether the device supports image capture


fp_device_has_storage ()

gboolean
fp_device_has_storage (FpDevice *device);

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_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. The driver may make use of this 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 successed.

Parameters

device

a FpDevice

 

template_print

a FpPrint.

[transfer floating]

cancellable

a GCancellable, or NULL.

[nullable]

progress_cb

progress reporting callback.

[nullable][scope notified]

progress_data

user data for progress_cb .

[closure 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]

match_data

user data for match_cb .

[closure 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]

match_data

user data for match_cb .

[closure 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_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_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]

match_data

user data for match_cb .

[closure 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]

match_data

user data for match_cb .

[closure 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


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]

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_USB

The device is a USB device

 

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.

 

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

 

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

 

FpDevice

typedef struct _FpDevice FpDevice;

FpDeviceClass

typedef struct {
  /* Static information about the driver. */
  const gchar     *id;
  const gchar     *full_name;
  FpDeviceType     type;
  const FpIdEntry *id_table;

  /* Defaults for device properties */
  gint       nr_enroll_stages;
  FpScanType scan_type;

  /* Callbacks */
  gint (*usb_discover) (GUsbDevice *usb_device);
  void (*probe)    (FpDevice *device);
  void (*open)     (FpDevice *device);
  void (*close)    (FpDevice *device);
  void (*enroll)   (FpDevice *device);
  void (*verify)   (FpDevice *device);
  void (*identify) (FpDevice *device);
  void (*capture)  (FpDevice *device);
  void (*list)     (FpDevice *device);
  void (*delete)   (FpDevice * device);

  void (*cancel)   (FpDevice *device);
} FpDeviceClass;

NOTE: If your driver is image based, then you should subclass FpImageDevice instead. FpImageDevice based drivers use a different way of interacting with libfprint.

These are the main entry points for drivers to implement. Drivers may not implement all of these entry points if they do not support the operation (or a default implementation is sufficient).

Drivers must eventually call the corresponding function to finish the operation. It is also acceptable to call the generic fpi_device_action_error() function but doing so is not recommended in most usecases.

Drivers must also handle cancellation properly for any long running operation (i.e. any operation that requires capturing). It is entirely fine to ignore cancellation requests for short operations (e.g. open/close).

This API is solely intended for drivers. It is purely internal and neither API nor ABI stable.

Members

const gchar *id;

ID string for the driver. Should be a valid C identifier and should match the drivers file name.

 

const gchar *full_name;

Human readable description of the driver

 

FpDeviceType type;

The type of driver

 

const FpIdEntry *id_table;

The table of IDs to bind the driver to

 

gint nr_enroll_stages;

The number of enroll stages supported devices need; use fpi_device_set_nr_enroll_stages() from probe if this is dynamic.

 

FpScanType scan_type;

The scan type of supported devices; use fpi_device_set_scan_type() from probe if this is dynamic.

 

usb_discover ()

Class method to check whether a USB device is supported by the driver. Should return 0 if the device is unsupported and a positive score otherwise. The default score is 50 and the driver with the highest score will be loaded.

 

probe ()

Called immediately for all devices. Most drivers will not need to implement this. Drivers should setup the device identifier from the probe callback which will be used to verify the compatibility of stored FpPrint's. It is permissable to temporarily open the USB device if this is required for the operation. If an error is returned, then the device will be destroyed again immediately and never reported to the API user.

 

open ()

Open the device for futher operations. Any of the normal actions are guaranteed to only happen when the device is open (this includes delete).

 

close ()

Close the device again

 

enroll ()

Start an enroll operation

 

verify ()

Start a verify operation

 

identify ()

Start an identify operation

 

capture ()

Start a capture operation

 

list ()

List prints stored on the device

 

delete ()

Delete a print from the device

 

cancel ()

Called on cancellation, this is a convenience to not need to handle the GCancellable directly by using fpi_device_get_cancellable().