Initialisation and events handling: libfprint Reference Manual

## Initialisation and events handling Initialisation and events handling |

## Functions

void | fp_set_debug ()
int | fp_init ()
void | fp_exit ()
int | fp_handle_events_timeout ()
int | fp_handle_events ()
int | fp_get_next_timeout ()
ssize_t | fp_get_pollfds ()
void | (*fp_pollfd_added_cb) ()
void | (*fp_pollfd_removed_cb) ()
void | fp_set_pollfd_notifiers ()

## Types and Values

struct | fp_pollfd

## 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 events Param2);

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

### struct fp_pollfd

    struct fp_pollfd {
    	int fd;
    	short 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 |