Initialisation and events handling

Initialisation and events handling — Initialisation and events handling functions

Functions

Types and Values

Includes

#include <fprint.h>

Description

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.

Functions

fp_set_debug ()

void
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.

Parameters

level

the verbosity level

 

fp_init ()

int
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.

Example:

LIBUSB_DEBUG=4 G_MESSAGES_DEBUG=all my-libfprint-application

Returns

0 on success, non-zero on error.


fp_exit ()

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

int
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.

Parameters

timeout

Maximum timeout for this blocking function

 

Returns

0 on success, non-zero on error.


fp_handle_events ()

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

Returns

0 on success, non-zero on error.


fp_get_next_timeout ()

int
fp_get_next_timeout (struct timeval *tv);

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

Parameters

tv

a timeval structure containing the duration to the next timeout.

 

Returns

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


fp_get_pollfds ()

ssize_t
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.

Parameters

pollfds

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

 

Returns

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


fp_pollfd_added_cb ()

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

Parameters

fd

the new file descriptor

 

events

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

 

fp_pollfd_removed_cb ()

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

Parameters

fd

the file descriptor to stop monitoring

 

fp_set_pollfd_notifiers ()

void
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.

Parameters

added_cb

a fp_pollfd_added_cb callback or NULL

 

removed_cb

a fp_pollfd_removed_cb callback or NULL

 

Types and Values

LIBFPRINT_DEPRECATED

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

Members

int fd;

a file descriptor

 

short int events;

Event flags to poll for from <poll.h>