fprint_backend_libfprint/lib.rs
1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5// The whole crate is Linux-only: it dynamically links the C libfprint through `libfprint-sys`,
6// which only exists on Linux. On every other target this `#![cfg]` empties the crate so the
7// cross-platform workspace still builds and resolves.
8#![cfg(target_os = "linux")]
9
10//! # fprint-backend-libfprint
11//!
12//! A [`fprint_core::Backend`]/[`fprint_core::Device`] implementation that owns the **C libfprint**
13//! FFI directly through `libfprint-sys`, so the pure-Rust daemon can drive every sensor libfprint
14//! already supports. The LGPL library is linked *dynamically* — an interoperability boundary LGPL
15//! explicitly permits — and this crate's own source stays MIT/Apache.
16//!
17//! ## The `!Send` bridge and the worker thread
18//!
19//! libfprint's objects are glib `GObject`s bound to the thread that created their `GMainContext`,
20//! and its only entry points are the *blocking* `*_sync` calls. The shim wraps them as thin glib
21//! objects and owns their lifetime itself (the `ffi` module). [`LibfprintBackend`] holds an
22//! `FpContext` and is therefore **`!Send`**; discovery reads each device's getters on the caller
23//! thread and hands the device off to a dedicated **worker thread** that owns the `FpDevice` and
24//! runs every `*_sync` there. [`LibfprintDevice`] is thus a `Send` handle — a channel to its
25//! worker — while the sensor it drives never leaves that one thread. `fprint-core` never requires
26//! `Send` (principle 7), so either shape is expressible; cancellation runs through the worker
27//! thread.
28//!
29//! ## Cancellation
30//!
31//! `fprint-core`'s contract is "**dropping the future cancels the operation**" (principle 4), and
32//! the shim honours it fully. Each operation submits a job to the worker with a fresh
33//! [`gio::Cancellable`] and awaits the reply; the worker parks inside the blocking `*_sync` on its
34//! own thread, so the operation future yields `Pending` on the caller thread. A guard held across
35//! that await fires the cancellable — which is `Send` — from the caller thread if the future is
36//! dropped, waking the parked `*_sync` cross-thread (libfprint's own `g_cancellable_cancel` path).
37//! The worker's call returns `Cancelled` and it moves on to the next job, releasing the sensor
38//! without the caller ever waiting.
39
40// The pure crates all set this; the shim is the one published crate that may not
41// `#![forbid(unsafe_code)]` (it is the FFI quarantine), but it holds the same documentation bar.
42#![deny(missing_docs)]
43
44mod backend;
45mod convert;
46mod device;
47mod ffi;
48mod print;
49mod progress;
50mod worker;
51
52pub use backend::LibfprintBackend;
53pub use device::LibfprintDevice;
54
55/// Round-trip `bytes` through the real C libfprint's own `fp_print_deserialize` →
56/// `fp_print_serialize`, yielding libfprint's canonical FP3 encoding. The byte-identity tests use
57/// it as the real-libfprint oracle for `fprint-fp3`'s output. Gated behind the test-only `virtual`
58/// feature and hidden from docs: it is not part of the shim's API.
59#[cfg(feature = "virtual")]
60#[doc(hidden)]
61pub fn libfprint_canonical_fp3(bytes: &[u8]) -> Result<Vec<u8>, glib::Error> {
62 ffi::FpPrint::deserialize(bytes)?.serialize()
63}