mirrors/libfprint
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libfprint/libfprint.git synced 2025-11-15 07:38:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: Port from Doxygen to gtk-doc

Browse Source 
Split the introduction into separate chapters, add filler documentation
for async functions, fix mismatched function arguments.
This commit is contained in:
Bastien Nocera
2018-05-17 02:58:59 +02:00
parent dac153d24a
commit 231b8f9f92
18 changed files with 1216 additions and 1847 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
libfprint/fprint.h
View File

@@ -27,42 +27,86 @@ extern "C" {
#include <stdint.h>
#include <sys/time.h>
/* structs that applications are not allowed to peek into */
/**
* fp_dscv_dev:
*
*/
struct fp_dscv_dev;
/**
* fp_dscv_print:
*
*/
struct fp_dscv_print;
/**
* fp_dev:
*
*/
struct fp_dev;
/**
* fp_driver:
*
*/
struct fp_driver;
/**
* fp_print_data:
*
*/
struct fp_print_data;
/**
* fp_img:
*
*/
struct fp_img;
/* misc/general stuff */
/** \ingroup print_data
/**
* fp_finger:
* @LEFT_THUMB: Left thumb
* @LEFT_INDEX: Left index finger
* @LEFT_MIDDLE: Left middle finger
* @LEFT_RING: Left ring finger
* @LEFT_LITTLE: Left little finger
* @RIGHT_THUMB: Right thumb
* @RIGHT_INDEX: Right index finger
* @RIGHT_MIDDLE: Right middle finger
* @RIGHT_RING: Right ring finger
* @RIGHT_LITTLE: Right little finger
*
* Numeric codes used to refer to fingers (and thumbs) of a human. These are
* purposely not available as strings, to avoid getting the library tangled up
* in localization efforts.
*/
enum fp_finger {
LEFT_THUMB = 1, /** thumb (left hand) */
LEFT_INDEX, /** index finger (left hand) */
LEFT_MIDDLE, /** middle finger (left hand) */
LEFT_RING, /** ring finger (left hand) */
LEFT_LITTLE, /** little finger (left hand) */
RIGHT_THUMB, /** thumb (right hand) */
RIGHT_INDEX, /** index finger (right hand) */
RIGHT_MIDDLE, /** middle finger (right hand) */
RIGHT_RING, /** ring finger (right hand) */
RIGHT_LITTLE, /** little finger (right hand) */
LEFT_THUMB = 1,
LEFT_INDEX,
LEFT_MIDDLE,
LEFT_RING,
LEFT_LITTLE,
RIGHT_THUMB,
RIGHT_INDEX,
RIGHT_MIDDLE,
RIGHT_RING,
RIGHT_LITTLE,
};
/** \ingroup dev
/**
* fp_scan_type:
* @FP_SCAN_TYPE_PRESS: the reader has a surface area that covers the whole finger
* @FP_SCAN_TYPE_SWIPE: the reader requires swiping the finger on a smaller area
*
* Numeric codes used to refer to the scan type of the device. Devices require
* either swiping or pressing the finger on the device. This is useful for
* front-ends.
*/
enum fp_scan_type {
FP_SCAN_TYPE_PRESS = 0, /** press */
FP_SCAN_TYPE_SWIPE, /** swipe */
FP_SCAN_TYPE_PRESS = 0,
FP_SCAN_TYPE_SWIPE,
};
/* Drivers */
@@ -85,6 +129,12 @@ struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
struct fp_dscv_print *print);
/**
* fp_dscv_dev_get_driver_id:
* @dev: a discovered fingerprint device
*
* Returns: the ID for the underlying driver for that device
*/
static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
{
return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
@@ -107,68 +157,75 @@ uint32_t fp_dev_get_devtype(struct fp_dev *dev);
int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
/** \ingroup dev
* Image capture result codes returned from fp_dev_img_capture().
/**
* fp_capture_result:
* Whether a capture failed or completed.
*
* @FP_CAPTURE_COMPLETE: Capture completed successfully, the capture data has been returned to the caller.
* @FP_CAPTURE_FAIL: Capture failed
*
*/
enum fp_capture_result {
/** Capture completed successfully, the capture data has been
* returned to the caller. */
FP_CAPTURE_COMPLETE = 0,
/** Capture failed for some reason */
FP_CAPTURE_FAIL,
};
int fp_dev_supports_imaging(struct fp_dev *dev);
int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
struct fp_img **image);
struct fp_img **img);
int fp_dev_get_img_width(struct fp_dev *dev);
int fp_dev_get_img_height(struct fp_dev *dev);
/** \ingroup dev
/**
* fp_enroll_result:
* @FP_ENROLL_COMPLETE: Enrollment completed successfully, the enrollment data has been
* returned to the caller.
* @FP_ENROLL_FAIL: Enrollment failed due to incomprehensible data; this may occur when
* the user scans a different finger on each enroll stage.
* @FP_ENROLL_PASS: Enroll stage passed; more stages are need to complete the process.
* @FP_ENROLL_RETRY: The enrollment scan did not succeed due to poor scan quality or
* other general user scanning problem.
* @FP_ENROLL_RETRY_TOO_SHORT: The enrollment scan did not succeed because the finger swipe was
* too short.
* @FP_ENROLL_RETRY_CENTER_FINGER: The enrollment scan did not succeed because the finger was not
* centered on the scanner.
* @FP_ENROLL_RETRY_REMOVE_FINGER: The verification scan did not succeed due to quality or pressure
* problems; the user should remove their finger from the scanner before
* retrying.
*
*
* Enrollment result codes returned from fp_enroll_finger().
* Result codes with RETRY in the name suggest that the scan failed due to
* user error. Applications will generally want to inform the user of the
* problem and then retry the enrollment stage. For more info on the semantics
* of interpreting these result codes and tracking enrollment process, see
* \ref enrolling.
* [Enrolling](libfprint-Devices-operations.html#enrolling)
*/
enum fp_enroll_result {
/** Enrollment completed successfully, the enrollment data has been
* returned to the caller. */
FP_ENROLL_COMPLETE = 1,
/** Enrollment failed due to incomprehensible data; this may occur when
* the user scans a different finger on each enroll stage. */
FP_ENROLL_FAIL,
/** Enroll stage passed; more stages are need to complete the process. */
FP_ENROLL_PASS,
/** The enrollment scan did not succeed due to poor scan quality or
* other general user scanning problem. */
FP_ENROLL_RETRY = 100,
/** The enrollment scan did not succeed because the finger swipe was
* too short. */
FP_ENROLL_RETRY_TOO_SHORT,
/** The enrollment scan did not succeed because the finger was not
* centered on the scanner. */
FP_ENROLL_RETRY_CENTER_FINGER,
/** The verification scan did not succeed due to quality or pressure
* problems; the user should remove their finger from the scanner before
* retrying. */
FP_ENROLL_RETRY_REMOVE_FINGER,
};
int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
struct fp_img **img);
/** \ingroup dev
* Performs an enroll stage. See \ref enrolling for an explanation of enroll
* stages. This function is just a shortcut to calling fp_enroll_finger_img()
* with a NULL image parameter. Be sure to read the description of
* fp_enroll_finger_img() in order to understand its behaviour.
*
* \param dev the device
* \param print_data a location to return the resultant enrollment data from
/**
* fp_enroll_finger:
* @dev: the device
* @print_data: a location to return the resultant enrollment data from
* the final stage. Must be freed with fp_print_data_free() after use.
* \return negative code on error, otherwise a code from #fp_enroll_result
*
* Performs an enroll stage. See [Enrolling](libfprint-Devices-operations.html#enrolling)
* for an explanation of enroll stages. This function is just a shortcut to
* calling fp_enroll_finger_img() with a %NULL image parameter. Be sure to read
* the description of fp_enroll_finger_img() in order to understand its behaviour.
*
* Returns: negative code on error, otherwise a code from #fp_enroll_result
*/
static inline int fp_enroll_finger(struct fp_dev *dev,
struct fp_print_data **print_data)
@@ -176,7 +233,23 @@ static inline int fp_enroll_finger(struct fp_dev *dev,
return fp_enroll_finger_img(dev, print_data, NULL);
}
/** \ingroup dev
/**
* fp_verify_result:
* @FP_VERIFY_NO_MATCH: The scan completed successfully, but the newly scanned fingerprint
* does not match the fingerprint being verified against.
* In the case of identification, this return code indicates that the
* scanned finger could not be found in the print gallery.
* @FP_VERIFY_MATCH: The scan completed successfully and the newly scanned fingerprint does
* match the fingerprint being verified, or in the case of identification,
* the scanned fingerprint was found in the print gallery.
* @FP_VERIFY_RETRY: The scan did not succeed due to poor scan quality or other general
* user scanning problem.
* @FP_VERIFY_RETRY_TOO_SHORT: The scan did not succeed because the finger swipe was too short.
* @FP_VERIFY_RETRY_CENTER_FINGER: The scan did not succeed because the finger was not centered on the
* scanner.
* @FP_VERIFY_RETRY_REMOVE_FINGER: The scan did not succeed due to quality or pressure problems; the user
* should remove their finger from the scanner before retrying.
*
* Verification result codes returned from fp_verify_finger(). Return codes
* are also shared with fp_identify_finger().
* Result codes with RETRY in the name suggest that the scan failed due to
@@ -184,39 +257,28 @@ static inline int fp_enroll_finger(struct fp_dev *dev,
* problem and then retry the verify operation.
*/
enum fp_verify_result {
/** The scan completed successfully, but the newly scanned fingerprint
* does not match the fingerprint being verified against.
* In the case of identification, this return code indicates that the
* scanned finger could not be found in the print gallery. */
FP_VERIFY_NO_MATCH = 0,
/** The scan completed successfully and the newly scanned fingerprint does
* match the fingerprint being verified, or in the case of identification,
* the scanned fingerprint was found in the print gallery. */
FP_VERIFY_MATCH = 1,
/** The scan did not succeed due to poor scan quality or other general
* user scanning problem. */
FP_VERIFY_RETRY = FP_ENROLL_RETRY,
/** The scan did not succeed because the finger swipe was too short. */
FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
/** The scan did not succeed because the finger was not centered on the
* scanner. */
FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
/** The scan did not succeed due to quality or pressure problems; the user
* should remove their finger from the scanner before retrying. */
FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
};
int fp_verify_finger_img(struct fp_dev *dev,
struct fp_print_data *enrolled_print, struct fp_img **img);
/** \ingroup dev
/**
* fp_verify_finger:
* @dev: the device to perform the scan.
* @enrolled_print: the print to verify against. Must have been previously
* enrolled with a device compatible to the device selected to perform the scan.
*
* Performs a new scan and verify it against a previously enrolled print. This
* function is just a shortcut to calling fp_verify_finger_img() with a NULL
* image output parameter.
* \param dev the device to perform the scan.
* \param enrolled_print the print to verify against. Must have been previously
* enrolled with a device compatible to the device selected to perform the scan.
* \return negative code on error, otherwise a code from #fp_verify_result
*
* Returns: negative code on error, otherwise a code from #fp_verify_result
* \sa fp_verify_finger_img()
*/
static inline int fp_verify_finger(struct fp_dev *dev,
@@ -230,19 +292,22 @@ int fp_identify_finger_img(struct fp_dev *dev,
struct fp_print_data **print_gallery, size_t *match_offset,
struct fp_img **img);
/** \ingroup dev
* Performs a new scan and attempts to identify the scanned finger against a
* collection of previously enrolled fingerprints. This function is just a
* shortcut to calling fp_identify_finger_img() with a NULL image output
* parameter.
* \param dev the device to perform the scan.
* \param print_gallery NULL-terminated array of pointers to the prints to
/**
* fp_identify_finger:
* @dev: the device to perform the scan.
* @print_gallery: %NULL-terminated array of pointers to the prints to
* identify against. Each one must have been previously enrolled with a device
* compatible to the device selected to perform the scan.
* \param match_offset output location to store the array index of the matched
* @match_offset: output location to store the array index of the matched
* gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
* returned.
* \return negative code on error, otherwise a code from #fp_verify_result
* Performs a new scan and attempts to identify the scanned finger against a
* collection of previously enrolled fingerprints. This function is just a
* shortcut to calling fp_identify_finger_img() with a %NULL image output
* parameter.
*
* Returns: negative code on error, otherwise a code from #fp_verify_result
* \sa fp_identify_finger_img()
*/
static inline int fp_identify_finger(struct fp_dev *dev,
@@ -267,7 +332,11 @@ uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
/* Image handling */
/** \ingroup img */
/**
* fp_minutia:
*
* FIXME
*/
struct fp_minutia {
int x;
int y;
@@ -294,6 +363,10 @@ void fp_img_free(struct fp_img *img);
/* Polling and timing */
/**
* fp_pollfd:
*
*/
struct fp_pollfd {
int fd;
short events;