fprint_backend_libfprint/progress.rs
1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! The enroll-progress and verify/identify match trampolines.
6//!
7//! libfprint's progress/match callbacks are C function pointers with a single `user_data` slot.
8//! The worker passes a pointer to a stack-owned sink as that slot and one of these trampolines as
9//! the callback; libfprint invokes the trampoline **synchronously, on the worker thread, from
10//! inside the `*_sync` call**, so the trampoline can rebuild a shared `&Sink` and read the
11//! device's live finger status there. It forwards a fully-formed domain report over the sink's
12//! channel; the caller's future delivers the reports to the user closure.
13
14use std::os::raw::{c_int, c_void};
15use std::sync::{Arc, Mutex};
16
17use fprint_core::{EnrollProgress, FingerStatus, Temperature};
18use futures_channel::mpsc::UnboundedSender;
19use glib::translate::{from_glib_borrow, FromGlibPtrNone};
20
21use crate::convert;
22use crate::ffi::FpDevice;
23
24/// Ferries enroll progress from the worker to the caller's future: the progress sender, the
25/// device's total stage count (needed to shape each [`EnrollProgress`]), and the handle's live
26/// temperature cell (republished on every callback so [`Device::temperature`] tracks a warming
27/// sensor *during* a long enroll, not only at job boundaries).
28///
29/// [`Device::temperature`]: fprint_core::Device::temperature
30pub(crate) struct EnrollSink {
31 pub(crate) tx: UnboundedSender<EnrollProgress>,
32 pub(crate) total: u32,
33 pub(crate) temperature: Arc<Mutex<Option<Temperature>>>,
34}
35
36/// Ferries verify/identify finger-presence status from the worker to the caller's future, and
37/// republishes the live temperature on each callback (see [`EnrollSink`]).
38pub(crate) struct StatusSink {
39 pub(crate) tx: UnboundedSender<FingerStatus>,
40 pub(crate) temperature: Arc<Mutex<Option<Temperature>>>,
41}
42
43/// libfprint's per-capture enroll callback (`FpEnrollProgress`). A failed capture arrives as a
44/// retry-domain `error` with the stage count unchanged; it is relayed as
45/// [`EnrollProgress::with_retry`] rather than aborting the enrollment. A closed channel (the
46/// caller dropped the operation future) is ignored.
47///
48/// # Safety
49///
50/// Called only by libfprint, synchronously, from inside a `fp_device_enroll_sync` whose
51/// `user_data` is the `&EnrollSink` the worker kept alive across the call.
52pub(crate) unsafe extern "C" fn on_enroll_progress(
53 device: *mut libfprint_sys::FpDevice,
54 completed_stages: c_int,
55 _print: *mut libfprint_sys::FpPrint,
56 user_data: *mut c_void,
57 error: *mut libfprint_sys::GError,
58) {
59 if user_data.is_null() {
60 return;
61 }
62 // SAFETY: libfprint invokes this synchronously on the worker thread from inside the
63 // `fp_device_enroll_sync` call whose `progress_data` is this `&EnrollSink` and whose live
64 // device is `device` (borrowed, no ref taken). Both outlive the call, and the same-thread
65 // invocation means the shared borrow cannot race.
66 let sink = unsafe { &*(user_data as *const EnrollSink) };
67 let dev = unsafe { from_glib_borrow::<_, FpDevice>(device) };
68
69 // Republish the live temperature mid-enroll, so the handle's getter tracks a warming sensor
70 // across a multi-stage enrollment rather than only between jobs.
71 *sink.temperature.lock().unwrap() = convert::temperature(&dev);
72
73 let retry = if error.is_null() {
74 None
75 } else {
76 // SAFETY: `error` is a transfer-none retry `GError`; copied here for classification.
77 let err = unsafe { glib::Error::from_glib_none(error.cast()) };
78 convert::gerror_retry(&err)
79 };
80
81 let mut progress = EnrollProgress::new(completed_stages.max(0) as u32, sink.total)
82 .with_finger_status(convert::finger_status(&dev));
83 if let Some(reason) = retry {
84 progress = progress.with_retry(reason);
85 }
86 let _ = sink.tx.unbounded_send(progress);
87}
88
89/// libfprint's match callback (`FpMatchCb`), invoked when a print is matched (or a retry occurs)
90/// during verify/identify. Relays the device's live finger-presence status so the daemon can drive
91/// the `finger-present` / `finger-needed` prompts during a login as it does during enroll.
92///
93/// # Safety
94///
95/// Called only by libfprint, synchronously, from inside a `fp_device_verify_sync` /
96/// `fp_device_identify_sync` whose `user_data` is the `&StatusSink` the worker kept alive.
97pub(crate) unsafe extern "C" fn on_match_status(
98 device: *mut libfprint_sys::FpDevice,
99 _match: *mut libfprint_sys::FpPrint,
100 _print: *mut libfprint_sys::FpPrint,
101 user_data: *mut c_void,
102 _error: *mut libfprint_sys::GError,
103) {
104 if user_data.is_null() {
105 return;
106 }
107 // SAFETY: as in `on_enroll_progress` — invoked synchronously on the worker thread from inside
108 // the match `*_sync` call; `user_data` is the live `&StatusSink`, `device` the live device
109 // (borrowed, no ref taken).
110 let sink = unsafe { &*(user_data as *const StatusSink) };
111 let dev = unsafe { from_glib_borrow::<_, FpDevice>(device) };
112 // Republish the live temperature mid-verify/identify (see `on_enroll_progress`).
113 *sink.temperature.lock().unwrap() = convert::temperature(&dev);
114 let _ = sink.tx.unbounded_send(convert::finger_status(&dev));
115}