Initialisation and events handling

Initialisation and events handling — Initialisation and events handling functions


Types and Values


#include <fprint.h>


These functions are only applicable to users of libfprint's asynchronous API.

libfprint does not create internal library threads and hence can only execute when your application is calling a libfprint function. However, libfprint often has work to be do, such as handling of completed USB transfers, and processing of timeouts required in order for the library to function. Therefore it is essential that your own application must regularly "phone into" libfprint so that libfprint can handle any pending events.

The function you must call is fp_handle_events() or a variant of it. This function will handle any pending events, and it is from this context that all asynchronous event callbacks from the library will occur. You can view this function as a kind of iteration function.

If there are no events pending, fp_handle_events() will block for a few seconds (and will handle any new events should anything occur in that time). If you wish to customise this timeout, you can use fp_handle_events_timeout() instead. If you wish to do a non-blocking iteration, call fp_handle_events_timeout() with a zero timeout.

How to integrate events handling depends on your main loop implementation. The sister fprintd project includes an implementation of main loop handling that integrates into GLib's main loop. The libusb documentation also includes more details about how to integrate libfprint events into your main loop.


fp_set_debug ()

fp_set_debug (int level);

fp_set_debug is deprecated and should not be used in newly-written code.

This call does nothing, see fp_init() for details.



the verbosity level


fp_init ()

fp_init (void);

Initialise libfprint. This function must be called before you attempt to use the library in any way.

To enable debug output of libfprint specifically, use GLib's G_MESSAGES_DEBUG environment variable as explained in Running and debugging GLib Applications.

The log domains used in libfprint are either libfprint or libfprint-FP_COMPONENT where FP_COMPONENT is defined in the source code for each driver, or component of the library. Starting with all and trimming down is advised.

To enable debugging of libusb, for USB-based fingerprint reader drivers, use libusb's LIBUSB_DEBUG environment variable as explained in the libusb-1.0 API Reference.


LIBUSB_DEBUG=4 G_MESSAGES_DEBUG=all my-libfprint-application


0 on success, non-zero on error.

fp_exit ()

fp_exit (void);

Deinitialise libfprint. This function should be called during your program exit sequence. You must not use any libfprint functions after calling this function, unless you call fp_init() again.

fp_handle_events_timeout ()

fp_handle_events_timeout (struct timeval *timeout);

Handle any pending events. If a non-zero timeout is specified, the function will potentially block for the specified amount of time, although it may return sooner if events have been handled. The function acts as non-blocking for a zero timeout.



Maximum timeout for this blocking function



0 on success, non-zero on error.

fp_handle_events ()

fp_handle_events (void);

Convenience function for calling fp_handle_events_timeout() with a sensible default timeout value of two seconds (subject to change if we decide another value is more sensible).


0 on success, non-zero on error.

fp_get_next_timeout ()

fp_get_next_timeout (struct timeval *tv);

A zero filled tv timeout means events are to be handled immediately



a timeval structure containing the duration to the next timeout.



returns 0 if no timeouts active, or 1 if timeout returned.

fp_get_pollfds ()

fp_get_pollfds (struct fp_pollfd **pollfds);

Retrieve a list of file descriptors that should be polled for events interesting to libfprint. This function is only for users who wish to combine libfprint's file descriptor set with other event sources – more simplistic users will be able to call fp_handle_events() or a variant directly.



output location for a list of pollfds. If non-NULL, must be released with free() when done.



the number of pollfds in the resultant list, or negative on error.

fp_pollfd_added_cb ()

(*fp_pollfd_added_cb) (int fd,
                       short int events);

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().



the new file descriptor



events to monitor for, see <poll.h> for the possible values


fp_pollfd_removed_cb ()

(*fp_pollfd_removed_cb) (int fd);

Type definition for a function that will be called when an event source is removed. See fp_set_pollfd_notifiers().



the file descriptor to stop monitoring


fp_set_pollfd_notifiers ()

fp_set_pollfd_notifiers (fp_pollfd_added_cb added_cb,
                         fp_pollfd_removed_cb removed_cb);

This sets the callback functions to call for every new or removed file descriptor used as an event source.



a fp_pollfd_added_cb callback or NULL



a fp_pollfd_removed_cb callback or NULL


Types and Values


#define LIBFPRINT_DEPRECATED __attribute__((__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.

struct fp_pollfd

struct fp_pollfd {
	int fd;
	short int events;

A structure representing a file descriptor and the events to poll for, as returned by fp_get_pollfds().


int fd;

a file descriptor


short int events;

Event flags to poll for from <poll.h>