net.reactivated.Fprint.Device: fprintd Reference Manual

## net.reactivated.Fprint.Device net.reactivated.Fprint.Device — Device interface |

## Methods

    ListEnrolledFingers   (in  's'  username,
                           out 'as' enrolled_fingers)
    DeleteEnrolledFingers (in  's'  username)
    Claim                 (in  's'  username)
    Release               ()
    VerifyStart           (in  's'  finger_name)
    VerifyStop            ()
    EnrollStart           (in  's'  finger_name)
    EnrollStop            ()

## Signals

    VerifyFingerSelected ('s' finger_name)
    VerifyStatus         ('s' result,
                          'b' done)
    EnrollStatus         ('s' result,
                          'b' done)

## Implemented Interfaces

Objects implementing net.reactivated.Fprint.Device also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

## Properties

    'name'              read      's'
    'num-enroll-stages' read      'i'
    'scan-type'         read      's'

## Description

### PolicyKit integration

fprintd uses PolicyKit to check whether users are allowed to access fingerprint data, or the fingerprint readers itself.

- net.reactivated.fprint.device.verify: Whether the user is allowed to verify fingers against saved fingerprints.
- net.reactivated.fprint.device.enroll: Whether the user is allowed to enroll new fingerprints.
- net.reactivated.fprint.device.setusername: Whether the user is allowed to query, verify, or enroll fingerprints for users other than itself.

### Usernames

When a username argument is used for a method, a PolicyKit check is done on the `net.reactivated.fprint.device.setusername` PolicyKit action to see whether the user the client is running as is allowed to access data from other users.

By default, only root is allowed to access fingerprint data for users other than itself. For a normal user, it is recommended that you use an empty string for the username, which will mean "the client the user is running as".

See PolicyKit integration.

### Fingerprint names

When a finger name argument is used for a method, it refers to either a single finger, or "any" finger. See the list of possible values below:

- left-thumb: Left thumb
- left-index-finger: Left index finger
- left-middle-finger: Left middle finger
- left-ring-finger: Left ring finger
- left-little-finger: Left little finger
- right-thumb: Right thumb
- right-index-finger: Right index finger
- right-middle-finger: Right middle finger
- right-ring-finger: Right ring finger
- right-little-finger: Right little finger
- any: Any finger. This is only used for `Device.VerifyStart` (select the first finger with a fingerprint associated, or all the fingerprints available for the user when the device supports it) and `Device::VerifyFingerSelected` (any finger with an associated fingerprint can be used).

### Verify Statuses

- verify-no-match: The verification did not match, `Device.VerifyStop` should now be called.
- verify-match: The verification succeeded, `Device.VerifyStop` should now be called.
- verify-retry-scan: The user should retry scanning their finger, the verification is still ongoing.
- verify-swipe-too-short: The user's swipe was too short. The user should retry scanning their finger, the verification is still ongoing.
- verify-finger-not-centered: The user's finger was not centered on the reader. The user should retry scanning their finger, the verification is still ongoing.
- verify-remove-and-retry: The user should remove their finger from the reader and retry scanning their finger, the verification is still ongoing.
- verify-disconnected: The device was disconnected during the verification, no other actions should be taken, and you shouldn't use the device any more.
- verify-unknown-error: An unknown error occurred (usually a driver problem), `Device.VerifyStop` should now be called.

### Enroll Statuses

- enroll-completed: The enrollment successfully completed, `Device.EnrollStop` should now be called.
- enroll-failed: The enrollment failed, `Device.EnrollStop` should now be called.
- enroll-stage-passed: One stage of the enrollment passed, the enrollment is still ongoing.
- enroll-retry-scan: The user should retry scanning their finger, the enrollment is still ongoing.
- enroll-swipe-too-short: The user's swipe was too short. The user should retry scanning their finger, the enrollment is still ongoing.
- enroll-finger-not-centered: The user's finger was not centered on the reader. The user should retry scanning their finger, the enrollment is still ongoing.
- enroll-remove-and-retry: The user should remove their finger from the reader and retry scanning their finger, the enrollment is still ongoing.
- enroll-disconnected: The device was disconnected during the enrollment, no other actions should be taken, and you shouldn't use the device any more.
- enroll-unknown-error: An unknown error occurred (usually a driver problem), `Device.EnrollStop` should now be called.

## Details

### ListEnrolledFingers ()

    ListEnrolledFingers (in  's'  username,
                         out 'as' enrolled_fingers)

List all the enrolled fingerprints for the chosen user.

`username`: | The username for whom to list the enrolled fingerprints. See Usernames.
`enrolled_fingers`: | An array of strings representing the enrolled fingerprints. See Fingerprint names.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.NoEnrolledPrints`: | if the chosen user doesn't have any fingerprints enrolled

### DeleteEnrolledFingers ()

    DeleteEnrolledFingers (in  's' username)

Delete all the enrolled fingerprints for the chosen user.

`username`: | The username for whom to delete the enrolled fingerprints. See Usernames.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization

### Claim ()

    Claim (in  's' username)

Claim the device for the chosen user.

`username`: | The username for whom to claim the device. See Usernames.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.AlreadyInUse`: | if the device is already claimed
`net.reactivated.Fprint.Error.Internal`: | if the device couldn't be claimed

### Release ()

    Release ()

Release a device claimed with `Device.Claim`.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.ClaimDevice`: | if the device was not claimed

### VerifyStart ()

    VerifyStart (in  's' finger_name)

Check the chosen finger against a saved fingerprint. You need to have claimed the device using `Device.Claim`. The finger selected is sent to the front-end using `Device::VerifyFingerSelected` and verification status through `Device::VerifyStatus`.

`finger_name`: | A string representing the finger to verify. See Fingerprint names.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.ClaimDevice`: | if the device was not claimed
`net.reactivated.Fprint.Error.AlreadyInUse`: | if the device was already being used
`net.reactivated.Fprint.Error.NoEnrolledPrints`: | if there are no enrolled prints for the chosen user
`net.reactivated.Fprint.Error.Internal`: | if there was an internal error

### VerifyStop ()

    VerifyStop ()

Stop an on-going fingerprint verification started with `Device.VerifyStart`.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.ClaimDevice`: | if the device was not claimed
`net.reactivated.Fprint.Error.NoActionInProgress`: | if there was no ongoing verification
`net.reactivated.Fprint.Error.Internal`: | if there was an internal error

### EnrollStart ()

    EnrollStart (in  's' finger_name)

Start enrollemnt for the selected finger. You need to have claimed the device using `Device.Claim` before calling this method. Enrollment status is sent through `Device::EnrollStatus`.

`finger_name`: | A string representing the finger to enroll. See Fingerprint names. Note that "any" is not a valid finger name for this method.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.ClaimDevice`: | if the device was not claimed
`net.reactivated.Fprint.Error.AlreadyInUse`: | if the device was already being used
`net.reactivated.Fprint.Error.InvalidFingername`: | if there are no enrolled prints for the chosen user
`net.reactivated.Fprint.Error.Internal`: | if there was an internal error

### EnrollStop ()

    EnrollStop ()

Stop an on-going fingerprint enrollment started with `Device.EnrollStart`.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.ClaimDevice`: | if the device was not claimed
`net.reactivated.Fprint.Error.NoActionInProgress`: | if there was no ongoing verification
`net.reactivated.Fprint.Error.Internal`: | if there was an internal error

## Signal Details

### The VerifyFingerSelected signal

    VerifyFingerSelected ('s' finger_name)

`finger_name`: | A string representing the finger select to be verified.

See also: Fingerprint names.

### The VerifyStatus signal

    VerifyStatus ('s' result,
                  'b' done)

`result`: | A string representing the status of the verification.
`done`: | Whether the verification finished and can be stopped.

See also: Verify Statuses and `Device.VerifyStop`.

### The EnrollStatus signal

    EnrollStatus ('s' result,
                  'b' done)

`result`: | A string representing the status of the enrollment.
`done`: | Whether the enrollment finished and can be stopped.

See also: Enrollment Statuses and `Device.EnrollStop`.

## Property Details

### The "name" property

    'name'  read      's'

The product name of the device.

### The "num-enroll-stages" property

    'num-enroll-stages'  read      'i'

The number of enrollment stages for the device. This is only available when the device has been claimed, otherwise it will be undefined (-1).

See also: `Device.Claim` and `Device.EnrollStart`.

### The "scan-type" property

    'scan-type'  read      's'

The scan type of the device, either "press" if you place your finger on the device, or "swipe" if you have to swipe your finger.