Skip to main content

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}