WDF Custom Driver Design Pattern Peter wieland Software Design Engineer

Agenda What is the WDF Custom Driver Pattern? Example Components Device Custom Driver App Device Metadata Design Guidance Questions & Code Walkthrough

WDF Custom Driver Pattern A device, such as a USB attached device, that doesn't fit into any of the other patterns. Protocols: Any. A custom device driver provides access to the device from the app Access Model: Restricted API: Device Access: (CreateDeviceAccessInstance(), IDeviceIoControl()) Advantages Disadvantages Can meet needs of the broadest range of devices Requires development, certification & maintenance of a custom device driver Vendor controls which Metro style apps access their device Only vertical solutions are supported, and only a small # of apps can have privileged access to the device Existing custom drivers can be easily adapted for this pattern This is the most complicated pattern with the most components and moving parts. Communications between app and driver must be written in C++ Not supported for external devices on WinRT

WDF Custom Driver Pattern Example Custom USB Device : USB credit-card reader with app to perform CC transactions Acquisition Scenarios: Automatic Acquisition, Windows Store Download Device Discovery: Windows.Devices.Enumeration Device Access: CreateDeviceAccessInstance(), IDeviceIoControl Device Device driver Device metadata Metro style app + meta app

Components Custom WDF Driver pattern can be applied to any device Other patterns may be a better fit, depending on the device Device must have a unique hardware ID Device must be pass Windows Hardware Certification For use with real, external devices Not software or virtualized devices Device

Components Written using Windows Driver Framework (WDF) Device Driver Written using Windows Driver Framework (WDF) Driver can be user-mode or kernel-mode WDF driver See Using the Windows Driver Framework to build better drivers Driver provides communications between app & device Registers a custom device interface for the app to open Sets restricted property on interface to grant privileged app access App sends I/O controls to the driver to control device Driver should be signed and deployed to Windows Update Custom driver can use other drivers to talk to device e.g. USB HID drivers Device driver

Components app Declares the custom device interface class as a device capability in app manifest Discovers device interface using DeviceInformation’s FindAllAsync() method Opens a handle to the device using CreateDeviceAccessInstance() Communicates with device using IDeviceIoControl interface Last two steps can only be done in C++ code Recommend creating a C++ WinRT component for this app Metro style app

meta Components For the purposes of a device app, Device Metadata: Declares your app as a privileged app Set AccessCustomDriver attribute to “true” Declares your app as an automatically acquired app for the device Permission applies to the device container App can access any restricted interface it has declared access to in the container meta Device metadata

Design Guidance Authoring the Device Driver Write custom drivers in user-mode WDF where possible Drivers must be certified with the Windows Hardware Certification Kit (WHCK) Check Windows Hardware Certification requirements for your device type May want to create new device interface specifically for device app Can provide different capabilities to admin running desktop app vs. normal user running device app Many existing device interfaces assume administrator access App to driver interface can only use IOCTLs

Updating with Custom WDF Pattern Loose coupling between app, device metadata, and drivers. Components are distributed through different services with update rhythms: App updates – Available sometime after acceptance. Users are notified of an update and must initiate update. Device metadata updates – 2 days after acceptance, auto-download within 8 days Driver updates – available sometime after acceptance. Driver notification & update dependent on Windows Update client settings. Components need to behave gracefully when all proper components are not present. (maintain forward and backward compatibility)

Sample Walkthrough

Summary Very flexible in terms of devices supported Only supports restricted app model Certified custom driver makes this a costly pattern Beware of compatibility between components