Skip to main content

Crate fprint_core

Crate fprint_core 

Source
Expand description

§fprint-core

The GObject-free core of an fprintd-compatible fingerprint stack: the domain model (fingers, device capabilities, prints/templates) plus the Backend/Device traits that a concrete backend implements.

It contains no device drivers, USB code, or matching algorithms; those live in downstream crates:

  • fprint-backend-libfprint implements Backend by wrapping the C libfprint, and
  • fprint-backend-native implements the same trait with pure-Rust drivers + transport.

The fprintd-compatible daemon (fprintd) depends only on these traits, so the backend can be swapped without touching the daemon.

Enum values that cross a wire boundary (the FP3 template format, fprintd’s per-finger file names) mirror libfprint’s C enums exactly — see Finger — so the stack stays interoperable with existing /var/lib/fprint stores. The device-capability enums (DeviceFeature, ScanType) mirror their libfprint counterparts too. The wire vocabularies themselves (the net.reactivated.Fprint finger-name and status strings) live at the daemon edge, not here (ARCHITECTURE.md principle 3).

§Implementing a backend

A backend is a type that hands out Devices. Both traits are native async fn traits with no dyn and no runtime: a backend is a struct and two impl blocks. The example below is compiled as a doctest, depending on nothing but std.

use fprint_core::{
    Backend, Device, DeviceFeature, DeviceId, DeviceInfo, DriverId, EnrollProgress, Error,
    Finger, FingerStatus, IdentifyOutcome, Print, Result, ScanType, Template, VerifyOutcome,
};

/// A match-on-chip reader holding one template.
struct Demo {
    info: DeviceInfo,
    stored: Option<Print>,
}

impl Device for Demo {
    fn info(&self) -> &DeviceInfo {
        &self.info
    }

    async fn enroll<F: FnMut(EnrollProgress)>(
        &mut self,
        mut print: Print,
        mut on_progress: F,
    ) -> Result<Print> {
        let total_stages = self.info.enroll_stages;
        for completed_stages in 1..=total_stages {
            on_progress(EnrollProgress::new(completed_stages, total_stages));
        }
        print.template = Template::Raw(b"on-sensor handle".to_vec());
        print.driver = Some(self.info.driver.clone());
        print.device_stored = true;
        self.stored = Some(print.clone());
        Ok(print)
    }

    async fn verify_with_status<F: FnMut(FingerStatus)>(
        &mut self,
        enrolled: &Print,
        mut on_status: F,
    ) -> Result<VerifyOutcome> {
        on_status(FingerStatus::PRESENT); // report the finger the desktop prompts for
        Ok(VerifyOutcome::new(self.stored.as_ref() == Some(enrolled), None))
    }

    // The remaining operations are stubs here; a real backend talks to the sensor.
}

struct DemoBackend;

impl Backend for DemoBackend {
    type Device = Demo;

    async fn enumerate(&self) -> Result<Vec<Demo>> {
        Ok(vec![Demo {
            info: DeviceInfo::new(
                DeviceId::new("demo-0"),
                DriverId::new("demo"),
                "Demo Reader",
                ScanType::Press,
                DeviceFeature::VERIFY | DeviceFeature::STORAGE,
                3,
            ),
            stored: None,
        }])
    }

    async fn open(&self, id: &DeviceId) -> Result<Demo> {
        self.enumerate()
            .await?
            .into_iter()
            .find(|d| &d.info().id == id)
            .ok_or(Error::NotFound)
    }
}

block_on(async {
    let mut device = DemoBackend.open(&DeviceId::new("demo-0")).await.unwrap();
    device.open().await.unwrap();
    assert!(device.has_feature(DeviceFeature::STORAGE));
    assert!(device.info().features.is_match_on_chip());

    let mut seen = Vec::new();
    let print = device
        .enroll(Print::new_for_enroll(Finger::RightIndex), |p| seen.push(p.completed_stages))
        .await
        .unwrap();

    assert_eq!(seen, [1, 2, 3]);
    assert_eq!(print.finger, Some(Finger::RightIndex));
    assert!(print.is_compatible_with_driver(&DriverId::new("demo")));
    assert!(device.verify(&print).await.unwrap().matched);
});

Modules§

prelude
The names a backend or client reaches for most: the traits, the model, and the result types.

Structs§

DeviceFeature
Capability bit-flags, matching libfprint’s FpDeviceFeature (fp-device.h).
DeviceId
Stable identifier for a physical reader (opaque; assigned by the backend).
DeviceInfo
Static description of a device, known once it is discovered.
DriverId
Identifier of the driver a template is bound to (e.g. "goodixmoc"). Templates are driver-specific, so this is its own type rather than a bare String.
EnrollDate
Enrollment date (libfprint serializes this as a Julian-day int32; None ⇒ the G_MININT32 “unset” sentinel).
EnrollProgress
Progress report delivered during Device::enroll, once per capture attempt.
FingerStatus
Live finger-presence status (FpFingerStatusFlags), used to drive UI prompts.
IdentifyOutcome
Result of a 1:N Device::identify.
InvalidFinger
The error Finger::try_from returns for a byte outside the valid 0..=10 range.
Minutia
A single detected minutia (MINDTCT output / BOZORTH3 input).
Print
A fingerprint print: biometric Template plus the metadata libfprint serializes alongside it.
PrintBuilder
Builder for Print, one setter per field, terminated by build.
VerifyOutcome
Result of a 1:1 Device::verify.

Enums§

Error
Errors surfaced by Backend/Device operations.
Finger
A finger, matching libfprint’s FpFinger enum ordering (see fp-print.h).
InvalidEnrollDate
The error EnrollDate::try_new returns for a month outside 1..=12 or a day outside 1..=31, naming the offending field and value.
RetryReason
Why a scan needs to be retried (maps to fprintd enroll-*/verify-* retry strings).
ScanType
How a finger is presented to the sensor (FpScanType).
Temperature
Sensor thermal state (FpTemperature); some sensors throttle when warm/hot.
Template
The biometric payload of a print, matching libfprint’s FpiPrintType.

Traits§

Backend
A source of Devices — the entry point, analogous to libfprint’s FpContext.
Device
A physical fingerprint reader.

Type Aliases§

Result
Crate result alias.