1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
|
/*
* 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"
/**
* FpiDeviceUdevSubtypeFlags:
* @FPI_DEVICE_UDEV_SUBTYPE_SPIDEV: The device requires an spidev node
* @FPI_DEVICE_UDEV_SUBTYPE_HIDRAW: The device requires a hidraw node
*
* Bitfield of required hardware resources for a udev-backed device.
*/
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
|