GCC Code Coverage Report

Directory: ./
File: libfprint/fp-device.h
Date: 2025-08-09 07:40:30
Exec Total Coverage
Lines: 1 1 100.0%
Functions: 2 2 100.0%
Branches: 47 68 69.1%
Line Branch Exec Source
1 /*
2 * FpDevice - A fingerprint reader device
3 * Copyright (C) 2019 Benjamin Berg <bberg@redhat.com>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 */
19
20
21 #pragma once
22
23 #include "fp-image.h"
24 #include <glib-object.h>
25 #include <gio/gio.h>
26
27 G_BEGIN_DECLS
28
29 #define FP_TYPE_DEVICE (fp_device_get_type ())
30 #define FP_DEVICE_RETRY (fp_device_retry_quark ())
31 #define FP_DEVICE_ERROR (fp_device_error_quark ())
32
47/68
✓ Branch 0 (7→8) taken 827860 times.
✓ Branch 1 (7→9) taken 56 times.
✓ Branch 2 (31→32) taken 828084 times.
✓ Branch 3 (31→33) taken 235 times.
✓ Branch 4 (9→10) taken 826736 times.
✓ Branch 5 (9→11) taken 293 times.
✓ Branch 6 (9→10) taken 313 times.
✗ Branch 7 (9→11) not taken.
✓ Branch 8 (7→8) taken 2 times.
✓ Branch 9 (7→9) taken 1 times.
✓ Branch 10 (2→3) taken 4 times.
✗ Branch 11 (2→5) not taken.
✓ Branch 12 (11→12) taken 2 times.
✓ Branch 13 (11→13) taken 1 times.
✓ Branch 14 (11→12) taken 2 times.
✓ Branch 15 (11→13) taken 8 times.
✓ Branch 16 (11→12) taken 166 times.
✓ Branch 17 (11→13) taken 1 times.
✓ Branch 18 (11→12) taken 1 times.
✗ Branch 19 (11→13) not taken.
✓ Branch 20 (11→12) taken 1 times.
✓ Branch 21 (11→13) taken 235 times.
✓ Branch 22 (11→12) taken 1 times.
✓ Branch 23 (11→13) taken 12 times.
✓ Branch 24 (22→23) taken 1 times.
✓ Branch 25 (22→24) taken 33614 times.
✓ Branch 26 (4→5) taken 1 times.
✓ Branch 27 (4→7) taken 33614 times.
✗ Branch 28 (22→23) not taken.
✓ Branch 29 (22→24) taken 33615 times.
✓ Branch 30 (20→21) taken 1 times.
✗ Branch 31 (20→22) not taken.
✓ Branch 32 (3→4) taken 1 times.
✗ Branch 33 (3→5) not taken.
✗ Branch 34 (4→5) not taken.
✓ Branch 35 (4→6) taken 1 times.
✗ Branch 36 (4→5) not taken.
✓ Branch 37 (4→6) taken 1 times.
✓ Branch 38 (8→9) taken 1 times.
✗ Branch 39 (8→10) not taken.
✓ Branch 40 (18→19) taken 1 times.
✗ Branch 41 (18→20) not taken.
✓ Branch 42 (17→18) taken 1 times.
✗ Branch 43 (17→19) not taken.
✓ Branch 44 (9→10) taken 1 times.
✗ Branch 45 (9→11) not taken.
✓ Branch 46 (6→7) taken 1 times.
✗ Branch 47 (6→8) not taken.
✓ Branch 48 (8→9) taken 1 times.
✗ Branch 49 (8→10) not taken.
✓ Branch 50 (8→9) taken 1 times.
✗ Branch 51 (8→10) not taken.
✓ Branch 52 (15→16) taken 1 times.
✗ Branch 53 (15→17) not taken.
✓ Branch 54 (9→10) taken 1 times.
✗ Branch 55 (9→11) not taken.
✓ Branch 56 (8→9) taken 1 times.
✗ Branch 57 (8→10) not taken.
✓ Branch 58 (9→10) taken 1 times.
✗ Branch 59 (9→11) not taken.
✓ Branch 60 (9→10) taken 1 times.
✓ Branch 61 (9→11) taken 50 times.
✓ Branch 62 (3→4) taken 5 times.
✓ Branch 63 (3→7) taken 4 times.
✓ Branch 64 (4→5) taken 5 times.
✗ Branch 65 (4→6) not taken.
✓ Branch 66 (5→6) taken 5 times.
✗ Branch 67 (5→7) not taken.
 898803 G_DECLARE_DERIVABLE_TYPE (FpDevice, fp_device, FP, DEVICE, GObject)
33
34 #include "fp-print.h"
35
36 /* NOTE: We keep the class struct private! */
37
38 /**
39 * FpDeviceType:
40 * @FP_DEVICE_TYPE_VIRTUAL: The device is a virtual device
41 * @FP_DEVICE_TYPE_UDEV: The device is a udev device
42 * @FP_DEVICE_TYPE_USB: The device is a USB device
43 */
44 typedef enum {
45 FP_DEVICE_TYPE_VIRTUAL,
46 FP_DEVICE_TYPE_UDEV,
47 FP_DEVICE_TYPE_USB,
48 } FpDeviceType;
49
50 /**
51 * FpDeviceFeature:
52 * @FP_DEVICE_FEATURE_NONE: Device does not support any feature
53 * @FP_DEVICE_FEATURE_CAPTURE: Supports image capture
54 * @FP_DEVICE_FEATURE_VERIFY: Supports finger verification
55 * @FP_DEVICE_FEATURE_IDENTIFY: Supports finger identification
56 * @FP_DEVICE_FEATURE_STORAGE: Device has a persistent storage
57 * @FP_DEVICE_FEATURE_STORAGE_LIST: Supports listing the storage templates
58 * @FP_DEVICE_FEATURE_STORAGE_DELETE: Supports deleting stored templates
59 * @FP_DEVICE_FEATURE_STORAGE_CLEAR: Supports clearing the whole storage
60 * @FP_DEVICE_FEATURE_DUPLICATES_CHECK: Natively supports duplicates detection
61 * @FP_DEVICE_FEATURE_ALWAYS_ON: Whether the device can run continuously
62 * @FP_DEVICE_FEATURE_UPDATE_PRINT: Supports updating an existing print record using new scans
63 */
64 typedef enum /*< flags >*/ {
65 FP_DEVICE_FEATURE_NONE = 0,
66 FP_DEVICE_FEATURE_CAPTURE = 1 << 0,
67 FP_DEVICE_FEATURE_IDENTIFY = 1 << 1,
68 FP_DEVICE_FEATURE_VERIFY = 1 << 2,
69 FP_DEVICE_FEATURE_STORAGE = 1 << 3,
70 FP_DEVICE_FEATURE_STORAGE_LIST = 1 << 4,
71 FP_DEVICE_FEATURE_STORAGE_DELETE = 1 << 5,
72 FP_DEVICE_FEATURE_STORAGE_CLEAR = 1 << 6,
73 FP_DEVICE_FEATURE_DUPLICATES_CHECK = 1 << 7,
74 FP_DEVICE_FEATURE_ALWAYS_ON = 1 << 8,
75 FP_DEVICE_FEATURE_UPDATE_PRINT = 1 << 9,
76 } FpDeviceFeature;
77
78 /**
79 * FpScanType:
80 * @FP_SCAN_TYPE_SWIPE: Sensor requires swiping the finger.
81 * @FP_SCAN_TYPE_PRESS: Sensor requires placing/pressing down the finger.
82 */
83 typedef enum {
84 FP_SCAN_TYPE_SWIPE,
85 FP_SCAN_TYPE_PRESS,
86 } FpScanType;
87
88 /**
89 * FpTemperature:
90 * @FP_TEMPERATURE_COLD: Sensor is considered cold.
91 * @FP_TEMPERATURE_WARM: Sensor is warm, usage time may be limited.
92 * @FP_TEMPERATURE_HOT: Sensor is hot and cannot be used.
93 *
94 * When a device is created, it is assumed to be cold. Applications such as
95 * fprintd may want to ensure all devices on the system are cold before
96 * shutting down in order to ensure that the cool-off period is not violated
97 * because the internal libfprint state about the device is lost.
98 */
99 typedef enum {
100 FP_TEMPERATURE_COLD,
101 FP_TEMPERATURE_WARM,
102 FP_TEMPERATURE_HOT,
103 } FpTemperature;
104
105 /**
106 * FpDeviceRetry:
107 * @FP_DEVICE_RETRY_GENERAL: The scan did not succeed due to poor scan quality
108 * or other general user scanning problem.
109 * @FP_DEVICE_RETRY_TOO_SHORT: The scan did not succeed because the finger
110 * swipe was too short.
111 * @FP_DEVICE_RETRY_CENTER_FINGER: The scan did not succeed because the finger
112 * was not centered on the scanner.
113 * @FP_DEVICE_RETRY_REMOVE_FINGER: The scan did not succeed due to quality or
114 * pressure problems; the user should remove their finger from the scanner
115 * before retrying.
116 * @FP_DEVICE_RETRY_TOO_FAST: The scan did not succeed because the finger
117 * swipe or touch was too fast.
118 *
119 * Error codes representing scan failures resulting in the user needing to
120 * retry.
121 */
122 typedef enum {
123 FP_DEVICE_RETRY_GENERAL,
124 FP_DEVICE_RETRY_TOO_SHORT,
125 FP_DEVICE_RETRY_CENTER_FINGER,
126 FP_DEVICE_RETRY_REMOVE_FINGER,
127 FP_DEVICE_RETRY_TOO_FAST,
128 } FpDeviceRetry;
129
130 /**
131 * FpDeviceError:
132 * @FP_DEVICE_ERROR_GENERAL: A general error occurred.
133 * @FP_DEVICE_ERROR_NOT_SUPPORTED: The device does not support the requested
134 * operation.
135 * @FP_DEVICE_ERROR_NOT_OPEN: The device needs to be opened to start this
136 * operation.
137 * @FP_DEVICE_ERROR_ALREADY_OPEN: The device has already been opened.
138 * @FP_DEVICE_ERROR_BUSY: The device is busy with another request.
139 * @FP_DEVICE_ERROR_PROTO: Protocol error
140 * @FP_DEVICE_ERROR_DATA_INVALID: The passed data is invalid
141 * @FP_DEVICE_ERROR_DATA_NOT_FOUND: Requested print was not found on device
142 * @FP_DEVICE_ERROR_DATA_FULL: No space on device available for operation
143 * @FP_DEVICE_ERROR_DATA_DUPLICATE: Enrolling template duplicates storaged templates
144 * @FP_DEVICE_ERROR_REMOVED: The device has been removed.
145 * @FP_DEVICE_ERROR_TOO_HOT: The device might be getting too hot
146 *
147 * Error codes for device operations. More specific errors from other domains
148 * such as #G_IO_ERROR or #G_USB_DEVICE_ERROR may also be reported.
149 */
150 typedef enum {
151 FP_DEVICE_ERROR_GENERAL,
152 FP_DEVICE_ERROR_NOT_SUPPORTED,
153 FP_DEVICE_ERROR_NOT_OPEN,
154 FP_DEVICE_ERROR_ALREADY_OPEN,
155 FP_DEVICE_ERROR_BUSY,
156 FP_DEVICE_ERROR_PROTO,
157 FP_DEVICE_ERROR_DATA_INVALID,
158 FP_DEVICE_ERROR_DATA_NOT_FOUND,
159 FP_DEVICE_ERROR_DATA_FULL,
160 FP_DEVICE_ERROR_DATA_DUPLICATE,
161 /* Leave some room to add more DATA related errors */
162 FP_DEVICE_ERROR_REMOVED = 0x100,
163 FP_DEVICE_ERROR_TOO_HOT,
164 } FpDeviceError;
165
166 GQuark fp_device_retry_quark (void);
167 GQuark fp_device_error_quark (void);
168
169 /**
170 * FpEnrollProgress:
171 * @device: a #FpDevice
172 * @completed_stages: Number of completed stages
173 * @print: (nullable) (transfer none): The last scanned print
174 * @user_data: (nullable) (transfer none): User provided data
175 * @error: (nullable) (transfer none): #GError or %NULL
176 *
177 * The passed error is guaranteed to be of type %FP_DEVICE_RETRY if set.
178 */
179 typedef void (*FpEnrollProgress) (FpDevice *device,
180 gint completed_stages,
181 FpPrint *print,
182 gpointer user_data,
183 GError *error);
184
185 /**
186 * FpMatchCb:
187 * @device: a #FpDevice
188 * @match: (nullable) (transfer none): The matching print if any matched @print
189 * @print: (nullable) (transfer none): The newly scanned print
190 * @user_data: (nullable) (transfer none): User provided data
191 * @error: (nullable) (transfer none): #GError or %NULL
192 *
193 * Report the result of a match (identify or verify) operation.
194 *
195 * If @match is non-%NULL, then it is set to the matching #FpPrint as passed
196 * to the match operation. In this case @error will always be %NULL.
197 *
198 * If @error is not %NULL then its domain is guaranteed to be
199 * %FP_DEVICE_RETRY. All other error conditions will not be reported using
200 * this callback. If such an error occurs before a match/no-match decision
201 * can be made, then this callback will not be called. Should an error
202 * happen afterwards, then you will get a match report through this callback
203 * and an error when the operation finishes.
204 *
205 * If @match and @error are %NULL, then a finger was presented but it did not
206 * match any known print.
207 *
208 * @print represents the newly scanned print. The driver may or may not
209 * provide this information. Image based devices will provide it and it
210 * allows access to the raw data.
211 *
212 * This callback exists because it makes sense for drivers to wait e.g. on
213 * finger removal before completing the match operation. However, the
214 * success/failure can often be reported at an earlier time, and there is
215 * no need to make the user wait.
216 */
217 typedef void (*FpMatchCb) (FpDevice *device,
218 FpPrint *match,
219 FpPrint *print,
220 gpointer user_data,
221 GError *error);
222
223 const gchar *fp_device_get_driver (FpDevice *device);
224 const gchar *fp_device_get_device_id (FpDevice *device);
225 const gchar *fp_device_get_name (FpDevice *device);
226 gboolean fp_device_is_open (FpDevice *device);
227 FpScanType fp_device_get_scan_type (FpDevice *device);
228 FpFingerStatusFlags fp_device_get_finger_status (FpDevice *device);
229 gint fp_device_get_nr_enroll_stages (FpDevice *device);
230 FpTemperature fp_device_get_temperature (FpDevice *device);
231
232 FpDeviceFeature fp_device_get_features (FpDevice *device);
233 gboolean fp_device_has_feature (FpDevice *device,
234 FpDeviceFeature feature);
235
236 /* Opening the device */
237 void fp_device_open (FpDevice *device,
238 GCancellable *cancellable,
239 GAsyncReadyCallback callback,
240 gpointer user_data);
241
242 void fp_device_close (FpDevice *device,
243 GCancellable *cancellable,
244 GAsyncReadyCallback callback,
245 gpointer user_data);
246
247 void fp_device_suspend (FpDevice *device,
248 GCancellable *cancellable,
249 GAsyncReadyCallback callback,
250 gpointer user_data);
251
252 void fp_device_resume (FpDevice *device,
253 GCancellable *cancellable,
254 GAsyncReadyCallback callback,
255 gpointer user_data);
256
257 void fp_device_enroll (FpDevice *device,
258 FpPrint *template_print,
259 GCancellable *cancellable,
260 FpEnrollProgress progress_cb,
261 gpointer progress_data,
262 GDestroyNotify progress_destroy,
263 GAsyncReadyCallback callback,
264 gpointer user_data);
265
266 void fp_device_verify (FpDevice *device,
267 FpPrint *enrolled_print,
268 GCancellable *cancellable,
269 FpMatchCb match_cb,
270 gpointer match_data,
271 GDestroyNotify match_destroy,
272 GAsyncReadyCallback callback,
273 gpointer user_data);
274
275 void fp_device_identify (FpDevice *device,
276 GPtrArray *prints,
277 GCancellable *cancellable,
278 FpMatchCb match_cb,
279 gpointer match_data,
280 GDestroyNotify match_destroy,
281 GAsyncReadyCallback callback,
282 gpointer user_data);
283
284 void fp_device_capture (FpDevice *device,
285 gboolean wait_for_finger,
286 GCancellable *cancellable,
287 GAsyncReadyCallback callback,
288 gpointer user_data);
289
290 void fp_device_delete_print (FpDevice *device,
291 FpPrint *enrolled_print,
292 GCancellable *cancellable,
293 GAsyncReadyCallback callback,
294 gpointer user_data);
295
296 void fp_device_list_prints (FpDevice *device,
297 GCancellable *cancellable,
298 GAsyncReadyCallback callback,
299 gpointer user_data);
300
301 void fp_device_clear_storage (FpDevice *device,
302 GCancellable *cancellable,
303 GAsyncReadyCallback callback,
304 gpointer user_data);
305
306 gboolean fp_device_open_finish (FpDevice *device,
307 GAsyncResult *result,
308 GError **error);
309 gboolean fp_device_close_finish (FpDevice *device,
310 GAsyncResult *result,
311 GError **error);
312 gboolean fp_device_suspend_finish (FpDevice *device,
313 GAsyncResult *result,
314 GError **error);
315 gboolean fp_device_resume_finish (FpDevice *device,
316 GAsyncResult *result,
317 GError **error);
318 FpPrint *fp_device_enroll_finish (FpDevice *device,
319 GAsyncResult *result,
320 GError **error);
321 gboolean fp_device_verify_finish (FpDevice *device,
322 GAsyncResult *result,
323 gboolean *match,
324 FpPrint **print,
325 GError **error);
326 gboolean fp_device_identify_finish (FpDevice *device,
327 GAsyncResult *result,
328 FpPrint **match,
329 FpPrint **print,
330 GError **error);
331 FpImage * fp_device_capture_finish (FpDevice *device,
332 GAsyncResult *result,
333 GError **error);
334 gboolean fp_device_delete_print_finish (FpDevice *device,
335 GAsyncResult *result,
336 GError **error);
337 GPtrArray * fp_device_list_prints_finish (FpDevice *device,
338 GAsyncResult *result,
339 GError **error);
340 gboolean fp_device_clear_storage_finish (FpDevice *device,
341 GAsyncResult *result,
342 GError **error);
343
344 gboolean fp_device_open_sync (FpDevice *device,
345 GCancellable *cancellable,
346 GError **error);
347 gboolean fp_device_close_sync (FpDevice *device,
348 GCancellable *cancellable,
349 GError **error);
350 FpPrint * fp_device_enroll_sync (FpDevice *device,
351 FpPrint *template_print,
352 GCancellable *cancellable,
353 FpEnrollProgress progress_cb,
354 gpointer progress_data,
355 GError **error);
356 gboolean fp_device_verify_sync (FpDevice *device,
357 FpPrint *enrolled_print,
358 GCancellable *cancellable,
359 FpMatchCb match_cb,
360 gpointer match_data,
361 gboolean *match,
362 FpPrint **print,
363 GError **error);
364 gboolean fp_device_identify_sync (FpDevice *device,
365 GPtrArray *prints,
366 GCancellable *cancellable,
367 FpMatchCb match_cb,
368 gpointer match_data,
369 FpPrint **match,
370 FpPrint **print,
371 GError **error);
372 FpImage * fp_device_capture_sync (FpDevice *device,
373 gboolean wait_for_finger,
374 GCancellable *cancellable,
375 GError **error);
376 gboolean fp_device_delete_print_sync (FpDevice *device,
377 FpPrint *enrolled_print,
378 GCancellable *cancellable,
379 GError **error);
380 GPtrArray * fp_device_list_prints_sync (FpDevice *device,
381 GCancellable *cancellable,
382 GError **error);
383 gboolean fp_device_clear_storage_sync (FpDevice *device,
384 GCancellable *cancellable,
385 GError **error);
386 gboolean fp_device_suspend_sync (FpDevice *device,
387 GCancellable *cancellable,
388 GError **error);
389 gboolean fp_device_resume_sync (FpDevice *device,
390 GCancellable *cancellable,
391 GError **error);
392
393 /* Deprecated functions */
394 G_DEPRECATED_FOR (fp_device_get_features)
395 gboolean fp_device_supports_identify (FpDevice *device);
396 G_DEPRECATED_FOR (fp_device_get_features)
397 gboolean fp_device_supports_capture (FpDevice *device);
398 G_DEPRECATED_FOR (fp_device_get_features)
399 gboolean fp_device_has_storage (FpDevice *device);
400
401 G_END_DECLS
402