327 lines
13 KiB
C
327 lines
13 KiB
C
/*
|
|
* FpDevice - A 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 <gusb.h>
|
|
#include "fp-device.h"
|
|
#include "fp-image.h"
|
|
#include "fpi-print.h"
|
|
|
|
/**
|
|
* FpiDeviceUdevSubtype:
|
|
* @FPI_DEVICE_UDEV_SUBTYPE_SPIDEV: The device requires an spidev node
|
|
* @FPI_DEVICE_UDEV_SUBTYPE_HIDRAW: The device requires a hidraw node
|
|
*/
|
|
typedef enum {
|
|
FPI_DEVICE_UDEV_SUBTYPE_SPIDEV = 1 << 0,
|
|
FPI_DEVICE_UDEV_SUBTYPE_HIDRAW = 1 << 1,
|
|
} FpiDeviceUdevSubtypeFlags;
|
|
|
|
/**
|
|
* FpIdEntry:
|
|
*
|
|
* An entry in the table of supported hardware. For USB devices, the product ID
|
|
* and vendor ID should be provided. The optional @driver_data field defaults
|
|
* to 0 and can be used as a simple flag for device quirks.
|
|
*/
|
|
typedef struct _FpIdEntry FpIdEntry;
|
|
|
|
struct _FpIdEntry
|
|
{
|
|
union
|
|
{
|
|
struct
|
|
{
|
|
guint pid;
|
|
guint vid;
|
|
};
|
|
const gchar *virtual_envvar;
|
|
struct
|
|
{
|
|
FpiDeviceUdevSubtypeFlags udev_types;
|
|
const gchar *spi_acpi_id;
|
|
struct
|
|
{
|
|
guint pid;
|
|
guint vid;
|
|
} hid_id;
|
|
};
|
|
};
|
|
guint64 driver_data;
|
|
};
|
|
|
|
/**
|
|
* FpDeviceClass:
|
|
* @id: ID string for the driver. Should be a valid C identifier and should
|
|
* match the drivers file name.
|
|
* @full_name: Human readable description of the driver
|
|
* @type: The type of driver
|
|
* @id_table: The table of IDs to bind the driver to
|
|
* @features: The features the device supports, it can be initialized using
|
|
* fpi_device_class_auto_initialize_features() on @class_init.
|
|
* @nr_enroll_stages: The number of enroll stages supported devices need; use
|
|
* fpi_device_set_nr_enroll_stages() from @probe if this is dynamic.
|
|
* @scan_type: The scan type of supported devices; use
|
|
* fpi_device_set_scan_type() from @probe if this is dynamic.
|
|
* @temp_hot_seconds: Assumed time in seconds for the device to become too hot
|
|
* after being mostly cold. Set to -1 if the device can be always-on.
|
|
* @temp_cold_seconds: Assumed time in seconds for the device to be mostly cold
|
|
* after having been too hot to operate.
|
|
* @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 permissible 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 further 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
|
|
* @clear_storage: Delete all prints 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().
|
|
* @suspend: Called when an interactive action is running (ENROLL, VERIFY,
|
|
* IDENTIFY or CAPTURE) and the system is about to go into suspend.
|
|
* @resume: Called to resume an ongoing interactive action after the system has
|
|
* resumed from suspend.
|
|
*
|
|
* 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).
|
|
*
|
|
* Note that @cancel, @suspend and @resume will not be called while the device
|
|
* is within a fpi_device_critical_enter()/fpi_device_critical_leave() block.
|
|
*
|
|
* This API is solely intended for drivers. It is purely internal and neither
|
|
* API nor ABI stable.
|
|
*/
|
|
struct _FpDeviceClass
|
|
{
|
|
/*< private >*/
|
|
GObjectClass parent_class;
|
|
|
|
/*< public >*/
|
|
/* Static information about the driver. */
|
|
const gchar *id;
|
|
const gchar *full_name;
|
|
FpDeviceType type;
|
|
const FpIdEntry *id_table;
|
|
FpDeviceFeature features;
|
|
|
|
/* Defaults for device properties */
|
|
gint nr_enroll_stages;
|
|
FpScanType scan_type;
|
|
|
|
/* Simple device temperature model constants */
|
|
gint32 temp_hot_seconds;
|
|
gint32 temp_cold_seconds;
|
|
|
|
/* 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 (*clear_storage) (FpDevice * device);
|
|
|
|
void (*cancel) (FpDevice *device);
|
|
void (*suspend) (FpDevice *device);
|
|
void (*resume) (FpDevice *device);
|
|
};
|
|
|
|
void fpi_device_class_auto_initialize_features (FpDeviceClass *device_class);
|
|
|
|
/**
|
|
* FpTimeoutFunc:
|
|
* @device: The #FpDevice passed to fpi_device_add_timeout()
|
|
* @user_data: the data passed to fpi_device_add_timeout()
|
|
*
|
|
* The prototype of the callback function for fpi_device_add_timeout().
|
|
*/
|
|
typedef void (*FpTimeoutFunc) (FpDevice *device,
|
|
gpointer user_data);
|
|
|
|
/**
|
|
* FpiDeviceAction:
|
|
* @FPI_DEVICE_ACTION_NONE: No action is active.
|
|
* @FPI_DEVICE_ACTION_PROBE: Probe device for support and information.
|
|
* @FPI_DEVICE_ACTION_OPEN: Device is currently being opened.
|
|
* @FPI_DEVICE_ACTION_CLOSE: Device is currently being closed.
|
|
* @FPI_DEVICE_ACTION_ENROLL: Device is currently enrolling.
|
|
* @FPI_DEVICE_ACTION_VERIFY: Device is currently verifying.
|
|
* @FPI_DEVICE_ACTION_IDENTIFY: Device is currently identifying.
|
|
* @FPI_DEVICE_ACTION_CAPTURE: Device is currently capturing an image.
|
|
* @FPI_DEVICE_ACTION_LIST: Device stored prints are being queried.
|
|
* @FPI_DEVICE_ACTION_DELETE: Device stored print is being deleted.
|
|
* @FPI_DEVICE_ACTION_CLEAR_STORAGE: Device stored prints are being deleted.
|
|
*
|
|
* Current active action of the device. A driver can retrieve the action.
|
|
*/
|
|
typedef enum {
|
|
FPI_DEVICE_ACTION_NONE = 0,
|
|
FPI_DEVICE_ACTION_PROBE,
|
|
FPI_DEVICE_ACTION_OPEN,
|
|
FPI_DEVICE_ACTION_CLOSE,
|
|
FPI_DEVICE_ACTION_ENROLL,
|
|
FPI_DEVICE_ACTION_VERIFY,
|
|
FPI_DEVICE_ACTION_IDENTIFY,
|
|
FPI_DEVICE_ACTION_CAPTURE,
|
|
FPI_DEVICE_ACTION_LIST,
|
|
FPI_DEVICE_ACTION_DELETE,
|
|
FPI_DEVICE_ACTION_CLEAR_STORAGE,
|
|
} FpiDeviceAction;
|
|
|
|
GUsbDevice *fpi_device_get_usb_device (FpDevice *device);
|
|
const gchar *fpi_device_get_virtual_env (FpDevice *device);
|
|
gpointer fpi_device_get_udev_data (FpDevice *device,
|
|
FpiDeviceUdevSubtypeFlags subtype);
|
|
//const gchar *fpi_device_get_spi_dev (FpDevice *device);
|
|
|
|
|
|
FpiDeviceAction fpi_device_get_current_action (FpDevice *device);
|
|
gboolean fpi_device_action_is_cancelled (FpDevice *device);
|
|
|
|
GError * fpi_device_retry_new (FpDeviceRetry error);
|
|
GError * fpi_device_error_new (FpDeviceError error);
|
|
|
|
GError * fpi_device_retry_new_msg (FpDeviceRetry error,
|
|
const gchar *msg,
|
|
...) G_GNUC_PRINTF (2, 3);
|
|
GError * fpi_device_error_new_msg (FpDeviceError error,
|
|
const gchar *msg,
|
|
...) G_GNUC_PRINTF (2, 3);
|
|
|
|
guint64 fpi_device_get_driver_data (FpDevice *device);
|
|
|
|
void fpi_device_get_enroll_data (FpDevice *device,
|
|
FpPrint **print);
|
|
|
|
void fpi_device_get_capture_data (FpDevice *device,
|
|
gboolean *wait_for_finger);
|
|
void fpi_device_get_verify_data (FpDevice *device,
|
|
FpPrint **print);
|
|
void fpi_device_get_identify_data (FpDevice *device,
|
|
GPtrArray **prints);
|
|
void fpi_device_get_delete_data (FpDevice *device,
|
|
FpPrint **print);
|
|
GCancellable *fpi_device_get_cancellable (FpDevice *device);
|
|
|
|
void fpi_device_remove (FpDevice *device);
|
|
|
|
GSource * fpi_device_add_timeout (FpDevice *device,
|
|
gint interval,
|
|
FpTimeoutFunc func,
|
|
gpointer user_data,
|
|
GDestroyNotify destroy_notify);
|
|
|
|
void fpi_device_set_nr_enroll_stages (FpDevice *device,
|
|
gint enroll_stages);
|
|
|
|
void fpi_device_set_scan_type (FpDevice *device,
|
|
FpScanType scan_type);
|
|
|
|
void fpi_device_update_features (FpDevice *device,
|
|
FpDeviceFeature update,
|
|
FpDeviceFeature value);
|
|
|
|
void fpi_device_action_error (FpDevice *device,
|
|
GError *error);
|
|
|
|
void fpi_device_critical_enter (FpDevice *device);
|
|
void fpi_device_critical_leave (FpDevice *device);
|
|
|
|
void fpi_device_probe_complete (FpDevice *device,
|
|
const gchar *device_id,
|
|
const gchar *device_name,
|
|
GError *error);
|
|
void fpi_device_open_complete (FpDevice *device,
|
|
GError *error);
|
|
void fpi_device_close_complete (FpDevice *device,
|
|
GError *error);
|
|
void fpi_device_enroll_complete (FpDevice *device,
|
|
FpPrint *print,
|
|
GError *error);
|
|
void fpi_device_verify_complete (FpDevice *device,
|
|
GError *error);
|
|
void fpi_device_identify_complete (FpDevice *device,
|
|
GError *error);
|
|
void fpi_device_capture_complete (FpDevice *device,
|
|
FpImage *image,
|
|
GError *error);
|
|
void fpi_device_delete_complete (FpDevice *device,
|
|
GError *error);
|
|
void fpi_device_list_complete (FpDevice *device,
|
|
GPtrArray *prints,
|
|
GError *error);
|
|
void fpi_device_clear_storage_complete (FpDevice *device,
|
|
GError *error);
|
|
void fpi_device_suspend_complete (FpDevice *device,
|
|
GError *error);
|
|
void fpi_device_resume_complete (FpDevice *device,
|
|
GError *error);
|
|
|
|
void fpi_device_enroll_progress (FpDevice *device,
|
|
gint completed_stages,
|
|
FpPrint *print,
|
|
GError *error);
|
|
void fpi_device_verify_report (FpDevice *device,
|
|
FpiMatchResult result,
|
|
FpPrint *print,
|
|
GError *error);
|
|
void fpi_device_identify_report (FpDevice *device,
|
|
FpPrint *match,
|
|
FpPrint *print,
|
|
GError *error);
|
|
|
|
gboolean fpi_device_report_finger_status (FpDevice *device,
|
|
FpFingerStatusFlags finger_status);
|
|
gboolean fpi_device_report_finger_status_changes (FpDevice *device,
|
|
FpFingerStatusFlags added_status,
|
|
FpFingerStatusFlags removed_status);
|
|
|
|
G_END_DECLS
|