libfprint/libfprint/fpi-image-device.h
Benjamin Berg 3ee5536a13 image-device: Redefine internal states and valid transitions
This adds a number of new internal states to better capture what is
going on. Also added are checks that all transitions we make are in the
set of expected and valid transitions.

Only three drivers use the state_change notification. These drivers are
updated accordingly.
2020-11-04 14:13:00 +01:00

139 lines
6 KiB
C

/*
* FpImageDevice - An image based fingerprint reader device
* Copyright (C) 2019 Benjamin Berg <bberg@redhat.com>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#pragma once
#include "fpi-device.h"
#include "fp-image-device.h"
/**
* FpiImageDeviceState:
* @FPI_IMAGE_DEVICE_STATE_INACTIVE: inactive
* @FPI_IMAGE_DEVICE_STATE_ACTIVATING: State during activate callback
* @FPI_IMAGE_DEVICE_STATE_IDLE: Activated but idle
* @FPI_IMAGE_DEVICE_STATE_DEACTIVATING: State during deactivate callback
* @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
*
* 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
*/
typedef enum {
FPI_IMAGE_DEVICE_STATE_INACTIVE,
FPI_IMAGE_DEVICE_STATE_ACTIVATING,
FPI_IMAGE_DEVICE_STATE_DEACTIVATING,
FPI_IMAGE_DEVICE_STATE_IDLE,
FPI_IMAGE_DEVICE_STATE_AWAIT_FINGER_ON,
FPI_IMAGE_DEVICE_STATE_CAPTURE,
FPI_IMAGE_DEVICE_STATE_AWAIT_FINGER_OFF,
} FpiImageDeviceState;
/**
* FpImageDeviceClass:
* @bz3_threshold: Threshold to consider bozorth3 score a match, default: 40
* @img_width: Width of the image, only provide if constant
* @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
* @deactivate: Stop 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.
*
* 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.
*/
struct _FpImageDeviceClass
{
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);
};
void fpi_image_device_set_bz3_threshold (FpImageDevice *self,
gint bz3_threshold);
void fpi_image_device_session_error (FpImageDevice *self,
GError *error);
void fpi_image_device_open_complete (FpImageDevice *self,
GError *error);
void fpi_image_device_close_complete (FpImageDevice *self,
GError *error);
void fpi_image_device_activate_complete (FpImageDevice *self,
GError *error);
void fpi_image_device_deactivate_complete (FpImageDevice *self,
GError *error);
void fpi_image_device_report_finger_status (FpImageDevice *self,
gboolean present);
void fpi_image_device_image_captured (FpImageDevice *self,
FpImage *image);
void fpi_image_device_retry_scan (FpImageDevice *self,
FpDeviceRetry retry);