Chapter 9 236 the example, this value is USB\VID_0925&PID_1456. The hardware ID con- tains the Vendor ID (0925h) and Product ID (1456h) from the device descrip- tor in the device. The KmdfLibraryVersion directive specifies a version number for the KMDF library, which provides redistributable co-installer files used in installing the driver. The version number can vary with the WDK build and must match the version of the framework library used to develop the driver. The files WdfCoInstaller01007.dll and WUDFUpdate_01007.dll also incorporate the ver- sion number in their names and change with the library version. Chapter 14 has more about these files. In the Dev_AddReg section, a WinUSB device should have a vendor-defined device interface GUID as described in Chapter 8. The Strings section can provide device-specific strings for the company name, descriptions of the device and the driver service, and a name for the installation media. A catalog file contains cryptographic hash values that function as digital thumbprints that identify the files in a driver package. The catalog file can also contain a digital signature that the operating system uses to determine whether the driver files have been altered since the signature was created. You can create an unsigned catalog file with the Inf2Cat tool in the WDK. Chapter 17 has more about digital signatures. The example INF file includes a commented-out reference to the file MyCatFile.cat. 7UKPI&GXKEG+FGPVKHKECVKQP5VTKPIU To identify possible drivers for a device, Windows searches the system’s INF files for a device identification string that matches a string created from infor- mation in the device’s descriptors. Types of device identification strings include hardware IDs and compatible IDs. +FGPVKHKECVKQP5VTKPIU1DVCKPGFHTQOC&GXKEG Every USB device has a device ID, which is a hardware ID that the hub driver creates from the Vendor ID, Product ID, bcdDevice, and as appropriate, other values in the device descriptor. When assigning a driver, the device ID is the best match. A device ID for a USB device has this form: USB\Vid_xxxx&Pid_yyyy&Rev_zzzz Matching a Driver to a Device 237 The values in xxxx, yyyy, and zzzz are four characters each, with xxxx = idVendor, yyyy = idProduct, and zzzz = bcdDevice. The xxxx and yyyy values are hexadecimal except for Windows Me, which uses decimal, and zzzz is in BCD format. For example, a device with Vendor ID = 0925h, Product ID = 1234h, and bcd- Device = 0310 has this device ID: USB\Vid_0925&Pid_1234&Rev_0310 Composite devices can specify a driver for each function. In this case, the device has a device ID for each interface that represents a function. A device ID for an interface has this form: USB\Vid_xxxx&Pid_yyyy&Rev_zzzz&MI_ww The 2-character value in ww equals bInterfaceNumber in the interface descrip- tor for one of the device’s interfaces. A HID-class device whose report descriptor contains more than one top-level collection can have a device ID for each collection. A device ID for a collection has this form with bb indicating the collection number: USB\Vid_xxxx&Pid_yyyy&Rev_zzzz&MI_ww&Colbb In addition to a device ID, some drivers create one or more hardware IDs and compatible IDs for devices. A hardware ID has a similar format to a device ID but represents a less precise match. For example, the ID may omit the bcdDe- vice value: USB\Vid_xxxx&Pid_yyyy A hardware ID for a CDC device can use a Cdc_ value to specify a subclass. This device ID specifies CDC subclass 08h (WMC wireless handset control model): USB\Vid_0925&Pid_0902&Rev_0210&Cdc_08 A compatible ID identifies a device by class and optional subclass and protocol codes and may have any of the following forms: USB\Class_aa&SubClass_bb&Prot_cc USB\Class_aa&SubClass_bb USB\Class_aa The values aa, bb, and cc match values in the device descriptor or an interface descriptor and are two characters each: aa is bDeviceClass or bInterfaceClass, bb is bDeviceSubclass or bInterfaceSubclass, and cc is bDeviceProtocol or bInterfaceProtocol. The values are expressed in hexadecimal, except for Win- dows Me, which uses decimal. Chapter 9 238 For example, the class code for HIDs is 03h, so HID-class devices have the fol- lowing compatible ID: USB\Class_03 Mass-storage devices and printers have additional class-specific compatible IDs defined in the WDK documentation. A compatible ID in an INF file indicates a less desirable but acceptable match. Compatible IDs enable Windows to find and load a driver if the installation can’t find an INF file with a matching device ID. A vendor’s INF file should not contain a compatible ID. 1DVCKPKPI+FGPVKHKECVKQP5VTKPIUHTQOCP+0((KNG In an INF file, each entry in a Models section has one or more hardware IDs. The first hardware ID should be a device ID. Following the device ID may be one or more hardware and compatible IDs separated by commas. (KPFKPIC/CVEJ In looking for the best match between the information retrieved from a device and the information in INF files, the installer assigns a rank to every possible match, with a lower numerical value indicating a better match. NT-based Win- dows editions give more favorable ranks to signed drivers, and 64-bit Windows editions require signed drivers. Windows 98 doesn’t check for signed drivers. A signed driver has a catalog file with a digital signature that indicates that the driver has passed Windows Hardware Quality Labs (WHQL) testing. Chapter 17 has more about WHQL testing. The best match is a device ID that matches a hardware ID in a signed driver’s INF file. An installer that can’t find a match starts the Found New Hardware wizard and gives the user a chance to specify a location to look for the INF file. Composite devices, which have multiple interfaces, are a special case. Because each interface may require a different driver, selecting a driver using only the Vendor ID and Product ID isn’t sufficient. Windows XP and later can use the compatible ID USB\COMPOSITE, which loads the USB common class generic parent driver. This driver creates device and compatible IDs for each interface, and the installer assigns a driver to each interface. In earlier Windows editions, the bus or hub driver handles this task. Windows provides INF files for many devices and device classes, and devices may provide their own INF files. To speed up searching, Windows creates a precompiled INF (PNF) file during device installation and stores the file in the Matching a Driver to a Device 239 same folder as the device’s INF file. The PNF file contains much of the same information as the INF file but in a format that enables quicker searching. 9JGPVQ2TQXKFGCP+0((KNG Not every device requires its own INF file. Many devices that use the system’s class drivers can use the INF file that Windows provides for the class. These are some INF files for USB classes included with Windows XP: Because Windows XP and later prefer signed drivers, if you provide an unsigned driver for a device in a supported class, Windows XP and later won’t use your driver and instead will select a compatible ID from the class’s INF file. An INF file is considered part of the driver package, so Windows XP and later prefer a system-provided INF file for a system driver over an unsigned, ven- dor-provided INF file for the same driver even if the vendor’s INF file contains a matching hardware ID. When the best match is an unsigned driver, operating-system settings can affect whether Windows blocks installation, installs the driver with a warning, or installs with no warning. To change the setting, in Windows Control Panel, select System > Hardware > Driver Signing. A device that uses a class driver can have a custom, signed INF file with ven- dor-specific strings that display in the Device Manager. For example, the entry for a HID can be a vendor-specific string instead of the default USB Human Interface Device. Many INF files provided with Windows contain sections with manufac- turer-specific information. When a device passes WHQL tests, Microsoft can add the device’s sections to an existing INF file or add a manufacturer-specific INF file to the files distributed with Windows. %NCUU +0((KNG audio wdmaudio.inf human interface device (HID) input.inf (hiddev.inf in Windows 98) hub usb.inf mass storage usbstor.inf printer usbprint.inf smart card smartcrd.inf still image sti.inf Chapter 9 240 Modems and USB virtual COM ports in the communications device class must provide their own INF files even if they use system-supplied drivers. A device that uses the WinUSB driver must have an INF file that contains the device’s Vendor ID and Product ID. A device with a vendor-specific driver must have an INF file. 6QQNUCPF&KCIPQUVKE#KFU Microsoft provides tools to help in creating and testing INF files. The ChkINF utility tests a file’s structure and syntax. Log files record events that occur during device installation. ChkINF is a Perl script that requires a Perl interpreter, available free from www.activeware.com and other sources. The script runs from a command prompt and creates an HTML page that annotates an INF file with errors and warnings. During device installation, the PnP manager and the Windows Setup and Device Installer Services (SetupAPI) log events and errors to a text file. The log can be very helpful when debugging problems with device installations. In Windows XP, the data is in %windir%\setupapi.log. In Windows Vista, the data is in %windir%\inf\SetupAPI.dev.log. The WDK documentation has more about how to use the logging capability. 6KRUHQT7UKPI+0((KNGU Here are some tips for using INF files during and after product development: 7UGC8CNKF8GPFQT+& Firmware that you make available outside of a controlled environment must use a Vendor ID assigned by the USB-IF. My example code uses the Vendor ID of 0925h, which is assigned to my company, Lakeview Research. The owner of the Vendor ID is responsible for ensuring that each product and version has a unique Vendor ID/Product ID pair. Borrowing someone else’s Vendor ID can lead to conflicts if the owner of the ID uses the same values for a different device. (KPFKPI+0((KNGU On installing a device with a new INF file, Windows copies the INF file to %windir%\inf and may rename the file oem*.inf and create a .PNF file named Matching a Driver to a Device 241 oem*pnf, where * is a number. Using numbered oem file names eliminates con- flicts if multiple vendors provide INF files with the same name. To find INF files that contain a specific Vendor ID and Product ID, go to Start > Search > For Files or Folders, browse to %windir%\inf and search for the text VID_xxxx&PID_yyyy, where xxxx is the device’s Vendor ID and yyyy is the Prod- uct ID. 4GOQXKPI&GXKEG+PHQTOCVKQP When experimenting with different settings in an INF file, you may find that the operating system remembers information stored in the system registry from a previous version of the INF file. If you want the installation to use a different or changed INF file for a device (because you’ve changed the driver or device firmware, for example), you may need to tell the operating system to forget what it knows about the device. With the device installed, right-click its listing in the Device Manager, and select Uninstall. In the inf directory, remove (but save in another location if needed) any INF and PNF files that contain your device’s Vendor ID and Product ID. You can then detach and reattach the device, and installation will start fresh in searching for a driver. 9JCVVJG7UGT5GGU What the user sees on attaching a USB device varies with the Windows edition, the contents of the device’s INF file, the driver’s location, whether the driver has a co-installer and is digitally signed, and whether the device has been attached and enumerated previously and has a serial number. &GXKEGCPF%NCUU+PUVCNNGTU Device and class installers are DLLs that provide functions relating to device installation. Windows provides default installers for devices in supported device setup classes. On NT-based Windows editions, a device vendor can provide a device co-installer that works along with a class co-installer to support opera- tions specific to one or more devices in a class. A device co-installer can add information to the registry, request additional configuration information from the user, provide device-specific Property pages for the Device Manager to dis- play, and perform other tasks relating to device installation. The WDK includes the Driver Install Frameworks (DIFx) tools for creating Windows Installer packages. Chapter 9 242 5GCTEJKPIHQTC&TKXGT On boot up or device attachment, after retrieving a device’s descriptors, the operating system searches for a hardware key that matches information in the descriptors. On success, the operating system can assign a driver to the device. The hardware key’s Driver entry points to the driver key, which names the INF file. The hardware key’s Service entry points to the service key, which has infor- mation about the driver files. On first attachment, no matching hardware key exists so Windows searches for a match in the INF files. On finding none, the New Device Wizard starts. For signed drivers, an installation program can use the SetupCopyOEMInf API to copy the provided INF file to the INF folder on the user’s system. On finding a matching INF file, Windows copies the file to %windir%\inf (if the file isn’t already present), loads the driver(s) specified in the file if necessary, and adds the appropriate keys to the system registry. The device then displays in the Device Manager. After installing a device, when installing additional devices that are identical except for the serial number, Windows behaves differently depending on whether the driver is digitally signed. When the driver is signed, Windows uses administrative privileges to install the driver for additional devices after the first, even if the current user doesn’t have these privileges. If the driver is unsigned, Windows uses the privileges of the current user in deciding whether to install the driver for additional devices. When re-attaching a previously attached device, whether Windows finds a driver key can depend on whether the device’s descriptors include a USB serial number string. If the device doesn’t have a serial number, Windows finds the hardware key only if the device is re-attached to a port where the device was attached previously. If the device has a serial number, Windows finds the hard- ware key no matter which port the device attaches to. 243 &GVGEVKPI&GXKEGU This chapter shows how applications can obtain information about attached devices, request a handle for communicating with a device, and detect when a device is attached or removed. Each of these tasks involve using Windows API functions and the device interface GUIDs introduced in Chapter 8. Because many .NET programmers have limited experience with API functions, I begin with a short tutorial on the topic. #$TKGH)WKFGVQ%CNNKPI#2+(WPEVKQPU You can do a lot of programming without ever calling a Windows API function. Microsoft’s .NET Framework provides classes that support common tasks including creating user interfaces, accessing files, manipulating text and graph- ics, accessing common peripheral types, networking, security functions, and exception handling. Internally, a class’s methods are likely to call API functions, but the classes offer a safer, more secure, and more modular, object-oriented way for programmers to accomplish the tasks. Languages that can use the .NET Framework include Visual Basic, Visual C#, and Visual C++. Chapter 10 244 But .NET’s classes don’t handle every task. Some applications must do things that require calling API functions. A .NET application can use .NET classes where possible and API calls where needed. Because calling API functions can be an obscure art at times, this section includes an introduction to the topic. The code examples in this chapter assume the following Imports and using statements: 8$ Imports Microsoft.Win32.SafeHandles Imports System.Runtime.InteropServices Instead of Imports statements, you can provide references to the namespaces in the project’s properties, in the References tab. A reference to the System namespace is in the properties by default. 8% using Microsoft.Win32.SafeHandles; using System; using System.Runtime.InteropServices; /CPCIGFCPF7POCPCIGF%QFG Managed code is program code that accesses properties, methods, and events of the .NET Framework’s classes. Managed code compiles to the Microsoft Inter- mediate Language (MSIL). When the application runs, .NET’s common lan- guage runtime (CLR) environment executes the MSIL code. Because all .NET languages use the same CLR, components written in different .NET languages can easily interoperate. For example, a Visual Basic application can call a function written in Visual C# without worrying about differences in calling conventions. The CLR also simplifies programming by implementing garbage collection to manage memory. In contrast, Windows API functions are unmanaged code whose DLLs contain compiled machine code that executes directly on the target CPU. A Visual C++ application can compile to managed code, unmanaged code, or a combination. The language incorporates a technology that enables managed code to call API functions exactly as unmanaged code does. For other .NET languages, managed code can call API functions by using methods of the System.Runtime.InteropServices namespace. The namespace supports the Platform Invocation Services, also known as PInvoke and Detecting Devices 245 P/Invoke. The process of calling unmanaged functions from managed code is called Interop. 6JG& U The DLLs included with Windows are typically stored in %System- Root%\system32. The operating system searches this folder when an application calls a DLL function. Header files and documentation for Windows API func- tions are in the Windows Driver Kit (WDK) and Windows Software Develop- ment Kit (SDK): Header files contain declarations in C for the DLLs’ functions and define con- stants, variables, structures, and other components the functions access. The declarations enable applications to find the functions and pass parameters to them. A Visual Basic or Visual C# application must translate the declarations in the header files from C to Visual Basic or Visual C# syntax and data types. Translat- ing from C is more complicated than simple syntax changes because many of the variable and structure types don’t have one-to-one equivalents in .NET. The .NET code may also requires marshaling to enable passing data between man- aged and umanaged code. /CTUJCNKPI Visual Basic and Visual C# applications must take special care to ensure that any data passed to an unmanaged function survives the trip from managed to unmanaged code, and back if needed. The .NET Framework provides the Mar- shal class to help. Marshaling means doing whatever is needed to make the data available. The class provides methods for allocating memory for variables to pass to unmanaged code, copying data between unmanaged and managed memory, and converting between managed and unmanaged data types. For example, the PtrToStringAuto method accepts a pointer to a string in unman- aged memory and returns the string being pointed to. This code retrieves a (WPEVKQP & &QEWOGPVCVKQP Find devices setupapi.dll WDK under Device Installation Access devices that support handle-based operations kernel32.dll SDK under File Management Receive notifications of device attachment and removal user32.dll SDK under Device Management . input.inf (hiddev.inf in Windows 98) hub usb. inf mass storage usbstor.inf printer usbprint.inf smart card smartcrd.inf still image sti.inf Chapter 9 240 Modems and USB virtual COM ports in the communications. and protocol codes and may have any of the following forms: USB Class_aa&SubClass_bb&Prot_cc USB Class_aa&SubClass_bb USB Class_aa The values aa, bb, and cc match values in the device. descriptor. When assigning a driver, the device ID is the best match. A device ID for a USB device has this form: USB Vid_xxxx&Pid_yyyy&Rev_zzzz Matching a Driver to a Device 237 The values