Grabba Driver for Android
Unified driver for Grabba devices on the Android operating system
FingerprintListener Class Reference

Description

Base class for receiving events related to the fingerprint reader on a Grabba device.

The following events are supported by this class:

  • completionEvent - an asynchronous fingerprint operation (e.g. capture) completed successfully
  • errorEvent - an asynchronous fingerprint operation encountered an error (e.g. loss of connection)
  • imageEvent - a fingerprint image was received by the driver from the fingerprint reader hardware
  • templateEvent - a fingerprint template was received by the driver from the fingerprint reader hardware
  • userMessageEvent - a user message was received by the driver from the fingerprint reader hardware

Each event may invoke callbacks in two ways:

  • Subclassing - the relevant event methods (e.g. completionEvent) are called directly
    • This approach is recommended wherever feasible, due to its simplicity
    • To use it, create an object of a suitable subclass, which overrides the desired event method(s)
  • Delegation - event methods trigger method calls for a delegate object
    • This approach is only recommended when the callback handler must inherit from a different base class
    • To use it, create an object of this class, create an object of a class which implements FingerprintInterface, then call setDelegate() to provide the necessary linkage.
Note
Delegation will be disabled for an event if that event's method is subclassed, unless the subclass calls the superclass' equivalent method from within its override thereof.

By default, each listener object will receive event notifications from the driver for its entire lifetime; the enable() and disable() methods may be used if control is required over whether notifications are received.

The default behaviour for each event, if not overridden, on an enabled listener object is as follows:

  • If setDelegate() has not been called, then take no action
  • If the last call to setDelegate() accepted a null reference, then take no action
  • If the last call to setDelegate() accepted a non-null object reference, then delegate to that object

Overrides need not call the superclass' equivalent method unless it is necessary to preserve the delegation (i.e. to support both subclassing and delegation from a single object).

Thread safety: This class is intended to be thread-safe; any classes deriving from it should ensure that the relevant methods are callable from any thread.

See also
FingerprintAPI for related API functions
Inheritance diagram for FingerprintListener:
Listener< Delegate > FingerprintInterface

Public Member Functions

 FingerprintListener ()
 Default constructor - builds a listener object then enables receipt of events from the driver.
 
 FingerprintListener (boolean startEnabled)
 Constructor - builds a listener object then optionally enables receipt of events from the driver. More...
 
void completionEvent ()
 Callback which is invoked when an asynchronous fingerprint operation completes successfully. More...
 
final void disable ()
 Disable receipt of events from the driver by this object. More...
 
final void enable ()
 Enable receipt of events from the driver by this object. More...
 
void errorEvent (@NonNull ErrorCode error)
 Callback which is invoked when an asynchronous fingerprint operation fails to complete. More...
 
void imageEvent (@NonNull FingerprintImage image)
 Callback which is invoked when fingerprint image data is returned. More...
 
final void setDelegate (Delegate newDelegate)
 Set the delegate which will receive event callbacks if default listener behaviour is not overridden. More...
 
void templateEvent (@NonNull FingerprintTemplate templ)
 Callback which is invoked when fingerprint template data is returned. More...
 
void userMessageEvent (@NonNull FingerprintUserMessage message)
 Callback which is invoked when there is a user message to display. More...
 

Constructor & Destructor Documentation

◆ FingerprintListener()

FingerprintListener ( boolean  startEnabled)

Constructor - builds a listener object then optionally enables receipt of events from the driver.

Parameters
startEnabledIf set, the listener object is enabled immediately (equivalent of default constructor), otherwise it is disabled until the first call to enable()

Member Function Documentation

◆ completionEvent()

void completionEvent ( )

Callback which is invoked when an asynchronous fingerprint operation completes successfully.

Each asynchronous operation will trigger either this or errorEvent (but not both) immediately prior to termination, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note
Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

Implements FingerprintInterface.

◆ disable()

final void disable ( )
inherited

Disable receipt of events from the driver by this object.

This has no effect if the object was already disabled.

◆ enable()

final void enable ( )
inherited

Enable receipt of events from the driver by this object.

This has no effect if the object was already enabled.

◆ errorEvent()

void errorEvent ( @NonNull ErrorCode  error)

Callback which is invoked when an asynchronous fingerprint operation fails to complete.

Each asynchronous operation will trigger either this or completionEvent (but not both) immediately prior to termination, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note
Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.
Parameters
errorDetails of the error which was detected

Implements FingerprintInterface.

◆ imageEvent()

void imageEvent ( @NonNull FingerprintImage  image)

Callback which is invoked when fingerprint image data is returned.

This event will be triggered by the driver when a fingerprint image is received by the driver, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note
Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.
Parameters
imageCaptured fingerprint image data, plus associated metadata

Implements FingerprintInterface.

◆ setDelegate()

final void setDelegate ( Delegate  newDelegate)
inherited

Set the delegate which will receive event callbacks if default listener behaviour is not overridden.

Delegation may alternatively be disabled by providing a null reference here.

Parameters
newDelegateIf null, disables delegation; if non-null, enables delegation and sets the delegate to the supplied object.

◆ templateEvent()

void templateEvent ( @NonNull FingerprintTemplate  templ)

Callback which is invoked when fingerprint template data is returned.

This event will be triggered by the driver when a fingerprint template is received, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note
Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.
Parameters
templCaptured fingerprint template data, plus associated metadata

Implements FingerprintInterface.

◆ userMessageEvent()

void userMessageEvent ( @NonNull FingerprintUserMessage  message)

Callback which is invoked when there is a user message to display.

This event will be triggered by the driver when a user message is generated by the driver, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note
Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.
Parameters
messageMessage which needs to be displayed

Implements FingerprintInterface.