Internal FpImageDevice: libfprint Reference Manual

## Internal FpImageDevice Internal FpImageDevice — Internal image device functions |

## Functions

void | fpi_image_device_session_error ()
void | fpi_image_device_open_complete ()
void | fpi_image_device_close_complete ()
void | fpi_image_device_activate_complete ()
void | fpi_image_device_deactivate_complete ()
void | fpi_image_device_report_finger_status ()
void | fpi_image_device_image_captured ()
void | fpi_image_device_retry_scan ()
void | fpi_image_device_set_bz3_threshold ()

## Types and Values

enum | FpiImageDeviceState
| FpImageDeviceClass

## Description

Internal image device functions. See FpImageDevice for public routines.

## Functions

### fpi_image_device_session_error ()

    void
    fpi_image_device_session_error (FpImageDevice *self,
                                    GError *error);

Report an error while interacting with the device. This effectively aborts the current ongoing action. Note that doing so will result in the deactivation handler to be called and this function must not be used to report an error during deactivation.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
error | The GError to report |

### fpi_image_device_open_complete ()

    void
    fpi_image_device_open_complete (FpImageDevice *self,
                                    GError *error);

Reports completion of open operation.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
error | A GError or `NULL` on success |

### fpi_image_device_close_complete ()

    void
    fpi_image_device_close_complete (FpImageDevice *self,
                                     GError *error);

Reports completion of close operation.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
error | A GError or `NULL` on success |

### fpi_image_device_activate_complete ()

    void
    fpi_image_device_activate_complete (FpImageDevice *self,
                                        GError *error);

Reports completion of device activation.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
error | A GError or `NULL` on success |

### fpi_image_device_deactivate_complete ()

    void
    fpi_image_device_deactivate_complete (FpImageDevice *self,
                                          GError *error);

Reports completion of device deactivation.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
error | A GError or `NULL` on success |

### fpi_image_device_report_finger_status ()

    void
    fpi_image_device_report_finger_status (FpImageDevice *self,
                                           gboolean present);

Reports from the driver whether the user's finger is on the sensor.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
present | whether the finger is present on the sensor |

### fpi_image_device_image_captured ()

    void
    fpi_image_device_image_captured (FpImageDevice *self,
                                     FpImage *image);

Reports an image capture. Only use this function if the image was captured successfully. If there was an issue where the user should retry, use `fpi_image_device_retry_scan()` to report the retry condition.

In the event of a fatal error for the operation use `fpi_image_device_session_error()`. This will abort the entire operation including e.g. an enroll operation which captures multiple images during one session.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
image | whether the finger is present on the sensor |

### fpi_image_device_retry_scan ()

    void
    fpi_image_device_retry_scan (FpImageDevice *self,
                                 FpDeviceRetry retry);

Reports a scan failure to the user. This may or may not abort the current session. It is the equivalent of `fpi_image_device_image_captured()` in the case of a retryable error condition (e.g. short swipe).

#### Parameters

self | a FpImageDevice imaging fingerprint device |
retry | The FpDeviceRetry error code to report |

### fpi_image_device_set_bz3_threshold ()

    void
    fpi_image_device_set_bz3_threshold (FpImageDevice *self,
                                        gint bz3_threshold);

Dynamically adjust the bz3 threshold. This is only needed for drivers that support devices with different properties. It should generally be called from the probe callback, but is acceptable to call from the open callback.

#### Parameters

self | a FpImageDevice imaging fingerprint device |
bz3_threshold | BZ3 threshold to use |

## Types and Values

### enum FpiImageDeviceState

The state of an imaging device while doing a capture. The state is passed through to the driver using the ::`activate()` or ::`change_state()` vfuncs.

The driver needs to call `fpi_image_device_report_finger_status()` to move between the different states. Note that the capture state might be entered unconditionally if the device supports raw capturing.

A usual run would look like:

- inactive -> activating: activate vfunc is called

- activating -> idle: `fpi_image_device_activate_complete()`

- idle -> await-finger-on

- await-finger-on -> capture: `fpi_image_device_report_finger_status()`

- capture -> await-finger-off: `fpi_image_device_image_captured()`

- await-finger-off -> idle: `fpi_image_device_report_finger_status()`

- idle -> deactivating: deactivate vfunc is called

- deactivating -> inactive: `fpi_image_device_deactivate_complete()`

Raw mode is currently not supported (not waiting for finger), but in that case the following transitions are valid:

- idle -> capture

- capture -> idle

Also valid are these transitions in case of errors or cancellations:

- activating -> inactive: `fpi_image_device_activate_complete()`

- await-finger-on -> deactivating: deactivate vfunc is called

- capture -> deactivating: deactivate vfunc is called

- await-finger-off -> deactivating: deactivate vfunc is called

#### Members

FPI_IMAGE_DEVICE_STATE_INACTIVE | inactive |
FPI_IMAGE_DEVICE_STATE_ACTIVATING | State during activate callback |
FPI_IMAGE_DEVICE_STATE_DEACTIVATING | State during deactivate callback |
FPI_IMAGE_DEVICE_STATE_IDLE | Activated but idle |
FPI_IMAGE_DEVICE_STATE_AWAIT_FINGER_ON | waiting for the finger to be pressed or swiped |
FPI_IMAGE_DEVICE_STATE_CAPTURE | capturing an image |
FPI_IMAGE_DEVICE_STATE_AWAIT_FINGER_OFF | waiting for the finger to be removed |

### FpImageDeviceClass

    typedef struct {
      FpDeviceClass parent_class;

      gint          bz3_threshold;
      gint          img_width;
      gint          img_height;

      void          (*img_open)     (FpImageDevice *dev);
      void          (*img_close)    (FpImageDevice *dev);
      void          (*activate)     (FpImageDevice *dev);
      void          (*change_state) (FpImageDevice      *dev,
                                     FpiImageDeviceState state);
      void          (*deactivate)   (FpImageDevice *dev);
    } FpImageDeviceClass;

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.

Image drivers must expect a `deactivate` call to happen at any point during image capture.

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

#### Members

gint `bz3_threshold`; | Threshold to consider bozorth3 score a match, default: 40 |
gint `img_width`; | Width of the image, only provide if constant |
gint `img_height`; | Height of the image, only provide if constant |
`img_open` () | Open the device and do basic initialization (use this instead of the FpDeviceClass open vfunc) |
`img_close` () | Close the device (use this instead of the FpDeviceClass close vfunc) |
`activate` () | Start image capture and finger detection |
`change_state` () | Notification about the current device state (i.e. waiting for finger or image capture). Implementing this is optional, it can e.g. be used to flash an LED when waiting for a finger. |
`deactivate` () | Stop image capture and finger detection |