### Libfprint Context Usage Example

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpContext.md

Demonstrates how to create an FpContext, connect to device-added and device-removed signals, start device enumeration, and run a main loop to process events.

```c
#include <libfprint/fprint.h>
#include <glib.h>

static void
on_device_added (FpContext *context, FpDevice *device)
{
  const gchar *name = fp_device_get_name (device);
  g_print ("Device added: %s\n", name);
}

static void
on_device_removed (FpContext *context, FpDevice *device)
{
  const gchar *name = fp_device_get_name (device);
  g_print ("Device removed: %s\n", name);
}

int main (void)
{
  FpContext *context = fp_context_new ();
  
  g_signal_connect (context, "device-added", 
                    G_CALLBACK (on_device_added), NULL);
  g_signal_connect (context, "device-removed",
                    G_CALLBACK (on_device_removed),
                    NULL);
  
  fp_context_enumerate (context);
  
  GMainLoop *loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);
  
  g_main_loop_unref (loop);
  g_object_unref (context);
  return 0;
}
```

--------------------------------

### Libfprint Usage Example (C)

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImage.md

Demonstrates a complete workflow for capturing a fingerprint image, detecting minutiae, and printing their coordinates. This example requires setting up a main loop to handle asynchronous operations.

```c
#include <libfprint/fprint.h>

static void
on_capture_complete (FpDevice *device, GAsyncResult *result, gpointer user_data)
{
  GError *error = NULL;
  FpImage *image = fp_device_capture_finish (device, result, &error);
  
  if (!error)
    {
      g_print ("Image captured: %ux%u @ %.2f ppmm\n",
               fp_image_get_width (image),
               fp_image_get_height (image),
               fp_image_get_ppmm (image));
    }
  else
    {
      g_print ("Capture failed: %s\n", error->message);
    }
}

static void
on_minutiae_detected (FpImage *image, GAsyncResult *result, gpointer user_data)
{
  GError *error = NULL;
  
  if (!fp_image_detect_minutiae_finish (image, result, &error))
    {
      g_print ("Minutiae detection failed: %s\n", error->message);
      return;
    }
  
  GPtrArray *minutiae = fp_image_get_minutiae (image);
  g_print ("Detected %u minutiae\n", minutiae->len);
  
  for (guint i = 0; i < minutiae->len; i++)
    {
      FpMinutia *min = g_ptr_array_index (minutiae, i);
      gint x, y;
      fp_minutia_get_coords (min, &x, &y);
      g_print ("  Minutia %u: (%d, %d)\n", i, x, y);
    }
}

int main (void)
{
  FpContext *context = fp_context_new ();
  fp_context_enumerate (context);
  
  GPtrArray *devices = fp_context_get_devices (context);
  FpDevice *device = g_ptr_array_index (devices, 0);
  
  // Open device and capture image
  fp_device_open (device, NULL, (GAsyncReadyCallback) on_open_complete, NULL);
  
  GMainLoop *loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);
  
  return 0;
}
```

--------------------------------

### Example FpImageDevice Driver Implementation

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImageDevice.md

A comprehensive example demonstrating the structure and required functions for implementing a custom FpImageDevice driver. This includes probe, open, close, activate, and deactivate methods, along with device identification and feature definitions.

```c
#include "libfprint/drivers_api.h"

static void
probe (FpDevice *device)
{
  // Validate device supports image capture
  fpi_device_probe_complete (device, "device-id", "Device Name", NULL);
}

static void
open (FpDevice *device)
{
  FpImageDevice *img_device = FP_IMAGE_DEVICE (device);
  
  // Initialize device for image capture
  // ...
  
  fpi_device_open_complete (device, NULL);
}

static void
close (FpDevice *device)
{
  // Shut down image capture
  // ...
  
  fpi_device_close_complete (device, NULL);
}

static void
activate (FpImageDevice *device)
{
  // Start image capture loop
  // When image available, call:
  // fpi_device_image_capture_complete (FPI_IMAGE_DEVICE (device),
  //                                    image, error);
}

static void
deactivate (FpImageDevice *device)
{
  // Stop image capture loop
}

static const FpIdEntry entries[] = {
  { .vid = 0x1234, .pid = 0x5678 },
  { .vid = 0, .pid = 0 },  // Terminator
};

static FpDeviceClass device_class = {
  .id = "example_imager",
  .full_name = "Example Fingerprint Imager",
  .type = FP_DEVICE_TYPE_USB,
  .id_table = entries,
  .features = FP_DEVICE_FEATURE_CAPTURE | FP_DEVICE_FEATURE_VERIFY |
              FP_DEVICE_FEATURE_IDENTIFY | FP_DEVICE_FEATURE_ENROLL,
  .nr_enroll_stages = 5,
  .scan_type = FP_SCAN_TYPE_PRESS,
  .probe = probe,
  .open = open,
  .close = close,
};

static FpImageDeviceClass image_device_class = {
  .parent_class = &device_class,
  .activate = activate,
  .deactivate = deactivate,
};
```

--------------------------------

### FpPrint Usage Example

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpPrint.md

This example demonstrates the complete lifecycle of an FpPrint object: creating a new print, setting finger, username, and description, serializing it to data, saving to a file, and then restoring it from the file. Ensure libfprint and GIO are properly linked.

```c
#include <libfprint/fprint.h>
#include <gio/gio.h>

int main (void)
{
  FpContext *context = fp_context_new ();
  fp_context_enumerate (context);
  
  GPtrArray *devices = fp_context_get_devices (context);
  FpDevice *device = g_ptr_array_index (devices, 0);
  
  // Create a new print for the device
  FpPrint *print = fp_print_new (device);
  fp_print_set_finger (print, FP_FINGER_RIGHT_INDEX);
  fp_print_set_username (print, "john_doe");
  fp_print_set_description (print, "Work laptop right index");
  
  // Serialize for storage
  guchar *data = NULL;
  gsize length = 0;
  GError *error = NULL;
  
  if (!fp_print_serialize (print, &data, &length, &error))
    {
      g_print ("Serialization failed: %s\n", error->message);
      return 1;
    }
  
  // Save to file
  g_file_set_contents ("fingerprint.dat", (gchar *)data, length, &error);
  g_free (data);
  
  // Later: restore from file
  gchar *file_data = NULL;
  gsize file_length = 0;
  g_file_get_contents ("fingerprint.dat", &file_data, &file_length, &error);
  
  FpPrint *restored = fp_print_deserialize ((guchar *)file_data, file_length, &error);
  g_free (file_data);
  
  if (restored)
    {
      g_print ("Restored print for finger: %d\n", fp_print_get_finger (restored));
      g_object_unref (restored);
    }
  
  g_object_unref (print);
  g_object_unref (context);
  return 0;
}

```

--------------------------------

### Device Enumeration Pattern

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Example demonstrating how to enumerate fingerprint devices using `fp_context_new`, `g_signal_connect` for device-added signals, and `fp_context_enumerate` to start the enumeration process. It also shows how to run a main loop to process events.

```APIDOC
## Device Enumeration

```c
FpContext *ctx = fp_context_new ();
g_signal_connect (ctx, "device-added", G_CALLBACK (on_added), NULL);
fp_context_enumerate (ctx);
GMainLoop *loop = g_main_loop_new (NULL, FALSE);
g_main_loop_run (loop);
```
```

--------------------------------

### Start State Machine Execution

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Starts the execution of a state machine. A callback function can be provided to be notified when the state machine completes.

```c
void fpi_ssm_start (FpiSsm                 *ssm,
                    FpiSsmCompletedCallback callback);
```

--------------------------------

### Serialization Pattern

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Example of serializing a fingerprint print into a byte array using `fp_print_serialize`. It shows how to get the serialized data and length, and then save it to a file using `g_file_set_contents`.

```APIDOC
## Serialization

```c
guchar *data = NULL;
gsize length = 0;
fp_print_serialize (print, &data, &length, NULL);
g_file_set_contents ("print.dat", (gchar *)data, length, NULL);
g_free (data);
```
```

--------------------------------

### fpi_ssm_start

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Starts the execution of a state machine. The provided callback will be invoked when the state machine completes its execution.

```APIDOC
## fpi_ssm_start()

### Description
Starts state machine execution.

### Parameters
- `ssm` (FpiSsm *) - The state machine to start.
- `callback` (FpiSsmCompletedCallback) - Callback function to be invoked upon completion.
```

--------------------------------

### Libfprint Device Usage Example

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Demonstrates how to initialize libfprint, enumerate devices, open a device, and handle asynchronous enrollment callbacks. Requires GObject and GLib event loop.

```c
#include <libfprint/fprint.h>

static void
on_enroll_progress (FpDevice *device, gint completed_stages, FpPrint *print,
                    gpointer user_data, GError *error)
{
  if (error)
    g_print ("Scan failed, retry: %s\n", error->message);
  else
    g_print ("Stage %d/%d complete\n", completed_stages,
             fp_device_get_nr_enroll_stages (device));
}

static void
on_enroll_complete (FpDevice *device, GAsyncResult *result, gpointer user_data)
{
  GError *error = NULL;
  FpPrint *print = fp_device_enroll_finish (device, result, &error);
  
  if (!error)
    g_print ("Enrollment successful\n");
  else
    g_print ("Enrollment failed: %s\n", error->message);
}

int main (void)
{
  FpContext *context = fp_context_new ();
  fp_context_enumerate (context);
  
  GPtrArray *devices = fp_context_get_devices (context);
  if (devices->len == 0)
    {
      g_print ("No devices found\n");
      return 1;
    }
  
  FpDevice *device = g_ptr_array_index (devices, 0);
  
  fp_device_open (device, NULL, (GAsyncReadyCallback) on_open_complete, NULL);
  
  GMainLoop *loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);
  
  return 0;
}

```

--------------------------------

### Enrollment Progress Callback in C

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Provides an example of an enrollment progress callback function. This callback is invoked at each stage of a multi-stage enrollment process, allowing for user feedback on progress.

```c
gint stages = fp_device_get_nr_enroll_stages (device);
// e.g., 5 stages means 5 scans required

// Enroll progress callback reports stage by stage:
static void on_progress (FpDevice *device, gint completed_stages, FpPrint *print,
                         gpointer data, GError *error)
{
  gint total = fp_device_get_nr_enroll_stages (device);
  g_print ("Stage %d of %d\n", completed_stages, total);
}
```

--------------------------------

### Create Context and Enumerate Devices

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Initialize an FpContext, connect to device-added and device-removed signals, and enumerate available fingerprint devices. A GMainLoop is then started to process events.

```c
FpContext *context = fp_context_new ();
g_signal_connect (context, "device-added", G_CALLBACK (on_device_added), NULL);
g_signal_connect (context, "device-removed", G_CALLBACK (on_device_removed), NULL);
fp_context_enumerate (context);

GMainLoop *loop = g_main_loop_new (NULL, FALSE);
g_main_loop_run (loop);
```

--------------------------------

### Device Enumeration with Callbacks

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Demonstrates how to enumerate fingerprint devices and connect to the 'device-added' signal for asynchronous handling. A GMainLoop is started to process events.

```c
FpContext *ctx = fp_context_new ();
g_signal_connect (ctx, "device-added", G_CALLBACK (on_added), NULL);
fp_context_enumerate (ctx);
GMainLoop *loop = g_main_loop_new (NULL, FALSE);
g_main_loop_run (loop);
```

--------------------------------

### fp_context_enumerate

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpContext.md

Starts the asynchronous enumeration of fingerprint devices connected to the system. Device discovery events are reported via signals.

```APIDOC
## fp_context_enumerate

### Description
Starts the asynchronous enumeration of fingerprint devices connected to the system. Discovered devices are reported via the `device-added` signal. It is recommended to connect to signals before calling this method.

### Method
`void fp_context_enumerate (FpContext *context);`

### Parameters
#### Path Parameters
- **context** (FpContext *) - Required - The context instance to use for enumeration.
```

--------------------------------

### Feature Check Pattern

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Example showing how to check if a device supports a specific feature, such as `FP_DEVICE_FEATURE_IDENTIFY`, using `fp_device_has_feature` before attempting to use related functions.

```APIDOC
## Feature Check

```c
if (fp_device_has_feature (device, FP_DEVICE_FEATURE_IDENTIFY))
  {
    // Safe to call fp_device_identify()
  }
```
```

--------------------------------

### Start Fingerprint Device Enumeration

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpContext.md

Initiates the asynchronous discovery of fingerprint devices. Device notifications are reported via the 'device-added' signal.

```c
void fp_context_enumerate (FpContext *context);
```

--------------------------------

### Verification Process

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Starts the fingerprint verification process against a stored print. It uses callbacks to report match results and completion status.

```c
FpPrint *stored = load_stored_print ();
fp_device_verify (device, stored, NULL, on_match, NULL, NULL,
                  on_complete, NULL);
```

--------------------------------

### FpiSsm Functions

Source: https://github.com/libfprint/libfprint/blob/master/doc/libfprint-2-sections.txt

Functions for managing state machine (SSM) instances, including creation, starting, state transitions, and data handling.

```APIDOC
## FpiSsm Functions

### Description
Functions for managing Finite State Machines (FSMs) or State Machine Managers (SSMs). This includes creating and freeing SSM instances, starting and managing states, handling state transitions (immediate and delayed), cancelling transitions, marking completion or failure, and setting/getting data associated with the SSM. It also provides callbacks for SPI and USB transfers.

### Functions
- `fpi_ssm_new()`
- `fpi_ssm_new_full(FpiSsmHandlerCallback handler, FpiSsmCompletedCallback completed, void *user_data)`
- `fpi_ssm_free(FpiSsm *ssm)`
- `fpi_ssm_start(FpiSsm *ssm)`
- `fpi_ssm_start_subsm(FpiSsm *ssm, FpiSsm *subsm)`
- `fpi_ssm_next_state(FpiSsm *ssm)`
- `fpi_ssm_next_state_delayed(FpiSsm *ssm, guint milliseconds)`
- `fpi_ssm_jump_to_state(FpiSsm *ssm, FpiSsmState state)`
- `fpi_ssm_jump_to_state_delayed(FpiSsm *ssm, FpiSsmState state, guint milliseconds)`
- `fpi_ssm_cancel_delayed_state_change(FpiSsm *ssm)`
- `fpi_ssm_mark_completed(FpiSsm *ssm)`
- `fpi_ssm_mark_failed(FpiSsm *ssm, int error_code)`
- `fpi_ssm_set_data(FpiSsm *ssm, void *data)`
- `fpi_ssm_get_data(FpiSsm *ssm)`
- `fpi_ssm_get_device(FpiSsm *ssm)`
- `fpi_ssm_get_error(FpiSsm *ssm)`
- `fpi_ssm_dup_error(FpiSsm *ssm)`
- `fpi_ssm_get_cur_state(FpiSsm *ssm)`
- `fpi_ssm_silence_debug(FpiSsm *ssm)`
- `fpi_ssm_spi_transfer_cb(FpiSsm *ssm, int result)`
- `fpi_ssm_spi_transfer_with_weak_pointer_cb(FpiSsm *ssm, int result)`
- `fpi_ssm_usb_transfer_cb(FpiSsm *ssm, int result)`
- `fpi_ssm_usb_transfer_with_weak_pointer_cb(FpiSsm *ssm, int result)`
```

--------------------------------

### Verification Pattern

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Example of fingerprint verification using `load_stored_print` to retrieve a stored print and `fp_device_verify` to perform the verification against the device. It includes callbacks for match results and completion.

```APIDOC
## Verification

```c
FpPrint *stored = load_stored_print ();
fp_device_verify (device, stored, NULL, on_match, NULL, NULL,
                  on_complete, NULL);
```
```

--------------------------------

### Deserialization Pattern

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Example of deserializing a fingerprint print from a file using `g_file_get_contents` to read the data, and then `fp_print_deserialize` to reconstruct the `FpPrint` object from the byte array.

```APIDOC
## Deserialization

```c
gchar *data = NULL;
gsize length = 0;
g_file_get_contents ("print.dat", &data, &length, NULL);
FpPrint *print = fp_print_deserialize ((guchar *)data, length, NULL);
g_free (data);
```
```

--------------------------------

### Initialize and Use libfprint

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/START_HERE.md

This snippet demonstrates the basic workflow for using libfprint in an application. It covers context creation, device enumeration, opening a device, and initiating enrollment, verification, or identification processes.

```c
#include <libfprint/fprint.h>

// Create context and enumerate devices
FpContext *ctx = fp_context_new();
fp_context_enumerate(ctx);
FpDevice *dev = g_ptr_array_index(fp_context_get_devices(ctx), 0);

// Open device
fp_device_open(dev, NULL, on_open_done, NULL);

// Enroll (multiple stages)
FpPrint *template = fp_print_new(dev);
fp_device_enroll(dev, template, NULL, on_progress, NULL, NULL, on_enroll_done, NULL);

// Verify
fp_device_verify(dev, loaded_print, NULL, on_match, NULL, NULL, on_verify_done, NULL);

// Identify (1:N)
fp_device_identify(dev, print_list, NULL, on_match, NULL, NULL, on_identify_done, NULL);
```

--------------------------------

### Enrollment Pattern

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Demonstrates the process of fingerprint enrollment using `fp_print_new`, `fp_print_set_finger`, `fp_print_set_username`, and `fp_device_enroll`. It shows how to set up the print template and initiate the enrollment process with callbacks.

```APIDOC
## Enrollment

```c
FpPrint *template = fp_print_new (device);
fp_print_set_finger (template, FP_FINGER_RIGHT_INDEX);
fp_print_set_username (template, "alice");
fp_device_enroll (device, template, NULL, on_progress, NULL, NULL,
                  on_complete, NULL);
```
```

--------------------------------

### Compile with Meson

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Set up a Meson build for your C application, specifying libfprint as a dependency.

```meson
project('myapp', 'c')
libfprint = dependency('libfprint-2')
executable('myapp', 'myapp.c', dependencies: libfprint)
```

--------------------------------

### Get Finger Status

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves the current status of the finger on the scanner.

```c
FpFingerStatusFlags fp_device_get_finger_status (FpDevice *device);
```

--------------------------------

### Create Driver Test with `umockdev`

Source: https://github.com/libfprint/libfprint/blob/master/tests/README.md

Use this command to create a test case for a specific driver, optionally specifying a variant. Run as root from the build directory.

```shell
$ sudo tests/create-driver-test.py driver [variant]
```

--------------------------------

### Get Device Name

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves a human-readable name for the fingerprint device.

```c
const gchar *fp_device_get_name (FpDevice *device);
```

--------------------------------

### Get Driver Name

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves the driver name of the fingerprint device.

```c
const gchar *fp_device_get_driver (FpDevice *device);
```

--------------------------------

### Get Device Temperature

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves the current thermal state of the fingerprint device.

```c
FpTemperature fp_device_get_temperature (FpDevice *device);
```

--------------------------------

### Get Device ID

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves the unique identifier string for the fingerprint device.

```c
const gchar *fp_device_get_device_id (FpDevice *device);
```

--------------------------------

### Compile C program with libfprint

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/INDEX.md

Use pkg-config to automatically fetch the necessary compiler and linker flags for libfprint.

```bash
gcc prog.c -o prog $(pkg-config --cflags --libs libfprint-2)
```

--------------------------------

### Get Device Features

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves a bitmask representing the supported features of the fingerprint device.

```c
FpDeviceFeature fp_device_get_features (FpDevice *device);
```

--------------------------------

### Get Number of Enrollment Stages

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves the number of capture stages required for fingerprint enrollment.

```c
gint fp_device_get_nr_enroll_stages (FpDevice *device);
```

--------------------------------

### Initialize libfprint Core Objects

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/INDEX.md

Instantiate the core objects required for libfprint operations: context, device, print, and image.

```c
FpContext *ctx = fp_context_new();
FpDevice *dev = /* from context */;
FpPrint *print = fp_print_new(dev);
FpImage *img = fp_image_new(width, height);
```

--------------------------------

### Get Scan Type

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Retrieves the required scan method for the fingerprint device (swipe or press).

```c
FpScanType fp_device_get_scan_type (FpDevice *device);
```

--------------------------------

### Enroll a Fingerprint

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Initiate the fingerprint enrollment process. This involves creating an FpPrint object, setting the finger and username, and then calling fp_device_enroll. Callbacks for progress and completion are provided.

```c
FpPrint *template = fp_print_new (device);
fp_print_set_finger (template, FP_FINGER_RIGHT_INDEX);
fp_print_set_username (template, "alice");

fp_device_enroll (device, template, NULL, on_progress, NULL, NULL,
                  on_enroll_complete, NULL);
```

```c
// In progress callback:
static void on_progress (FpDevice *dev, gint stages, FpPrint *print,
                         gpointer data, GError *error)
{
  if (error && error->domain == FP_DEVICE_RETRY)
    g_print ("Scan failed; retry: %s\n", error->message);
  else if (!error)
    g_print ("Stage %d/%d complete\n", stages,
             fp_device_get_nr_enroll_stages (dev));
}
```

```c
// In completion callback:
static void on_enroll_complete (FpDevice *dev, GAsyncResult *result,
                                gpointer data)
{
  GError *error = NULL;
  FpPrint *print = fp_device_enroll_finish (dev, result, &error);
  if (!error)
    g_print ("Enrollment successful\n");
}
```

--------------------------------

### Open a Fingerprint Device

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Select the first available device from the context and attempt to open it. The on_open_complete callback will be invoked upon completion.

```c
FpDevice *device = g_ptr_array_index (fp_context_get_devices (context), 0);
fp_device_open (device, NULL, on_open_complete, NULL);
```

--------------------------------

### Get Cancellable Object

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Returns the GCancellable object associated with the current operation on the device. This object can be used to request cancellation.

```c
GCancellable *fpi_device_get_cancellable (FpDevice *device);
```

--------------------------------

### Get FpImage Height

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImage.md

Retrieves the height of the fingerprint image in pixels. This is a property query method for an existing FpImage object.

```c
guint fp_image_get_height (FpImage *self);
```

--------------------------------

### fpi_device_open_complete

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Called by `open()` callback when the device is ready or if an error occurred during the opening process.

```APIDOC
## fpi_device_open_complete

### Description
Called by `open()` callback when device is ready or error occurred.

### Parameters
#### Path Parameters
- **device** (FpDevice*) - Description not provided
- **error** (GError*) - Optional - Description not provided
```

--------------------------------

### Get FpImage Width

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImage.md

Retrieves the width of the fingerprint image in pixels. This is a property query method for an existing FpImage object.

```c
guint fp_image_get_width (FpImage *self);
```

--------------------------------

### open()

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Opens the device for operations. Called when the user calls `fp_device_open()`.

```APIDOC
## open() callback

### Description
Opens the device for operations. Called when user calls `fp_device_open()`.

### Responsibilities:
- Acquire device resources (USB handle, file descriptor, etc.)
- Initialize device state
- Call `fpi_device_open_complete()` on success/error

### Called:
Once per device open

### Threading:
GLib main loop context
```

--------------------------------

### Checking Print Compatibility in C

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Illustrates how to verify if a loaded fingerprint print is compatible with the current device. This is crucial because prints are device-specific and may not work across different hardware or drivers.

```c
FpPrint *loaded_print = fp_print_deserialize (data, len, NULL);

if (!fp_print_compatible (loaded_print, device))
  {
    g_print ("Print is from a different device/driver\n");
  }
```

--------------------------------

### Enrollment Process

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Initiates the fingerprint enrollment process for a given device. It sets the finger and username for the print template and uses callbacks for progress and completion.

```c
FpPrint *template = fp_print_new (device);
fp_print_set_finger (template, FP_FINGER_RIGHT_INDEX);
fp_print_set_username (template, "alice");
fp_device_enroll (device, template, NULL, on_progress, NULL, NULL,
                  on_complete, NULL);
```

--------------------------------

### FpDevice Functions

Source: https://github.com/libfprint/libfprint/blob/master/doc/libfprint-2-sections.txt

Functions for managing fingerprint devices, including getting device information, handling actions, and managing device state.

```APIDOC
## FpDevice Functions

### Description
Functions for interacting with fingerprint devices. This includes retrieving USB and udev data, managing device actions, retrying operations, handling errors, and reporting completion status for various device operations like enrollment, verification, and capture.

### Functions
- `fpi_device_get_usb_device(FpDevice *device)`
- `fpi_device_get_udev_data(FpDevice *device)`
- `fpi_device_get_virtual_env(FpDevice *device)`
- `fpi_device_get_current_action(FpDevice *device)`
- `fpi_device_retry_new(FpDevice *device, FpTimeoutFunc callback, void *user_data)`
- `fpi_device_error_new(FpDevice *device, int error_code, const char *msg)`
- `fpi_device_retry_new_msg(FpDevice *device, FpTimeoutFunc callback, void *user_data, const char *msg)`
- `fpi_device_emulation_mode_enabled(FpDevice *device)`
- `fpi_device_error_new_msg(FpDevice *device, int error_code, const char *msg)`
- `fpi_device_get_driver_data(FpDevice *device)`
- `fpi_device_get_enroll_data(FpDevice *device)`
- `fpi_device_get_capture_data(FpDevice *device)`
- `fpi_device_get_verify_data(FpDevice *device)`
- `fpi_device_get_identify_data(FpDevice *device)`
- `fpi_device_get_delete_data(FpDevice *device)`
- `fpi_device_get_cancellable(FpDevice *device)`
- `fpi_device_action_is_cancelled(FpDevice *device)`
- `fpi_device_add_timeout(FpDevice *device, guint milliseconds, FpTimeoutFunc callback, gpointer user_data, GDestroyNotify destroy_notify)`
- `fpi_device_set_nr_enroll_stages(FpDevice *device, guint nr_stages)`
- `fpi_device_set_scan_type(FpDevice *device, FpiScanType scan_type)`
- `fpi_device_update_features(FpDevice *device)`
- `fpi_device_critical_enter(FpDevice *device)`
- `fpi_device_critical_leave(FpDevice *device)`
- `fpi_device_remove(FpDevice *device)`
- `fpi_device_report_finger_status(FpDevice *device, FpiFingerStatus status)`
- `fpi_device_report_finger_status_changes(FpDevice *device, GHashTable *changes)`
- `fpi_device_action_error(FpDevice *device, FpiDeviceAction action, int error_code, const char *msg)`
- `fpi_device_probe_complete(FpDevice *device)`
- `fpi_device_open_complete(FpDevice *device)`
- `fpi_device_close_complete(FpDevice *device)`
- `fpi_device_enroll_complete(FpDevice *device)`
- `fpi_device_verify_complete(FpDevice *device)`
- `fpi_device_identify_complete(FpDevice *device)`
- `fpi_device_capture_complete(FpDevice *device)`
- `fpi_device_clear_storage_complete(FpDevice *device)`
- `fpi_device_delete_complete(FpDevice *device)`
- `fpi_device_list_complete(FpDevice *device)`
- `fpi_device_suspend_complete(FpDevice *device)`
- `fpi_device_resume_complete(FpDevice *device)`
- `fpi_device_enroll_progress(FpDevice *device, guint stage, guint progress)`
- `fpi_device_verify_report(FpDevice *device, guint match_percentage)`
- `fpi_device_identify_report(FpDevice *device, guint match_percentage)`
- `fpi_device_class_auto_initialize_features(FpDeviceClass *device_class)`
```

--------------------------------

### fp_device_open

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Opens the device for operations. Must be called before other operations.

```APIDOC
## fp_device_open

### Description
Opens the device for operations. Must be called before other operations.

### Parameters
#### Path Parameters
- **device** (FpDevice *) - Required - The device to open
- **cancellable** (GCancellable *) - Optional - Cancellation object
- **callback** (GAsyncReadyCallback) - Required - Completion callback
- **user_data** (gpointer) - Optional - Callback user data

### Returns
`gboolean` — TRUE on success, FALSE on error

## fp_device_open_finish

### Description
Completes the asynchronous open operation.

### Parameters
#### Path Parameters
- **device** (FpDevice *) - Required - The device to open
- **result** (GAsyncResult *) - Required - The asynchronous result
- **error** (GError **) - Optional - Error information

### Returns
`gboolean` — TRUE on success, FALSE on error
```

--------------------------------

### Enroll Fingerprint Asynchronously

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Performs fingerprint enrollment by capturing multiple scans to create a template. It accepts a progress callback for real-time feedback and a completion callback for the final result. Ensure the template_print is initialized before calling.

```c
void fp_device_enroll (FpDevice           *device,
                       FpPrint            *template_print,
                       GCancellable       *cancellable,
                       FpEnrollProgress    progress_cb,
                       gpointer            progress_data,
                       GDestroyNotify      progress_destroy,
                       GAsyncReadyCallback callback,
                       gpointer            user_data);

FpPrint * fp_device_enroll_finish (FpDevice     *device,
                                   GAsyncResult *result,
                                   GError      **error);
```

--------------------------------

### Driver Enroll Callback

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Performs fingerprint enrollment by capturing multiple scans. It loops until `nr_enroll_stages` are complete, reporting progress with `fpi_device_enroll_progress()` and finishing with `fpi_device_enroll_complete()`.

```c
void (*enroll) (FpDevice *device);
```

--------------------------------

### Get Driver-Specific Data

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Retrieves driver-specific data associated with the ID table entry for the device. This data is unique to the device's driver implementation.

```c
guint64 fpi_device_get_driver_data (FpDevice *device);
```

--------------------------------

### Get FpImage Resolution (PPMm)

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImage.md

Returns the image resolution in pixels per millimeter. This value is crucial for accurate minutiae extraction and matching processes.

```c
gdouble fp_image_get_ppmm (FpImage *self);
```

--------------------------------

### Compile Application with libfprint

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Compile a C application using GCC, linking against the libfprint library. Uses pkg-config to automatically determine the necessary compiler and linker flags.

```bash
gcc -o myapp myapp.c $(pkg-config --cflags --libs libfprint-2)
```

--------------------------------

### Compile with CMake

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Configure your CMake build to find and link against the libfprint library.

```cmake
find_package(libfprint REQUIRED)
add_executable(myapp myapp.c)
target_link_libraries(myapp libfprint)
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Use environment variables to enable detailed debug logging for libfprint and GLib.

```bash
G_MESSAGES_DEBUG=all        # Enable debug logging
FP_DEBUG=1                  # Enable libfprint debugging
LIBFPRINT_EMULATE_DEVICE=1  # Use virtual test device
```

--------------------------------

### API Reference Document Structure

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/MANIFEST.md

Describes the consistent structure followed by each API reference document, including overview, enumerations, constructors, methods, and usage examples.

```APIDOC
## API Reference Document Structure

Each API reference document follows this pattern:

1. **Overview** — What the type/function does and where it's defined
2. **Enumerations/Types** — All related enums with value tables
3. **Constructors/Creators** — How to create instances
4. **Methods/Functions** — Complete function documentation with:
   - Full C signature as code block
   - Parameters table (name | type | required | default | description)
   - Return type and meaning
   - Error conditions (where applicable)
   - Source file and line reference
5. **Usage Examples** — Realistic code examples showing patterns
6. **Related Types** — Cross-references to related documentation
```

--------------------------------

### Create Sequential State Machine

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Creates a sequential state machine for managing multi-step operations. The handler callback is invoked for each state transition. Specify the total number of states when creating the machine.

```c
FpiSsm *fpi_ssm_new (FpDevice             *dev,
                     FpiSsmHandlerCallback handler,
                     int                   nr_states);
```

--------------------------------

### Driver Open Callback

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Opens the device for operations when `fp_device_open()` is called. Responsibilities include acquiring device resources and initializing device state, followed by a call to `fpi_device_open_complete()`.

```c
void (*open) (FpDevice *device);
```

--------------------------------

### Get Current Device Action

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Retrieves the current active operation of the fingerprint device. Use this to determine the device's state (e.g., probing, enrolling, verifying).

```c
FpiDeviceAction fpi_device_get_current_action (FpDevice *device);
```

--------------------------------

### Define FpContext Type

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/types.md

Defines the main context for device enumeration and management. Extends GObject.

```c
typedef struct _FpContext FpContext;
G_DECLARE_DERIVABLE_TYPE (FpContext, fp_context, FP, CONTEXT, GObject)
```

--------------------------------

### Enroll Fingerprint with libfprint

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/INDEX.md

Initiate the fingerprint enrollment process. Requires a template and a callback for progress updates.

```c
fp_device_enroll(dev, tmpl, NULL, cb, ...);  // Enroll
```

--------------------------------

### Get Minutia Coordinates (C)

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImage.md

Retrieves the X and Y coordinates of a given minutia point. This function is useful when processing detected minutiae to determine their exact location on the fingerprint image.

```c
void fp_minutia_get_coords (FpMinutia *min,
                            gint      *x,
                            gint      *y);
```

--------------------------------

### Get Currently Known Fingerprint Devices

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpContext.md

Retrieves an array of all fingerprint devices currently known to the context. For a complete list, call fp_context_enumerate() first. The returned array is owned by the context and should not be freed.

```c
GPtrArray *fp_context_get_devices (FpContext *context);
```

--------------------------------

### fpi_device_enroll_complete

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Called by the `enroll()` callback with the final fingerprint print data or an error if enrollment failed.

```APIDOC
## fpi_device_enroll_complete

### Description
Called by `enroll()` callback with final print or error.

### Parameters
#### Path Parameters
- **device** (FpDevice*) - Description not provided
- **print** (FpPrint*) - Optional - Description not provided
- **error** (GError*) - Optional - Description not provided
```

--------------------------------

### Serializing and Deserializing Fingerprint Prints in C

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Demonstrates the process of serializing a fingerprint print into a binary format for storage and deserializing it back into an FpPrint object. This is essential for saving and loading fingerprint data.

```c
// Serialize for storage
guchar *data = NULL;
gsize length = 0;
if (fp_print_serialize (print, &data, &length, &error))
  {
    // data contains binary representation, length is size in bytes
    // Store to file or database
    g_free (data);
  }

// Deserialize from storage
FpPrint *restored = fp_print_deserialize (stored_data, stored_length, &error);
```

--------------------------------

### GObject Memory Management with libfprint

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

Demonstrates manual reference counting for GObjects using g_object_ref and g_object_unref, and automatic cleanup with g_autoptr.

```c
FpContext *ctx = fp_context_new ();     // refcount = 1
g_object_ref (ctx);                     // refcount = 2
g_object_unref (ctx);                   // refcount = 1
g_object_unref (ctx);                   // freed

// Or with autocleanup:
g_autoptr(FpContext) ctx = fp_context_new ();
// Automatically unreffed at scope exit
```

--------------------------------

### Driver List Callback

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Lists prints stored on the device if it supports the `STORAGE_LIST` feature. It queries device storage, creates `FpPrint` objects, and completes with a `GPtrArray` of prints via `fpi_device_list_complete()`.

```c
void (*list) (FpDevice *device);
```

--------------------------------

### enroll()

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Performs fingerprint enrollment, capturing multiple scans into a template.

```APIDOC
## enroll() callback

### Description
Performs fingerprint enrollment (capturing multiple scans into a template).

### Responsibilities:
- Loop to capture scans until `nr_enroll_stages` complete
- Call `fpi_device_enroll_progress()` after each scan
- Call `fpi_device_enroll_complete()` with final print or error

### Progress reporting:
- Call `fpi_device_enroll_progress()` after each scan attempt
- Pass scan quality/retry code via GError parameter if scan fails
- Pass captured print if available

### Called:
Once per enrollment operation

### Cancellation:
Check `fpi_device_action_is_cancelled()` in loops
```

--------------------------------

### Checking Device Features in C

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Shows how to check if a device supports specific features before attempting to use them. This prevents errors by ensuring the device capabilities match the intended operation.

```c
if (fp_device_has_feature (device, FP_DEVICE_FEATURE_IDENTIFY))
  {
    // Safe to call fp_device_identify()
  }

if (fp_device_has_feature (device, FP_DEVICE_FEATURE_STORAGE))
  {
    // Device has persistent storage
  }
```

--------------------------------

### FpImageDevice Class Callbacks

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImageDevice.md

Image device drivers typically implement these callbacks to manage the image capture lifecycle.

```APIDOC
## FpImageDeviceClass Callbacks

Drivers implement the following callbacks:

```c
struct _FpImageDeviceClass
{
  FpDeviceClass parent_class;

  // These are typically implemented by image drivers:
  void (*open)    (FpImageDevice *device);
  void (*close)   (FpImageDevice *device);
  void (*activate) (FpImageDevice *device);
  void (*deactivate) (FpImageDevice *device);
};
```

### activate()

Starts image capture loop when enrollment/verify/identify starts.

### deactivate()

Stops image capture loop when operation completes.
```

--------------------------------

### list()

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Lists prints stored on the device, if the device has the STORAGE_LIST feature.

```APIDOC
## list() callback

### Description
Lists prints stored on device (if device has STORAGE_LIST feature).

### Responsibilities:
- Query device storage
- Create FpPrint objects for each stored print
- Call `fpi_device_list_complete()` with GPtrArray of prints

### Called:
Once per list operation
```

--------------------------------

### Asynchronous Operation Pattern in C

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Demonstrates the standard pattern for handling asynchronous device operations in libfprint. This involves initiating an operation, providing a callback for completion, and then finishing the operation to retrieve results or errors.

```c
fp_device_open (device, cancellable, on_open_complete, user_data);

static void on_open_complete (FpDevice *device, GAsyncResult *result,
                              gpointer user_data)
{
  GError *error = NULL;
  gboolean success = fp_device_open_finish (device, result, &error);
  if (!error)
    g_print ("Device opened\n");
}
```

--------------------------------

### fpi_device_list_complete

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Called by the `list()` callback with an array of `FpPrint` objects representing the stored fingerprints, or an error if the listing failed.

```APIDOC
## fpi_device_list_complete

### Description
Called by `list()` callback with array of FpPrint objects.

### Parameters
#### Path Parameters
- **device** (FpDevice*) - Description not provided
- **prints** (GPtrArray*) - Optional - Array of FpPrint objects
- **error** (GError*) - Optional - Description not provided
```

--------------------------------

### Handling FP_DEVICE_RETRY Errors in C

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/README.md

Demonstrates how to check for and handle transient scan failures indicated by the FP_DEVICE_RETRY error domain. This allows the application to prompt the user to retry the operation.

```c
if (error && error->domain == FP_DEVICE_RETRY)
  {
    FpDeviceRetry code = (FpDeviceRetry)error->code;
    // Suggest appropriate retry message based on code
  }
```

--------------------------------

### suspend() / resume()

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Handles system sleep/wake events for the device, if supported.

```APIDOC
## suspend() / resume() callbacks

### Description
Handles system sleep/wake (optional).

### Responsibilities:
- `suspend()`: Save device state, prepare for power loss
- `resume()`: Restore state, reinitialize if needed

### Called:
On system suspend/resume during active operation
```

--------------------------------

### fpi_ssm_new

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Creates a sequential state machine for multi-step operations. This is used to simplify the implementation of complex, multi-step device protocols.

```APIDOC
## fpi_ssm_new()

### Description
Creates a sequential state machine for multi-step operations.

### Parameters
- `dev` (FpDevice *) - The fingerprint device.
- `handler` (FpiSsmHandlerCallback) - Callback called for each state transition.
- `nr_states` (int) - Number of states in the machine.

### Returns
FpiSsm *
A pointer to the newly created state machine.

### Used for
Simplifying multi-step protocol sequences.
```

--------------------------------

### Create New FpPrint

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpPrint.md

Creates a new print template associated with a specific device. The returned object must be freed with g_object_unref().

```c
FpPrint *fp_print_new (FpDevice *device);
```

--------------------------------

### FpContext - Device Enumeration

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/INDEX.md

The FpContext object is the main entry point for fingerprint device management. It is used to discover and enumerate devices connected to the system.

```APIDOC
## FpContext

### Description
Main entry point for fingerprint device management. Use to discover and enumerate devices.

### Key Methods
- `fp_context_new()`: Create context
- `fp_context_enumerate()`: Discover devices
- `fp_context_get_devices()`: Get device list

### Signals
- `device-added`: New device discovered
- `device-removed`: Device removed

### See Also
- [FpContext API Reference](FpContext.md)
```

--------------------------------

### FpImageDeviceClass Structure

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpImageDevice.md

Defines the class structure for image device drivers, including essential callbacks like open, close, activate, and deactivate.

```c
struct _FpImageDeviceClass
{
  FpDeviceClass parent_class;

  // These are typically implemented by image drivers:
  void (*open)    (FpImageDevice *device);
  void (*close)   (FpImageDevice *device);
  void (*activate) (FpImageDevice *device);
  void (*deactivate) (FpImageDevice *device);
};
```

--------------------------------

### probe()

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/driver-api.md

Called when a new device matching the driver's ID table is discovered. The driver should validate the device and set its properties.

```APIDOC
## probe() callback

### Description
Called when a new device matching the driver's ID table is discovered. Driver should validate the device and set its properties.

### Responsibilities:
- Validate device is actually supported (may require partial USB access)
- Set device ID via `fpi_device_probe_complete()`
- Set device name
- Optionally set dynamic properties (enroll stages, scan type)
- Call `fpi_device_probe_complete()` to finish or report error

### Called:
Once per discovered device

### Threading:
May run in any context; keep quick
```

--------------------------------

### Include libfprint API

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/INDEX.md

Include the main header file for all public libfprint APIs.

```c
#include <libfprint/fprint.h>  // All public APIs
```

--------------------------------

### Open Fingerprint Device Asynchronously

Source: https://github.com/libfprint/libfprint/blob/master/_autodocs/api-reference/FpDevice.md

Initiates the asynchronous opening of a fingerprint device. This must be called before any other operations. The completion is handled by the provided callback.

```c
void fp_device_open (FpDevice           *device,
                     GCancellable       *cancellable,
                     GAsyncReadyCallback callback,
                     gpointer            user_data);

gboolean fp_device_open_finish (FpDevice     *device,
                                GAsyncResult *result,
                                GError      **error);
```