Writing Windows WDM Device Drivers

  AfxMessageBox('Could not start driver');
  CloseServiceHandle(hSCManager);
  CloseServiceHandle(hDriver);
  return FALSE;
 }
 CloseServiceHandle(hDriver);
 CloseServiceHandle(hSCManager);
 return TRUE;
}
///////////////////////////////////////////////////////////////////////
//Try to find Match in MultiSz, including Match's terminating
int FindInMultiSz(LPTSTR MultiSz, int MultiSzLen, LPTSTR Match) {
 int MatchLen = strlen(Match);
 _TCHAR FirstChar = *Match;
 for (int i=0; i<MultiSzLen-MatchLen; i++) {
  if (*MultiSz++ == FirstChar) {
   BOOL Found = TRUE;
   LPTSTR Try = MultiSz;
   for (int j=1; j<=MatchLen; j++)
   if (*Try++ != Match[j]) {
    Found = FALSE;
    break;
   }
   if (Found) return i;
  }
 }
 return –1;
}
///////////////////////////////////////////////////////////////////////

Note: A revised version of NTNinstall.cpp is available on the book's web site, www.phdcc.com/wdmbook. This updated version fixes a problem to make it work in W2000.

Chapter 12 Windows Management Instrumentation

This chapter looks at Windows Management Instrumentation (WMI), the first of two methods of reporting management information to system administrators. The alternative — NT events for NT 3.51, NT 4, and Windows 2000 drivers — is covered in the next chapter. NT events are not recorded in Windows 98.

Windows Management Instrumentation is supposed to work in most Windows platforms. However, it did not work for me in Windows 98. As well as reporting information and firing events, WMI lets users set values that control the operation of a device or even invoke driver methods.

If possible, a driver should support the 'WMI extensions for WDM'. Although not mandatory, it can make it easier to debug or control your driver in the field. WMI support is required for some system functions (e.g., if you want to support user control of Power Management options in the device properties tab). If you do not support WMI, please provide a default WMI IRP handler such as in the Wdm1SystemControl routine.

The example Wdm3 driver builds on the Wdm2 driver, adding WMI and NT event support. It handles the standard MSPower_DeviceEnable WMI data block and defines its own custom WMI data block called Wdm3Information. The Wdm3Information data block returns three pieces of information to a user for each Wdm3 device: the length of the buffer, the first DWORD of the buffer contents, and the symbolic link name of the device.

I was not able to get these two further aspects of WMI working in the Beta version of W2000. A user is supposed to be able to invoke a function within the driver. The driver is supposed to be able to fire a WMI event that will be displayed in a user application.

I must first start with an overview of WMI. Although this overview appears quite complicated, it is actually fairly straightforward to support WMI in a driver.

Overview

A driver that implements the WMI extensions for WDM provides information and events to user applications, and these applications can invoke driver methods. The emphasis is on providing diagnostic and management information and tools, not the regular control of a driver.

WMI is part of the Web-Based Enterprise Management (WBEM) initiative that aims to reduce the total cost of computer ownership. WBEM is on-line at www.microsoft.com/management/wbem/. WBEM gives network professionals easy access to all the resources under their control. As the name suggests, the emphasis is on using browsers to access the information across a whole enterprise, either using COM ActiveX controls or a Java API on top of the HyperMedia Management Protocol (HMMP). Standard Win32 user programs can access WBEM repositories using COM APIs.

The WBEM core components are installed by default in Windows 2000 and are available in Windows 98[30]. To inspect the WBEM repository, you will need the WBEM SDK, available on-line and on the MSDN CDs.

WBEM embraces existing technologies, such as HMMP, Simple Network Management Protocol (SNMP), Desktop Management Interface (DMI), and Common Management Information Protocol (CMIP).

Microsoft has defined a Win32 implementation of WBEM and supplies various standard providers of information, giving access to the registry, the NT event log, Win32 information, and WDM drivers. In addition to the COM APIs, you can access the repository through an ODBC driver. Microsoft's WBEM SDK includes tools to browse and edit the WBEM repository.

The WBEM Query Language (WQL) is a subset of SQL with some extensions and can only be used to read information.

WBEM Model

WBEM is based on the Common Information Model (CIM), detailed at www.dmtf.org/work/cim.html. CIM is a structure for defining objects that need to be managed. A CIM Object Manager (CIMOM) stores these objects for the current computer in a repository. CIMOM is the heart of the WBEM system. It responds to requests from user mode management application clients and obtains information from providers.

Servers and Namespaces

Each WBEM enabled computer has its own CIM object database. Each computer is called a server and is named after the computer (e.g., \MyComputer). The current computer can be called \..

The objects in the CIM database are grouped into namespaces, which can be arranged into a hierarchy, although a namespace does not inherit anything from others higher in the tree. There is always a Root namespace. The RootDefault and RootSecurity namespaces have standard contents. Microsoft defines the Win32 namespaces RootCimV2 and RootWMI. If need be, you can define new namespaces.

CIM Objects

The objects in a namespace are defined as being classes, arranged in a hierarchy so that classes do inherit properties from base classes, possibly in different namespaces. A class is defined in a text file in the Managed Object Format (MOF). The compiled MOF data is presented by a provider so that CIMOM knows what object types can be created. Use the mofcomp tool to compile a custom WMI class definition and include it as a resource in your driver.

CIM class definitions look vaguely similar to C++ classes. Classes have properties and methods. A class can override a base class definition, including standard classes in the Default namespace. You can have abstract classes that cannot be instantiated. Singleton classes support only a single instance. See the WBEM documentation or CIM specification for full class details.

One of the properties of a class is called the key property, used to differentiate separate instances of a class. If the key property is called InstanceName, the full object path of a class instance might be \ServerNamespace:Class.InstanceName='PCIVEN..'.

Each class can have zero or more instances. For example, the Win32_LogicalDisk class may have two instances to represent drives C and D, differentiated by the DeviceId key property. Locally, the full object path for drive C is \.RootCimV2:Win32_LogicalDisk.DeviceId='C'. You can use relative paths once attached to a namespace (e.g., Win32_LogicalDisk.DeviceId='C').

You can denote a class as being 'expensive to collect' if it takes significant extra processing to collect the information. In this case, a user application must specifically request that the information be collected.

CIM object classes can be static or dynamic. Static classes can have static or dynamic instances. However, dynamic classes have only dynamic instances. Static instances are preserved across reboots. A static instance can have static or dynamic properties. Static information is provided from the CIMOM registry while dynamic information is supplied by a provider.

The WDM Provider

The WDM Provider is a Windows service that interacts with drivers and the CIM Object Manager. It is a WMI class, instance, method, and event provider. The WDM class provider retrieves