1 /*
2 * Main definitions for libfprint
3 * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 */
19
20 #ifndef __FPRINT_H__
21 #define __FPRINT_H__
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 #include <stdint.h>
28 #include <sys/time.h>
29
30 /* structs that applications are not allowed to peek into */
31 struct fp_dscv_dev;
32 struct fp_dscv_print;
33 struct fp_dev;
34 struct fp_driver;
35 struct fp_print_data;
36 struct fp_img;
37
38 /* misc/general stuff */
39
40 /** \ingroup print_data
41 * Numeric codes used to refer to fingers (and thumbs) of a human. These are
42 * purposely not available as strings, to avoid getting the library tangled up
43 * in localization efforts.
44 */
45 enum fp_finger {
46 LEFT_THUMB = 1, /** thumb (left hand) */
47 LEFT_INDEX, /** index finger (left hand) */
48 LEFT_MIDDLE, /** middle finger (left hand) */
49 LEFT_RING, /** ring finger (left hand) */
50 LEFT_LITTLE, /** little finger (left hand) */
51 RIGHT_THUMB, /** thumb (right hand) */
52 RIGHT_INDEX, /** index finger (right hand) */
53 RIGHT_MIDDLE, /** middle finger (right hand) */
54 RIGHT_RING, /** ring finger (right hand) */
55 RIGHT_LITTLE, /** little finger (right hand) */
56 };
57
58 /** \ingroup dev
59 * Numeric codes used to refer to the scan type of the device. Devices require
60 * either swiping or pressing the finger on the device. This is useful for
61 * front-ends.
62 */
63 enum fp_scan_type {
64 FP_SCAN_TYPE_PRESS = 0, /** press */
65 FP_SCAN_TYPE_SWIPE, /** swipe */
66 };
67
68 /* Drivers */
69 const char *fp_driver_get_name(struct fp_driver *drv);
70 const char *fp_driver_get_full_name(struct fp_driver *drv);
71 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
72 enum fp_scan_type fp_driver_get_scan_type(struct fp_driver *drv);
73
74 /* Device discovery */
75 struct fp_dscv_dev **fp_discover_devs(void);
76 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
77 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
78 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
79 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
80 struct fp_print_data *print);
81 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
82 struct fp_dscv_print *print);
83 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
84 struct fp_print_data *print);
85 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
86 struct fp_dscv_print *print);
87
fp_dscv_dev_get_driver_id(struct fp_dscv_dev * dev)88 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
89 {
90 return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
91 }
92
93 /* Print discovery */
94 struct fp_dscv_print **fp_discover_prints(void);
95 void fp_dscv_prints_free(struct fp_dscv_print **prints);
96 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
97 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
98 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
99 int fp_dscv_print_delete(struct fp_dscv_print *print);
100
101 /* Device handling */
102 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
103 void fp_dev_close(struct fp_dev *dev);
104 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
105 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
106 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
107 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
108 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
109
110 /** \ingroup dev
111 * Image capture result codes returned from fp_dev_img_capture().
112 */
113 enum fp_capture_result {
114 /** Capture completed successfully, the capture data has been
115 * returned to the caller. */
116 FP_CAPTURE_COMPLETE = 0,
117 /** Capture failed for some reason */
118 FP_CAPTURE_FAIL,
119 };
120
121 int fp_dev_supports_imaging(struct fp_dev *dev);
122 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
123 struct fp_img **image);
124 int fp_dev_get_img_width(struct fp_dev *dev);
125 int fp_dev_get_img_height(struct fp_dev *dev);
126
127 /** \ingroup dev
128 * Enrollment result codes returned from fp_enroll_finger().
129 * Result codes with RETRY in the name suggest that the scan failed due to
130 * user error. Applications will generally want to inform the user of the
131 * problem and then retry the enrollment stage. For more info on the semantics
132 * of interpreting these result codes and tracking enrollment process, see
133 * \ref enrolling.
134 */
135 enum fp_enroll_result {
136 /** Enrollment completed successfully, the enrollment data has been
137 * returned to the caller. */
138 FP_ENROLL_COMPLETE = 1,
139 /** Enrollment failed due to incomprehensible data; this may occur when
140 * the user scans a different finger on each enroll stage. */
141 FP_ENROLL_FAIL,
142 /** Enroll stage passed; more stages are need to complete the process. */
143 FP_ENROLL_PASS,
144 /** The enrollment scan did not succeed due to poor scan quality or
145 * other general user scanning problem. */
146 FP_ENROLL_RETRY = 100,
147 /** The enrollment scan did not succeed because the finger swipe was
148 * too short. */
149 FP_ENROLL_RETRY_TOO_SHORT,
150 /** The enrollment scan did not succeed because the finger was not
151 * centered on the scanner. */
152 FP_ENROLL_RETRY_CENTER_FINGER,
153 /** The verification scan did not succeed due to quality or pressure
154 * problems; the user should remove their finger from the scanner before
155 * retrying. */
156 FP_ENROLL_RETRY_REMOVE_FINGER,
157 };
158
159 int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
160 struct fp_img **img);
161
162 /** \ingroup dev
163 * Performs an enroll stage. See \ref enrolling for an explanation of enroll
164 * stages. This function is just a shortcut to calling fp_enroll_finger_img()
165 * with a NULL image parameter. Be sure to read the description of
166 * fp_enroll_finger_img() in order to understand its behaviour.
167 *
168 * \param dev the device
169 * \param print_data a location to return the resultant enrollment data from
170 * the final stage. Must be freed with fp_print_data_free() after use.
171 * \return negative code on error, otherwise a code from #fp_enroll_result
172 */
fp_enroll_finger(struct fp_dev * dev,struct fp_print_data ** print_data)173 static inline int fp_enroll_finger(struct fp_dev *dev,
174 struct fp_print_data **print_data)
175 {
176 return fp_enroll_finger_img(dev, print_data, NULL);
177 }
178
179 /** \ingroup dev
180 * Verification result codes returned from fp_verify_finger(). Return codes
181 * are also shared with fp_identify_finger().
182 * Result codes with RETRY in the name suggest that the scan failed due to
183 * user error. Applications will generally want to inform the user of the
184 * problem and then retry the verify operation.
185 */
186 enum fp_verify_result {
187 /** The scan completed successfully, but the newly scanned fingerprint
188 * does not match the fingerprint being verified against.
189 * In the case of identification, this return code indicates that the
190 * scanned finger could not be found in the print gallery. */
191 FP_VERIFY_NO_MATCH = 0,
192 /** The scan completed successfully and the newly scanned fingerprint does
193 * match the fingerprint being verified, or in the case of identification,
194 * the scanned fingerprint was found in the print gallery. */
195 FP_VERIFY_MATCH = 1,
196 /** The scan did not succeed due to poor scan quality or other general
197 * user scanning problem. */
198 FP_VERIFY_RETRY = FP_ENROLL_RETRY,
199 /** The scan did not succeed because the finger swipe was too short. */
200 FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
201 /** The scan did not succeed because the finger was not centered on the
202 * scanner. */
203 FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
204 /** The scan did not succeed due to quality or pressure problems; the user
205 * should remove their finger from the scanner before retrying. */
206 FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
207 };
208
209 int fp_verify_finger_img(struct fp_dev *dev,
210 struct fp_print_data *enrolled_print, struct fp_img **img);
211
212 /** \ingroup dev
213 * Performs a new scan and verify it against a previously enrolled print. This
214 * function is just a shortcut to calling fp_verify_finger_img() with a NULL
215 * image output parameter.
216 * \param dev the device to perform the scan.
217 * \param enrolled_print the print to verify against. Must have been previously
218 * enrolled with a device compatible to the device selected to perform the scan.
219 * \return negative code on error, otherwise a code from #fp_verify_result
220 * \sa fp_verify_finger_img()
221 */
fp_verify_finger(struct fp_dev * dev,struct fp_print_data * enrolled_print)222 static inline int fp_verify_finger(struct fp_dev *dev,
223 struct fp_print_data *enrolled_print)
224 {
225 return fp_verify_finger_img(dev, enrolled_print, NULL);
226 }
227
228 int fp_dev_supports_identification(struct fp_dev *dev);
229 int fp_identify_finger_img(struct fp_dev *dev,
230 struct fp_print_data **print_gallery, size_t *match_offset,
231 struct fp_img **img);
232
233 /** \ingroup dev
234 * Performs a new scan and attempts to identify the scanned finger against a
235 * collection of previously enrolled fingerprints. This function is just a
236 * shortcut to calling fp_identify_finger_img() with a NULL image output
237 * parameter.
238 * \param dev the device to perform the scan.
239 * \param print_gallery NULL-terminated array of pointers to the prints to
240 * identify against. Each one must have been previously enrolled with a device
241 * compatible to the device selected to perform the scan.
242 * \param match_offset output location to store the array index of the matched
243 * gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
244 * returned.
245 * \return negative code on error, otherwise a code from #fp_verify_result
246 * \sa fp_identify_finger_img()
247 */
fp_identify_finger(struct fp_dev * dev,struct fp_print_data ** print_gallery,size_t * match_offset)248 static inline int fp_identify_finger(struct fp_dev *dev,
249 struct fp_print_data **print_gallery, size_t *match_offset)
250 {
251 return fp_identify_finger_img(dev, print_gallery, match_offset, NULL);
252 }
253
254 /* Data handling */
255 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
256 struct fp_print_data **data);
257 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
258 struct fp_print_data **data);
259 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
260 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
261 void fp_print_data_free(struct fp_print_data *data);
262 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
263 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
264 size_t buflen);
265 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
266 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
267
268 /* Image handling */
269
270 /** \ingroup img */
271 struct fp_minutia {
272 int x;
273 int y;
274 int ex;
275 int ey;
276 int direction;
277 double reliability;
278 int type;
279 int appearing;
280 int feature_id;
281 int *nbrs;
282 int *ridge_counts;
283 int num_nbrs;
284 };
285
286 int fp_img_get_height(struct fp_img *img);
287 int fp_img_get_width(struct fp_img *img);
288 unsigned char *fp_img_get_data(struct fp_img *img);
289 int fp_img_save_to_file(struct fp_img *img, char *path);
290 void fp_img_standardize(struct fp_img *img);
291 struct fp_img *fp_img_binarize(struct fp_img *img);
292 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
293 void fp_img_free(struct fp_img *img);
294
295 /* Polling and timing */
296
297 struct fp_pollfd {
298 int fd;
299 short events;
300 };
301
302 int fp_handle_events_timeout(struct timeval *timeout);
303 int fp_handle_events(void);
304 size_t fp_get_pollfds(struct fp_pollfd **pollfds);
305 int fp_get_next_timeout(struct timeval *tv);
306
307 typedef void (*fp_pollfd_added_cb)(int fd, short events);
308 typedef void (*fp_pollfd_removed_cb)(int fd);
309 void fp_set_pollfd_notifiers(fp_pollfd_added_cb added_cb,
310 fp_pollfd_removed_cb removed_cb);
311
312 /* Library */
313 int fp_init(void);
314 void fp_exit(void);
315 void fp_set_debug(int level);
316
317 /* Asynchronous I/O */
318
319 typedef void (*fp_dev_open_cb)(struct fp_dev *dev, int status, void *user_data);
320 int fp_async_dev_open(struct fp_dscv_dev *ddev, fp_dev_open_cb callback,
321 void *user_data);
322
323 typedef void (*fp_dev_close_cb)(struct fp_dev *dev, void *user_data);
324 void fp_async_dev_close(struct fp_dev *dev, fp_dev_close_cb callback,
325 void *user_data);
326
327 typedef void (*fp_enroll_stage_cb)(struct fp_dev *dev, int result,
328 struct fp_print_data *print, struct fp_img *img, void *user_data);
329 int fp_async_enroll_start(struct fp_dev *dev, fp_enroll_stage_cb callback,
330 void *user_data);
331
332 typedef void (*fp_enroll_stop_cb)(struct fp_dev *dev, void *user_data);
333 int fp_async_enroll_stop(struct fp_dev *dev, fp_enroll_stop_cb callback,
334 void *user_data);
335
336 typedef void (*fp_verify_cb)(struct fp_dev *dev, int result,
337 struct fp_img *img, void *user_data);
338 int fp_async_verify_start(struct fp_dev *dev, struct fp_print_data *data,
339 fp_verify_cb callback, void *user_data);
340
341 typedef void (*fp_verify_stop_cb)(struct fp_dev *dev, void *user_data);
342 int fp_async_verify_stop(struct fp_dev *dev, fp_verify_stop_cb callback,
343 void *user_data);
344
345 typedef void (*fp_identify_cb)(struct fp_dev *dev, int result,
346 size_t match_offset, struct fp_img *img, void *user_data);
347 int fp_async_identify_start(struct fp_dev *dev, struct fp_print_data **gallery,
348 fp_identify_cb callback, void *user_data);
349
350 typedef void (*fp_identify_stop_cb)(struct fp_dev *dev, void *user_data);
351 int fp_async_identify_stop(struct fp_dev *dev, fp_identify_stop_cb callback,
352 void *user_data);
353
354 typedef void (*fp_capture_cb)(struct fp_dev *dev, int result,
355 struct fp_img *img, void *user_data);
356 int fp_async_capture_start(struct fp_dev *dev, int unconditional, fp_capture_cb callback, void *user_data);
357
358 typedef void (*fp_capture_stop_cb)(struct fp_dev *dev, void *user_data);
359 int fp_async_capture_stop(struct fp_dev *dev, fp_capture_stop_cb callback, void *user_data);
360
361 #ifdef __cplusplus
362 }
363 #endif
364
365 #endif
366
367