Книга: Writing Windows WDM Device Drivers

Overview

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 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 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 class definitions in binary MOF format from drivers and sends them to CIMOM. It updates the definitions as driver changes occur.

The WDM instance provider is a dynamic provider, creating instances on demand. The WDM method provider lets applications invoke methods in a WMI driver. The WDM event provider receives events from WMI devices and translates them into an instance derived from WMI Event, itself a subclass of the CIM_ExtrinisicEvent system class.

There are standard WMI classes defined that you can and should use. However, you can define your own if need be, each identified by a new GUID. In this case, you write a MOF file and compile it using mofcomp. You can include the binary MOF data either in your driver's resource or in a separate DLL. You must write a separate class for each WMI data block and WMI event block.

An event block class must be derived from the WMIEvent class. All WMI blocks appear in the RootWMI CIMOM namespace.

Standard WMI Objects

The Windows WDM provider has several standard Win32 WMI blocks defined. You can find these using the WBEM Object Browser. The MOF definitions for most of the standard Win32 WMI blocks are in the W2000 DDK file srcstorageclassdiskWMICORE.MOF.

The W2000 DDK sources also have plenty of examples of how to implement WMI. For example, the standard Windows 2000 serial driver provides five WMI data blocks of information, MSSerial_CommInfo, MSSerial_CommProperties, MSSerialHardwareConfiguration, MSSerial_PerformanceInformation and MSSerial_PortName. In each case the InstanceName property is the key, named after the PnP driver instance, not the serial port name. However, the MSSerial_PortName data object lets you retrieve the real port name in its PortName property. As another example, the MSSerial_CommInfo BaudRate property has the serial port's baud rate.

If you are writing a driver that is similar to a system driver, then consider reporting the standard system WMI blocks. The Wdm3 driver implements the standard MSPower_DeviceEnable WMI data block. As described in Chapter 10, this is used by the Device Manager to let users stop a device from powering down. This means that the Wdm3 must be able to accept a changed value for the Enable property, as well as reporting the current setting.

Listing 12.1 shows the source for the MSPower_DeviceEnable WMI data block, taken from WMICORE.MOF. A GUID is used to identify the block. This is {827c0a6f-feb0-11d0-bd26-00aa00b7b32a}, which is defined as GUID_POWER_DEVICE_ENABLE in the standard header WDMGUID.H.

All WMI classes have a key string property called InstanceName and Boolean property called Active. The MSPower_DeviceEnable class has only one "real" property, called Enable, that can be read and written and is identified as the first WmiDataId.

Listing 12.1 MSPower_DeviceEnable WMI data block

[Dynamic, Provider("WMIProv"), WMI,
 Description("The buffer for this control is a BOOLEAN and indicates if the device should dynamically power on and off while the system is working. A driver would only support such a setting if there is a significant user noticeable effect for powering off the device. E.g., turning on the device may cause a user noticeable delay. Regardless of this setting, the driver is still required to support system sleeping states irps (which likely translates to powering off the device when a system sleep occurs)."),
 guid("827c0a6f-feb0-11d0-bd26-00aa00b7b32a"), locale("MSx409")]
class MSPower_DeviceEnable {
 [key, read]
 string InstanceName;
 [read]
 boolean Active;
 [WmiDataId(1), read, write]
 boolean Enable;
};

Оглавление книги