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)
    DeleteEnrolledFingers2 ()
    DeleteEnrolledFinger   (in  's'  finger_name)
    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'
    'finger-present'    read      'b'
    'finger-needed'     read      'b'

## 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-data-full: No further prints can be enrolled on this device, `Device.EnrollStop` should now be called. `Delete other prints` from the device first to continue (e.g. from other users). Note that old prints or prints from other operating systems may be deleted automatically to resolve this error without any notification.
- enroll-duplicate: The print has already been enrolled, `Device.EnrollStop` should now be called. The user should enroll a different finger, or delete the print that has been enrolled already. This print may be enrolled for a different user. Note that an old duplicate (e.g. from a previous install) will be automatically garbage collected and should not cause any issues.
- 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.

This call only exists for compatibility reasons, you should instead claim the device using `Device.Claim` and then call `DeleteEnrolledFingers2` or `DeleteEnrolledFinger`.

`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
`net.reactivated.Fprint.Error.PrintsNotDeleted`: | if the fingerprint is not deleted from fprintd storage

### DeleteEnrolledFingers2 ()

    DeleteEnrolledFingers2 ()

Delete all the enrolled fingerprints for the user currently claiming the device with `Device.Claim`.

#### Errors

`net.reactivated.Fprint.Error.PermissionDenied`: | if the caller lacks the appropriate PolicyKit authorization
`net.reactivated.Fprint.Error.PrintsNotDeleted`: | if the fingerprint is not deleted from fprintd storage

### DeleteEnrolledFinger ()

    DeleteEnrolledFinger (in  's' finger_name)

Delete the enrolled fingerprint for the user currently claiming the device with `Device.Claim`.

`finger_name`: | A string representing the finger to delete. 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.InvalidFingername`: | if the finger name passed is invalid
`net.reactivated.Fprint.Error.NoEnrolledPrints`: | if the chosen user doesn't have the requsted fingerprint enrolled
`net.reactivated.Fprint.Error.PrintsNotDeleted`: | if the fingerprint is not deleted from fprintd storage

### 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 enrollment 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 the finger name passed is invalid
``: | if the finger has been already enrolled by the 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.

### The "finger-present" property

    'finger-present'  read      'b'

Whether the finger is on sensor.

### The "finger-needed" property

    'finger-needed'  read      'b'

Whether the sensor is waiting for the finger.