1. Developing WIA Drivers Byron Changuion Developer Windows Imaging Group Microsoft Corporation

3. Preamble What is this presentation about? What is this presentation about?  Selected topics regarding development of WIA mini-drivers (“full” WIA drivers) This talk is not necessary for you, if your device is: This talk is not necessary for you, if your device is:  PTP camera or Mass Storage device  Class driver exists  Simple flatbed scanner  Can write “micro-driver” instead

4. Agenda Overview of WIA Components Overview of WIA Components WIA Item Trees WIA Item Trees Run-time behavior of WIA Drivers Run-time behavior of WIA Drivers Troubleshooting and Debugging Troubleshooting and Debugging Hints and Tips Hints and Tips What can you do next? What can you do next?

5. WIA Component Architecture Processboundary STI Interface WIA / STI service TWAIN Data Source Microsoft Component IHV Component ISV Component Key USB Driver 1394 Driver SCSI Driver Serial Driver USD WIA Application User Mode Kernel Mode USD TWAIN Application COM Proxy Default UI Optional vendor UI

6. WIA Item Trees General Device (and any data) represented by “Items” Device (and any data) represented by “Items” Two kinds of items Two kinds of items  Driver items and Application items Driver creates tree of Driver items Driver creates tree of Driver items WIA Service will build copy of tree for applications (using Application items) WIA Service will build copy of tree for applications (using Application items)

7. WIA Item Trees General RootIWiaItem Second Child IWiaItem First Child IWiaItem Application 2 RootIWiaItem Second Child IWiaItem First Child IWiaItem Application 1 RootIWiaDrvItem Second Child IWiaDrvItem First Child IWiaDrvItem WIA Driver

8. WIA Item Trees General Each Application item has its own property stream Each Application item has its own property stream Service will call driver to set initial property values Service will call driver to set initial property values Driver notified when Application reads/writes properties Driver notified when Application reads/writes properties

9. WIA Item Trees Item Types Informs applications how to treat an item Informs applications how to treat an item  For example, WiaItemTypeAudio Item types are not exclusive Item types are not exclusive  For example, (WiaItemTypeFile | WiaItemTypeImage) Driver specifies item type when it creates the item Driver specifies item type when it creates the item

10. WIA Item Trees Annotations Some data may be associated with other data Some data may be associated with other data  Example: Audio recording for a picture WIA represents annotations with child-items WIA represents annotations with child-items Items with annotations have special item type flags Items with annotations have special item type flags

11. WIA Item Trees Annotations: Example Audio Annotation for Picture 1 (WiaItemTypeFile | WiaItemTypeAudio) Picture 1 (WiaItemTypeFile | WiaItemTypeImage) Picture 2 (WiaItemTypeFile | WiaItemTypeImage) Audio Annotation for Picture 1 (WiaItemTypeFile | WiaItemTypeAudio) Picture 1 (WiaItemTypeFile | WiaItemTypeImage | WiaItemTypeHasAttachments) Picture 2 (WiaItemTypeFile | WiaItemTypeImage) Data on Device WIA Item tree Representation

12. WIA Item Trees Interactions with Driver Image data exposed through items Image data exposed through items Characteristics exposed through properties, for example Characteristics exposed through properties, for example  Cameras  Picture width / height, Time picture was taken, and so on  Scanners  Set resolution, Set data type, and so on

13. WIA Item Trees Interactions with Driver Microsoft Component IHV Component ISV Component KeyWIA Driver Application Read Property X drvReadItemProperties If needed, return new value for X Current value for X WIA updates property storage Reading Property Example

14. WIA Item Trees Interactions with Driver: Example Walk through sample code Walk through sample code

15. WIA Item Trees Interactions with Driver WIA Driver Application Write Property X 1.drvValidateItemProperties Return appropriate error code 2.Driver updates dependant properties 3.Driver calls generic property validation helper 4.Helper returns error 5.Driver returns error WIA performs rollback by restoring property stream Writing Invalid Property Example Microsoft Component IHV Component ISV Component Key

16. Run-Time Behavior Updating the Driver Tree Drivers may add and/or remove WIA items, for example Drivers may add and/or remove WIA items, for example  Take picture  Delete picture Need to let applications know Need to let applications know  Use WIA events, for example  WIA_EVENT_ITEM_CREATED  WIA_EVENT_ITEM_DELETED  WIA_EVENT_TREE_UPDATED

17. Run-Time Behavior Updating the Driver Tree: Example Walk through sample code Walk through sample code

18. Run-Time Behavior drvInitializeWia / drvUnitializeWia Used to bracket application sessions Used to bracket application sessions Similar to AddRef / Release Similar to AddRef / Release  Can use to maintain session Reference Count  Multiple drvInitializeWia calls can be made before the equivalent drvUninitializeWia calls (i.e., can more than one active session)

19. Run-Time Behavior drvInitializeWia / drvUnitializeWia: Example Walk through sample code Walk through sample code

20. Run-Time Behavior drvNotifyPnPEvent Called Asynchronously Called Asynchronously Plug and Play Plug and Play  WIA_EVENT_DEVICE_CONNECTED  WIA_EVENT_DEVICE_DISCONNECTED Power Management Power Management  WIA_EVENT_POWER_SUSPEND  WIA_EVENT_POWER_RESUME I/O Cancellation I/O Cancellation  WIA_EVENT_CANCEL_IO

21. Run-Time Behavior drvNotifyPnPEvent: Example Walk through sample code Walk through sample code

22. Troubleshooting WIA Service Log file WIA Service Log file  %windir%\wiadebug.log  Turn on Warnings and Errors:  [HKLM\System\CurrentControlSet\Control\ StillImage\Debug\wiaservc.dll]  “DebugFlags = 0x3” Example snippet: Example snippet: wiasValidateItemProperties, invalid RANGE value for : (propID) Horizontal Start Position, value = 3000 (propID) Horizontal Start Position, value = 3000 Valid RANGE is: MIN = 0, MAX = 1274, STEP = 1

23. Debugging Overview Why use a debugger? Why use a debugger?  Driver faults (without debugger - service will catch and simply return “failed”)  Service faults (without debugger – service process is terminated) When do you start the debugger? When do you start the debugger?  Automatically on startup  Attach at run-time

24. Debugging

25. Hints And Tips USD does not show U.I.! USD does not show U.I.! Multiple instances of driver when using STI Multiple instances of driver when using STIProcessboundary STI Interface WIA / STI service TWAIN Data Source Microsoft Component IHV Component ISV Component Key USB Driver 1394 Driver SCSI Driver Serial Driver USD WIA Application User Mode Kernel Mode USD TWAIN Application COM Proxy Default UI Optional vendor UI

26. Hints And Tips IWiaMiniDrv portion of driver only initialized and/or used when application talks WIA IWiaMiniDrv portion of driver only initialized and/or used when application talks WIA drvInitializeWia / drvUnitializeWia not used to indicate driver loading or unloading drvInitializeWia / drvUnitializeWia not used to indicate driver loading or unloading Use WIA’s pre-defined Event GUIDs for Scan, Fax, and so on Use WIA’s pre-defined Event GUIDs for Scan, Fax, and so on

27. What Can You Do Next Reference the platform SDK/DDK Reference the platform SDK/DDK For more technical details about WIA driver development For more technical details about WIA driver development  http://www.microsoft.com/hwdev/wia http://www.microsoft.com/hwdev/wia For information about WHQL testing For information about WHQL testing  http://www.microsoft.com/hwtest http://www.microsoft.com/hwtest Send e-mail to Send e-mail to  winimage@microsoft.com winimage@microsoft.com