GCC Code Coverage Report

Directory: ./
File: libfprint/fp-device.h
Date: 2024-05-04 14:54:39
Exec Total Coverage
Lines: 1 1 100.0%
Functions: 2 2 100.0%
Branches: 57 90 63.3%
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
57/90
✓ Branch 0 taken 5 times.
✓ Branch 1 taken 825773 times.
✓ Branch 2 taken 7 times.
✓ Branch 3 taken 825773 times.
✓ Branch 4 taken 79 times.
✓ Branch 5 taken 824533 times.
✓ Branch 6 taken 77 times.
✓ Branch 7 taken 1 times.
✓ Branch 8 taken 77 times.
✗ Branch 9 not taken.
✓ Branch 10 taken 1 times.
✓ Branch 11 taken 92 times.
✓ Branch 12 taken 51 times.
✓ Branch 13 taken 233 times.
✓ Branch 14 taken 232 times.
✓ Branch 15 taken 232 times.
✓ Branch 16 taken 233 times.
✓ Branch 17 taken 232 times.
✗ Branch 18 not taken.
✓ Branch 19 taken 1 times.
✓ Branch 20 taken 2 times.
✓ Branch 21 taken 3 times.
✗ Branch 22 not taken.
✓ Branch 23 taken 1 times.
✓ Branch 24 taken 1 times.
✓ Branch 25 taken 1 times.
✓ Branch 26 taken 8 times.
✓ Branch 27 taken 165 times.
✓ Branch 28 taken 2 times.
✗ Branch 29 not taken.
✗ Branch 30 not taken.
✗ Branch 31 not taken.
✓ Branch 32 taken 233 times.
✗ Branch 33 not taken.
✓ Branch 35 taken 12 times.
✗ Branch 36 not taken.
✓ Branch 38 taken 31472 times.
✗ Branch 39 not taken.
✓ Branch 40 taken 31471 times.
✗ Branch 41 not taken.
✓ Branch 42 taken 31472 times.
✗ Branch 43 not taken.
✓ Branch 50 taken 1 times.
✗ Branch 51 not taken.
✓ Branch 54 taken 1 times.
✗ Branch 55 not taken.
✓ Branch 68 taken 1 times.
✗ Branch 69 not taken.
✓ Branch 70 taken 1 times.
✗ Branch 71 not taken.
✗ Branch 73 not taken.
✓ Branch 74 taken 1 times.
✓ Branch 76 taken 1 times.
✗ Branch 77 not taken.
✓ Branch 80 taken 1 times.
✗ Branch 81 not taken.
✗ Branch 82 not taken.
✓ Branch 83 taken 1 times.
✗ Branch 85 not taken.
✓ Branch 86 taken 1 times.
✓ Branch 88 taken 1 times.
✗ Branch 89 not taken.
✓ Branch 91 taken 1 times.
✗ Branch 92 not taken.
✓ Branch 95 taken 1 times.
✗ Branch 96 not taken.
✓ Branch 100 taken 1 times.
✗ Branch 101 not taken.
✓ Branch 104 taken 1 times.
✗ Branch 105 not taken.
✓ Branch 112 taken 1 times.
✗ Branch 113 not taken.
✓ Branch 116 taken 1 times.
✗ Branch 117 not taken.
✓ Branch 120 taken 1 times.
✗ Branch 121 not taken.
✓ Branch 123 taken 1 times.
✗ Branch 124 not taken.
✓ Branch 127 taken 1 times.
✗ Branch 128 not taken.
✓ Branch 130 taken 1 times.
✗ Branch 131 not taken.
✓ Branch 134 taken 1 times.
✓ Branch 135 taken 50 times.
✓ Branch 138 taken 5 times.
✓ Branch 139 taken 4 times.
✓ Branch 140 taken 5 times.
✗ Branch 141 not taken.
✓ Branch 142 taken 5 times.
✗ Branch 143 not taken.
 1702633 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 *
117 * Error codes representing scan failures resulting in the user needing to
118 * retry.
119 */
120 typedef enum {
121 FP_DEVICE_RETRY_GENERAL,
122 FP_DEVICE_RETRY_TOO_SHORT,
123 FP_DEVICE_RETRY_CENTER_FINGER,
124 FP_DEVICE_RETRY_REMOVE_FINGER,
125 } FpDeviceRetry;
126
127 /**
128 * FpDeviceError:
129 * @FP_DEVICE_ERROR_GENERAL: A general error occurred.
130 * @FP_DEVICE_ERROR_NOT_SUPPORTED: The device does not support the requested
131 * operation.
132 * @FP_DEVICE_ERROR_NOT_OPEN: The device needs to be opened to start this
133 * operation.
134 * @FP_DEVICE_ERROR_ALREADY_OPEN: The device has already been opened.
135 * @FP_DEVICE_ERROR_BUSY: The device is busy with another request.
136 * @FP_DEVICE_ERROR_PROTO: Protocol error
137 * @FP_DEVICE_ERROR_DATA_INVALID: The passed data is invalid
138 * @FP_DEVICE_ERROR_DATA_NOT_FOUND: Requested print was not found on device
139 * @FP_DEVICE_ERROR_DATA_FULL: No space on device available for operation
140 * @FP_DEVICE_ERROR_DATA_DUPLICATE: Enrolling template duplicates storaged templates
141 * @FP_DEVICE_ERROR_REMOVED: The device has been removed.
142 * @FP_DEVICE_ERROR_TOO_HOT: The device might be getting too hot
143 *
144 * Error codes for device operations. More specific errors from other domains
145 * such as #G_IO_ERROR or #G_USB_DEVICE_ERROR may also be reported.
146 */
147 typedef enum {
148 FP_DEVICE_ERROR_GENERAL,
149 FP_DEVICE_ERROR_NOT_SUPPORTED,
150 FP_DEVICE_ERROR_NOT_OPEN,
151 FP_DEVICE_ERROR_ALREADY_OPEN,
152 FP_DEVICE_ERROR_BUSY,
153 FP_DEVICE_ERROR_PROTO,
154 FP_DEVICE_ERROR_DATA_INVALID,
155 FP_DEVICE_ERROR_DATA_NOT_FOUND,
156 FP_DEVICE_ERROR_DATA_FULL,
157 FP_DEVICE_ERROR_DATA_DUPLICATE,
158 /* Leave some room to add more DATA related errors */
159 FP_DEVICE_ERROR_REMOVED = 0x100,
160 FP_DEVICE_ERROR_TOO_HOT,
161 } FpDeviceError;
162
163 GQuark fp_device_retry_quark (void);
164 GQuark fp_device_error_quark (void);
165
166 /**
167 * FpEnrollProgress:
168 * @device: a #FpDevice
169 * @completed_stages: Number of completed stages
170 * @print: (nullable) (transfer none): The last scanned print
171 * @user_data: (nullable) (transfer none): User provided data
172 * @error: (nullable) (transfer none): #GError or %NULL
173 *
174 * The passed error is guaranteed to be of type %FP_DEVICE_RETRY if set.
175 */
176 typedef void (*FpEnrollProgress) (FpDevice *device,
177 gint completed_stages,
178 FpPrint *print,
179 gpointer user_data,
180 GError *error);
181
182 /**
183 * FpMatchCb:
184 * @device: a #FpDevice
185 * @match: (nullable) (transfer none): The matching print if any matched @print
186 * @print: (nullable) (transfer none): The newly scanned print
187 * @user_data: (nullable) (transfer none): User provided data
188 * @error: (nullable) (transfer none): #GError or %NULL
189 *
190 * Report the result of a match (identify or verify) operation.
191 *
192 * If @match is non-%NULL, then it is set to the matching #FpPrint as passed
193 * to the match operation. In this case @error will always be %NULL.
194 *
195 * If @error is not %NULL then its domain is guaranteed to be
196 * %FP_DEVICE_RETRY. All other error conditions will not be reported using
197 * this callback. If such an error occurs before a match/no-match decision
198 * can be made, then this callback will not be called. Should an error
199 * happen afterwards, then you will get a match report through this callback
200 * and an error when the operation finishes.
201 *
202 * If @match and @error are %NULL, then a finger was presented but it did not
203 * match any known print.
204 *
205 * @print represents the newly scanned print. The driver may or may not
206 * provide this information. Image based devices will provide it and it
207 * allows access to the raw data.
208 *
209 * This callback exists because it makes sense for drivers to wait e.g. on
210 * finger removal before completing the match operation. However, the
211 * success/failure can often be reported at an earlier time, and there is
212 * no need to make the user wait.
213 */
214 typedef void (*FpMatchCb) (FpDevice *device,
215 FpPrint *match,
216 FpPrint *print,
217 gpointer user_data,
218 GError *error);
219
220 const gchar *fp_device_get_driver (FpDevice *device);
221 const gchar *fp_device_get_device_id (FpDevice *device);
222 const gchar *fp_device_get_name (FpDevice *device);
223 gboolean fp_device_is_open (FpDevice *device);
224 FpScanType fp_device_get_scan_type (FpDevice *device);
225 FpFingerStatusFlags fp_device_get_finger_status (FpDevice *device);
226 gint fp_device_get_nr_enroll_stages (FpDevice *device);
227 FpTemperature fp_device_get_temperature (FpDevice *device);
228
229 FpDeviceFeature fp_device_get_features (FpDevice *device);
230 gboolean fp_device_has_feature (FpDevice *device,
231 FpDeviceFeature feature);
232
233 /* Opening the device */
234 void fp_device_open (FpDevice *device,
235 GCancellable *cancellable,
236 GAsyncReadyCallback callback,
237 gpointer user_data);
238
239 void fp_device_close (FpDevice *device,
240 GCancellable *cancellable,
241 GAsyncReadyCallback callback,
242 gpointer user_data);
243
244 void fp_device_suspend (FpDevice *device,
245 GCancellable *cancellable,
246 GAsyncReadyCallback callback,
247 gpointer user_data);
248
249 void fp_device_resume (FpDevice *device,
250 GCancellable *cancellable,
251 GAsyncReadyCallback callback,
252 gpointer user_data);
253
254 void fp_device_enroll (FpDevice *device,
255 FpPrint *template_print,
256 GCancellable *cancellable,
257 FpEnrollProgress progress_cb,
258 gpointer progress_data,
259 GDestroyNotify progress_destroy,
260 GAsyncReadyCallback callback,
261 gpointer user_data);
262
263 void fp_device_verify (FpDevice *device,
264 FpPrint *enrolled_print,
265 GCancellable *cancellable,
266 FpMatchCb match_cb,
267 gpointer match_data,
268 GDestroyNotify match_destroy,
269 GAsyncReadyCallback callback,
270 gpointer user_data);
271
272 void fp_device_identify (FpDevice *device,
273 GPtrArray *prints,
274 GCancellable *cancellable,
275 FpMatchCb match_cb,
276 gpointer match_data,
277 GDestroyNotify match_destroy,
278 GAsyncReadyCallback callback,
279 gpointer user_data);
280
281 void fp_device_capture (FpDevice *device,
282 gboolean wait_for_finger,
283 GCancellable *cancellable,
284 GAsyncReadyCallback callback,
285 gpointer user_data);
286
287 void fp_device_delete_print (FpDevice *device,
288 FpPrint *enrolled_print,
289 GCancellable *cancellable,
290 GAsyncReadyCallback callback,
291 gpointer user_data);
292
293 void fp_device_list_prints (FpDevice *device,
294 GCancellable *cancellable,
295 GAsyncReadyCallback callback,
296 gpointer user_data);
297
298 void fp_device_clear_storage (FpDevice *device,
299 GCancellable *cancellable,
300 GAsyncReadyCallback callback,
301 gpointer user_data);
302
303 gboolean fp_device_open_finish (FpDevice *device,
304 GAsyncResult *result,
305 GError **error);
306 gboolean fp_device_close_finish (FpDevice *device,
307 GAsyncResult *result,
308 GError **error);
309 gboolean fp_device_suspend_finish (FpDevice *device,
310 GAsyncResult *result,
311 GError **error);
312 gboolean fp_device_resume_finish (FpDevice *device,
313 GAsyncResult *result,
314 GError **error);
315 FpPrint *fp_device_enroll_finish (FpDevice *device,
316 GAsyncResult *result,
317 GError **error);
318 gboolean fp_device_verify_finish (FpDevice *device,
319 GAsyncResult *result,
320 gboolean *match,
321 FpPrint **print,
322 GError **error);
323 gboolean fp_device_identify_finish (FpDevice *device,
324 GAsyncResult *result,
325 FpPrint **match,
326 FpPrint **print,
327 GError **error);
328 FpImage * fp_device_capture_finish (FpDevice *device,
329 GAsyncResult *result,
330 GError **error);
331 gboolean fp_device_delete_print_finish (FpDevice *device,
332 GAsyncResult *result,
333 GError **error);
334 GPtrArray * fp_device_list_prints_finish (FpDevice *device,
335 GAsyncResult *result,
336 GError **error);
337 gboolean fp_device_clear_storage_finish (FpDevice *device,
338 GAsyncResult *result,
339 GError **error);
340
341 gboolean fp_device_open_sync (FpDevice *device,
342 GCancellable *cancellable,
343 GError **error);
344 gboolean fp_device_close_sync (FpDevice *device,
345 GCancellable *cancellable,
346 GError **error);
347 FpPrint * fp_device_enroll_sync (FpDevice *device,
348 FpPrint *template_print,
349 GCancellable *cancellable,
350 FpEnrollProgress progress_cb,
351 gpointer progress_data,
352 GError **error);
353 gboolean fp_device_verify_sync (FpDevice *device,
354 FpPrint *enrolled_print,
355 GCancellable *cancellable,
356 FpMatchCb match_cb,
357 gpointer match_data,
358 gboolean *match,
359 FpPrint **print,
360 GError **error);
361 gboolean fp_device_identify_sync (FpDevice *device,
362 GPtrArray *prints,
363 GCancellable *cancellable,
364 FpMatchCb match_cb,
365 gpointer match_data,
366 FpPrint **match,
367 FpPrint **print,
368 GError **error);
369 FpImage * fp_device_capture_sync (FpDevice *device,
370 gboolean wait_for_finger,
371 GCancellable *cancellable,
372 GError **error);
373 gboolean fp_device_delete_print_sync (FpDevice *device,
374 FpPrint *enrolled_print,
375 GCancellable *cancellable,
376 GError **error);
377 GPtrArray * fp_device_list_prints_sync (FpDevice *device,
378 GCancellable *cancellable,
379 GError **error);
380 gboolean fp_device_clear_storage_sync (FpDevice *device,
381 GCancellable *cancellable,
382 GError **error);
383 gboolean fp_device_suspend_sync (FpDevice *device,
384 GCancellable *cancellable,
385 GError **error);
386 gboolean fp_device_resume_sync (FpDevice *device,
387 GCancellable *cancellable,
388 GError **error);
389
390 /* Deprecated functions */
391 G_DEPRECATED_FOR (fp_device_get_features)
392 gboolean fp_device_supports_identify (FpDevice *device);
393 G_DEPRECATED_FOR (fp_device_get_features)
394 gboolean fp_device_supports_capture (FpDevice *device);
395 G_DEPRECATED_FOR (fp_device_get_features)
396 gboolean fp_device_has_storage (FpDevice *device);
397
398 G_END_DECLS
399