Edit

Supporting Biometric IOCTL Calling Sequence

  • Article

WBDI is a Windows standard IOCTL-based interface. When you write a WBDI driver, you must support a set of mandatory IOCTLs. You may additionally choose to support optional IOCTLs. You can find a complete list of mandatory and optional IOCTLs in Biometric IOCTLs.

A vendor-supplied WBDI driver should be prepared to receive IOCTL requests in the following order from the Windows Biometric Service (WBS). You can review examples of handlers for these IOCTLs in Device.cpp in WudfBioUsbSample.

  1. The Windows Biometric Service or the sensor adapter initializes the biometric device and verifies that it is ready for use. The service or adapter sends an IOCTL_BIOMETRIC_GET_ATTRIBUTES request.

    The driver receives a pointer to a WINBIO_SENSOR_ATTRIBUTES structure. In the handler for this IOCTL, the driver should fill in the relevant members of this structure and complete the request by calling IWDFIoRequest::Complete.

  2. Next, the driver receives IOCTL_BIOMETRIC_GET_SENSOR_STATUS. The driver should fill in the relevant members of the WINBIO_DIAGNOSTICS structure and complete the request.

  3. If the driver indicates that calibration is necessary in the SensorStatus member of the WINBIO_DIAGNOSTICS structure that was returned from the IOCTL_BIOMETRIC_GET_SENSOR_STATUS request, the driver next receives an IOCTL_BIOMETRIC_CALIBRATE request. The driver must provide a handler for this IOCTL. After calibrating the device, the callback should return a WINBIO_CALIBRATION_INFO structure.

  4. The driver can now expect to receive IOCTL_BIOMETRIC_CAPTURE_DATA requests. Because only one capture can be pending at any time, the handler for this request should first confirm that no request is pending. If a request is pending, complete the request with WINBIO_E_DATA_COLLECTION_IN_PROGRESS.

    The WinBio service or an application can request cancellation of an outstanding capture request at any time by calling Win32 cancellation routines such as CancelIo, CancelIoEx, or CancelSynchronousIo. As such, WBDI drivers must also support cancellation.

    The driver handles cancellation by calling IWDFIoRequest::MarkCancelable to register an IRequestCallbackCancel interface.

    The handler then programs the device for capture mode and returns from the callback. The request should remain pending until canceled or the driver detects that capture is complete. After this I/O request is completed, the device can return to an idle state. A client may make an initial call to IOCTL_BIOMETRIC_CAPTURE_DATA to determine the correct buffer size for an actual capture.

  5. The handler for IOCTL_BIOMETRIC_RESET should physically reset the device to a known or idle state. The handler for this request must also cancel any pending data collection I/O and fill out the WINBIO_BLANK_PAYLOAD structure. The handler then completes the request. Clients do not need to call reset between calls to IOCTL_BIOMETRIC_CAPTURE_DATA.