fprint.h 15.8 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
/*
 * Main definitions for libfprint
 * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef __FPRINT_H__
#define __FPRINT_H__

23 24 25 26
#ifdef __cplusplus
extern "C" {
#endif

Daniel Drake's avatar
Daniel Drake committed
27
#include <stdint.h>
28 29
#include <stddef.h>
#include <unistd.h>
30
#include <sys/time.h>
Daniel Drake's avatar
Daniel Drake committed
31

32 33 34 35 36 37 38
/**
 * LIBFPRINT_DEPRECATED:
 *
 * Expands to the GNU C deprecated attribute if the compiler is `gcc`. When
 * called with the `-Wdeprecated-declarations` option, `gcc` will generate warnings
 * when deprecated interfaces are used.
 */
39 40
#define LIBFPRINT_DEPRECATED __attribute__((__deprecated__))

41 42 43
/**
 * fp_dscv_dev:
 *
44
 * #fp_dscv_dev is an opaque structure type.  You must access it using the
45
 * functions in this section.
46
 */
47
struct fp_dscv_dev;
48 49 50 51

/**
 * fp_dscv_print:
 *
52
 * #fp_dscv_print is an opaque structure type.  You must access it using the
53
 * functions in this section.
54
 */
Daniel Drake's avatar
Daniel Drake committed
55
struct fp_dscv_print;
56 57 58 59

/**
 * fp_dev:
 *
60
 * #fp_dev is an opaque structure type.  You must access it using the
61
 * functions in this section.
62
 */
63
struct fp_dev;
64 65 66 67

/**
 * fp_driver:
 *
68
 * #fp_driver is an opaque structure type.  You must access it using the
69
 * functions in this section.
70
 */
71
struct fp_driver;
72 73 74 75

/**
 * fp_print_data:
 *
76
 * #fp_print_data is an opaque structure type.  You must access it using the
77
 * functions in this section.
78
 */
79
struct fp_print_data;
80 81 82 83

/**
 * fp_img:
 *
84
 * #fp_img is an opaque structure type.  You must access it using the
85
 * functions in this section.
86
 */
87
struct fp_img;
88

89
/* misc/general stuff */
Daniel Drake's avatar
Daniel Drake committed
90

91 92 93 94 95 96 97 98 99 100 101 102 103
/**
 * 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
 *
Daniel Drake's avatar
Daniel Drake committed
104 105 106 107
 * 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.
 */
108
enum fp_finger {
109 110 111 112 113 114 115 116 117 118
	LEFT_THUMB = 1,
	LEFT_INDEX,
	LEFT_MIDDLE,
	LEFT_RING,
	LEFT_LITTLE,
	RIGHT_THUMB,
	RIGHT_INDEX,
	RIGHT_MIDDLE,
	RIGHT_RING,
	RIGHT_LITTLE,
119 120
};

121 122 123 124 125
/**
 * 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
 *
126 127 128 129 130
 * 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 {
131 132
	FP_SCAN_TYPE_PRESS = 0,
	FP_SCAN_TYPE_SWIPE,
133 134
};

Daniel Drake's avatar
Daniel Drake committed
135 136 137 138
/* Drivers */
const char *fp_driver_get_name(struct fp_driver *drv);
const char *fp_driver_get_full_name(struct fp_driver *drv);
uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
139
enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv);
140
int fp_driver_supports_imaging(struct fp_driver *drv);
Daniel Drake's avatar
Daniel Drake committed
141

142 143 144
/* Device discovery */
struct fp_dscv_dev **fp_discover_devs(void);
void fp_dscv_devs_free(struct fp_dscv_dev **devs);
145
struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
146
uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev);
147
uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
Daniel Drake's avatar
Daniel Drake committed
148 149 150
int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
	struct fp_print_data *print);
int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
151
	struct fp_dscv_print *print) LIBFPRINT_DEPRECATED;
Daniel Drake's avatar
Daniel Drake committed
152
struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
153
	struct fp_print_data *print) LIBFPRINT_DEPRECATED;
Daniel Drake's avatar
Daniel Drake committed
154
struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
155
	struct fp_dscv_print *print) LIBFPRINT_DEPRECATED;
156

Daniel Drake's avatar
Daniel Drake committed
157
/* Print discovery */
158 159 160 161 162 163
struct fp_dscv_print **fp_discover_prints(void) LIBFPRINT_DEPRECATED;
void fp_dscv_prints_free(struct fp_dscv_print **prints) LIBFPRINT_DEPRECATED;
uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED;
uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED;
enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED;
int fp_dscv_print_delete(struct fp_dscv_print *print) LIBFPRINT_DEPRECATED;
Daniel Drake's avatar
Daniel Drake committed
164

165 166 167
/* Device handling */
struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
void fp_dev_close(struct fp_dev *dev);
168
struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
Daniel Drake's avatar
Daniel Drake committed
169
int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
170
uint32_t fp_dev_get_devtype(struct fp_dev *dev);
Daniel Drake's avatar
Daniel Drake committed
171
int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
172
int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print) LIBFPRINT_DEPRECATED;
173

174 175 176 177 178
/**
 * fp_capture_result:
 * @FP_CAPTURE_COMPLETE: Capture completed successfully, the capture data has been returned to the caller.
 * @FP_CAPTURE_FAIL: Capture failed
 *
179
 * Whether a capture failed or completed.
180 181 182 183 184 185
 */
enum fp_capture_result {
	FP_CAPTURE_COMPLETE = 0,
	FP_CAPTURE_FAIL,
};

186 187
int fp_dev_supports_imaging(struct fp_dev *dev);
int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
188
	struct fp_img **img);
189 190 191
int fp_dev_get_img_width(struct fp_dev *dev);
int fp_dev_get_img_height(struct fp_dev *dev);

192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
/**
 * 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.
 *
 *
Daniel Drake's avatar
Daniel Drake committed
210 211 212 213 214
 * 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
215
 * [Enrolling](libfprint-Devices-operations.html#enrolling)
Daniel Drake's avatar
Daniel Drake committed
216
 */
217
enum fp_enroll_result {
Daniel Drake's avatar
Daniel Drake committed
218
	FP_ENROLL_COMPLETE = 1,
Daniel Drake's avatar
Daniel Drake committed
219 220
	FP_ENROLL_FAIL,
	FP_ENROLL_PASS,
221
	FP_ENROLL_RETRY = 100,
Daniel Drake's avatar
Daniel Drake committed
222 223
	FP_ENROLL_RETRY_TOO_SHORT,
	FP_ENROLL_RETRY_CENTER_FINGER,
224
	FP_ENROLL_RETRY_REMOVE_FINGER,
Daniel Drake's avatar
Daniel Drake committed
225 226
};

227 228
int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
	struct fp_img **img);
229 230
int fp_enroll_finger(struct fp_dev *dev,
	struct fp_print_data **print_data);
Daniel Drake's avatar
Daniel Drake committed
231

232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
/**
 * 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.
 *
249 250
 * Verification result codes returned from fp_verify_finger(). Return codes
 * are also shared with fp_identify_finger().
Daniel Drake's avatar
Daniel Drake committed
251 252 253 254
 * 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 verify operation.
 */
255 256 257 258 259 260 261 262 263
enum fp_verify_result {
	FP_VERIFY_NO_MATCH = 0,
	FP_VERIFY_MATCH = 1,
	FP_VERIFY_RETRY = FP_ENROLL_RETRY,
	FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
	FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
	FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
};

264 265
int fp_verify_finger_img(struct fp_dev *dev,
	struct fp_print_data *enrolled_print, struct fp_img **img);
266 267
int fp_verify_finger(struct fp_dev *dev,
	struct fp_print_data *enrolled_print);
268

269 270 271 272
int fp_dev_supports_identification(struct fp_dev *dev);
int fp_identify_finger_img(struct fp_dev *dev,
	struct fp_print_data **print_gallery, size_t *match_offset,
	struct fp_img **img);
273 274
int fp_identify_finger(struct fp_dev *dev,
	struct fp_print_data **print_gallery, size_t *match_offset);
275

276
/* Data handling */
277
int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
278
	struct fp_print_data **data) LIBFPRINT_DEPRECATED;
Daniel Drake's avatar
Daniel Drake committed
279
int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
280
	struct fp_print_data **data) LIBFPRINT_DEPRECATED;
281 282 283 284
int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger)
	LIBFPRINT_DEPRECATED;
int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger)
	LIBFPRINT_DEPRECATED;
285
void fp_print_data_free(struct fp_print_data *data);
286 287 288
size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
	size_t buflen);
289 290
uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
291

292
/* Image handling */
293

294 295 296
/**
 * fp_minutia:
 *
297
 * #fp_minutia is an opaque structure type.  You must access it using the
298
 * functions in this section.
299
 */
300
struct fp_minutia;
301

302 303 304 305
int fp_img_get_height(struct fp_img *img);
int fp_img_get_width(struct fp_img *img);
unsigned char *fp_img_get_data(struct fp_img *img);
int fp_img_save_to_file(struct fp_img *img, char *path);
Daniel Drake's avatar
Daniel Drake committed
306
void fp_img_standardize(struct fp_img *img);
307
struct fp_img *fp_img_binarize(struct fp_img *img);
308
struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
309
int fp_minutia_get_coords(struct fp_minutia *minutia, int *coord_x, int *coord_y);
310
void fp_img_free(struct fp_img *img);
311

312
/* Polling and timing */
Daniel Drake's avatar
Daniel Drake committed
313

314 315
/**
 * fp_pollfd:
316 317
 * @fd: a file descriptor
 * @events: Event flags to poll for from `<poll.h>`
318
 *
319
 * A structure representing a file descriptor and the @events to poll
320
 * for, as returned by fp_get_pollfds().
321
 */
Daniel Drake's avatar
Daniel Drake committed
322 323
struct fp_pollfd {
	int fd;
324
	short int events;
Daniel Drake's avatar
Daniel Drake committed
325 326
};

327 328
int fp_handle_events_timeout(struct timeval *timeout);
int fp_handle_events(void);
329
ssize_t fp_get_pollfds(struct fp_pollfd **pollfds);
330
int fp_get_next_timeout(struct timeval *tv);
Daniel Drake's avatar
Daniel Drake committed
331

332 333 334 335 336 337 338 339 340
/**
 * fp_pollfd_added_cb:
 * @fd: the new file descriptor
 * @events: events to monitor for, see `<poll.h>` for the possible values
 *
 * Type definition for a function that will be called when a new
 * event source is added. The @events argument is a flag as defined in
 * `<poll.h>` such as `POLLIN`, or `POLLOUT`. See fp_set_pollfd_notifiers().
 */
341
typedef void (*fp_pollfd_added_cb)(int fd, short int events);
342 343 344 345 346 347 348 349

/**
 * fp_pollfd_removed_cb:
 * @fd: the file descriptor to stop monitoring
 *
 * Type definition for a function that will be called when an
 * event source is removed. See fp_set_pollfd_notifiers().
 */
Daniel Drake's avatar
Daniel Drake committed
350 351 352
typedef void (*fp_pollfd_removed_cb)(int fd);
void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
	fp_pollfd_removed_cb removed_cb);
353

354
/* Library */
355
int fp_init(void);
356
void fp_exit(void);
357
void fp_set_debug(int level) LIBFPRINT_DEPRECATED;
358

359 360
/* Asynchronous I/O */

361 362
/**
 * fp_operation_stop_cb:
363
 * @dev: the struct #fp_dev device
364 365 366 367 368 369
 * @user_data: user data passed to the callback
 *
 * Type definition for a function that will be called when fp_async_dev_close(),
 * fp_async_verify_stop(), fp_async_identify_stop() or fp_async_capture_stop()
 * finishes.
 */
370
typedef void (*fp_operation_stop_cb)(struct fp_dev *dev, void *user_data);
371 372 373

/**
 * fp_img_operation_cb:
374
 * @dev: the struct #fp_dev device
375 376 377 378 379 380 381 382
 * @result: an #fp_verify_result for fp_async_verify_start(), or an #fp_capture_result
 * for fp_async_capture_start(), or a negative value on error
 * @img: the captured #fp_img if capture or verification was successful
 * @user_data: user data passed to the callback
 *
 * Type definition for a function that will be called when fp_async_verify_start()
 * or fp_async_capture_start() finished.
 */
383 384
typedef void (*fp_img_operation_cb)(struct fp_dev *dev, int result,
	struct fp_img *img, void *user_data);
385

386 387
/**
 * fp_dev_open_cb:
388
 * @dev: the struct #fp_dev device
389 390 391 392 393 394
 * @status: 0 on success, or a negative value on error
 * @user_data: user data passed to the callback
 *
 * Type definition for a function that will be called when fp_async_dev_open
 * finishes.
 */
395
typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data);
396

397 398 399
int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
	void *user_data);

400
void fp_async_dev_close(struct fp_dev *dev, fp_operation_stop_cb callback,
401 402
	void *user_data);

403 404
/**
 * fp_enroll_stage_cb:
405
 * @dev: the struct #fp_dev device
406 407 408 409 410 411
 * @result: a #fp_enroll_result on success, or a negative value on failure
 * @print: the enrollment data from the final stage
 * @img: an #fp_img to free with fp_img_free()
 * @user_data: user data passed to the callback
 *
 * Type definition for a function that will be called when
412 413
 * fp_async_enroll_start() finishes. See fp_enroll_finger_img() for
 * the expected behaviour of your program based on the @result.
414
 */
415 416
typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result,
	struct fp_print_data *print, struct fp_img *img, void *user_data);
417

418 419 420
int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback,
	void *user_data);

421
int fp_async_enroll_stop(struct fp_dev *dev, fp_operation_stop_cb callback,
422 423 424
	void *user_data);

int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data,
425
	fp_img_operation_cb callback, void *user_data);
426

427
int fp_async_verify_stop(struct fp_dev *dev, fp_operation_stop_cb callback,
428 429
	void *user_data);

430 431
/**
 * fp_identify_cb:
432
 * @dev: the struct #fp_dev device
433 434 435 436 437 438 439 440 441
 * @result: a #fp_verify_result on success, or a negative value on error.
 * @match_offset: the array index of the matched gallery print (if any was found).
 * Only valid if %FP_VERIFY_MATCH was returned.
 * @img: the scan image, it must be freed with fp_img_free() after use.
 * @user_data: user data passed to the callback
 *
 * Type definition for a function that will be called when fp_async_identify_start()
 * finishes.
 */
442 443 444 445 446
typedef void (*fp_identify_cb)(struct fp_dev *dev, int result,
	size_t match_offset, struct fp_img *img, void *user_data);
int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery,
	fp_identify_cb callback, void *user_data);

447
int fp_async_identify_stop(struct fp_dev *dev, fp_operation_stop_cb callback,
448 449
	void *user_data);

450
int fp_async_capture_start(struct fp_dev *dev, int unconditional, fp_img_operation_cb callback, void *user_data);
451

452
int fp_async_capture_stop(struct fp_dev *dev, fp_operation_stop_cb callback, void *user_data);
453

454 455 456 457
#ifdef __cplusplus
}
#endif

458 459
#endif