WDF Custom Driver Design Pattern

1. WDF Custom Driver Design Pattern Peter wieland Software Design Engineer

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

3. 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())

4. WDF Custom Driver Pattern • 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 • Example + + + app meta Device Device driver Metro style app Device metadata

5. Components • Device • 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

6. Components • 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 Device driver

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

8. Components meta • 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 • Device Metadata Device metadata

9. 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

10. 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)

11. Sample Walkthrough

12. 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