Fingerprint driver development in Windows(3)
Following the last two articles…
7. Managing Queues in a WBDI Driver
WBDI drivers should create at least one queue to handle multiple concurrent requests from the service. If you are using UMDF, you can take advantage of its queue management support.
In WudfBioUsbSample, the CBiometricIoQueue class implements the I/O queue interface.
In the method
CBiometricIoQueue::Initialize, specifically, the driver queries the owning
CBiometricIoQueue object for a pointer to the
IQueueCallbackDeviceIoControl interface that the framework uses to determine the event callback functions that the driver subscribes to on the queue:
Then the driver calls
IWDFDevice::CreateIoQueue to configure the default I/O queue:
The call specifies
WdfIoQueueDispatchParallel so that the framework will present requests to the driver’s I/O queue callback functions as soon as the requests are available.
Next, the driver calls
IWDFDevice::ConfigureRequestDispatching to configure the queue to filter all Device I/O requests:
Because the driver specifies
WdfRequestDeviceIoControl in this call, it provides an OnDeviceIoControl handler to process I/O notifications from the framework. It does this in the
IQueueCallbackDeviceIoControl::OnDeviceIoControl method that is part of the “unknown” parameter in the call to
There can only be one outstanding
IOCTL_BIOMETRIC_CAPTURE_DATA request at a time. The driver should track
IOCTL_BIOMETRIC_CAPTURE_DATA requests, either by internally keeping a pointer to the pending requests or by using another framework queue to handle those requests.
In the sample, if there is a pending I/O request, the sample maintains a pointer to the request in a member of the CBiometricDevice class, as defined in Device.h:
While one sensor data collection I/O is pending, subsequent calls to the data collection IOCTLs should fail:
When a capture request is completed or canceled, this value is set to NULL:
8. Installing a Biometric Driver
Vendors can provide an INF file to install a WBDI driver.
The following is a list of guidelines for biometric device installation. The code examples in this topic are taken from the
WudfBioUsbSample.inx file of the WudfBioUsbSample:
- WBDI drivers should specify a class of “Biometric.” Set ClassGuid equal to the value that corresponds to
- In your .HW section, provide AddReg directives to specify three sections that contain entries to be added to the registry:
- Provide the named sections referred to in the.HW section. The
[Biometric_Device_AddReg]section sets values for the biometric device, including the exclusive flag and system wake/device idle. To be recognized by Windows Biometric Framework, UMDF-based WBDI drivers must set the “Exclusive” value to 1. The first two lines of the
[Biometric_Device_AddReg]section specify access control list (ACL) rights so that the device can only be opened by an administrator or the local system account. When you specify these ACL rights, third-party applications cannot open the device and capture fingerprint data when the WinBio service is not running. For example:
A WBDI driver that exposes functionality to a legacy (non-WBDI) biometric stack should set the Exclusive value to zero. If this value is set to zero, the Windows Biometric Framework does not attempt to control the device and the device is not exposed through WBF.
Vendors can have a single driver binary that can work with legacy stacks and WBF, but the two cannot operate simultaneously. WBF will only operate if the device can be opened with exclusive access.
- The second named section contains registry values for the plug-in adapters. The sample uses the Microsoft-provided sensor adapter and storage adapter. This section also enables Windows log-in support by setting the SystemSensor value:
- Finally, the third section sets the following registry values for the database service. The identifying GUID must be unique for each vendor database of a certain format. For instance, in this code example from the sample, change
6E9D4C5A-55B4-4c52-90B7-DDDC75CA4D50to your own unique GUID in your INF file.
For information about INX files and how they differ from INF files, see Using INX Files to Create INF Files.
9. Creating a Device Interface for a WBDI Driver
After the device callback object has been initialized and returned to the driver, at the time of queue setup, the driver should create a device interface instance for the biometric device.
Specifically, WBDI drivers must expose the
GUID_DEVINTERFACE_BIOMETRIC_READER device interface by calling
This call is followed by a call to
A WBDI driver that wants to expose functionality to a legacy (non-WBDI) biometric stack should expose another device interface for legacy applications and make sure that the Exclusive value is set to zero in the INX file that installs the legacy stack.
GUID_DEVINTERFACE_BIOMETRIC_READER device interface causes the WBF service to enumerate the driver only. If Exclusive mode is not set, WBF does not attempt to open and control the device.
Alternatively, the driver could detect internally that it is in legacy mode and then not expose the
GUID_DEVINTERFACE_BIOMETRIC_READER device interface.