Windows 7 : Programming WMI Support (part 2) - WMI Requirements for WDM Drivers ,WMI Class Names and Base Classes

4. WMI Requirements for WDM Drivers

A driver that handles IRPs registers with WMI as a data provider. System-supplied storage port drivers, class drivers, and NDIS protocol drivers fall into this category.

A driver that does not handle IRPs should simply forward WMI requests to the next-lower driver in the driver stack. The next-lower driver then registers with WMI and handles WMI requests on the first driver’s behalf. For instance, SCSI miniport drivers and NDIS miniport drivers can register as WMI providers and supply WMI data to their corresponding class drivers.

A driver that supplies WMI data to a class or port driver must support the driver-type-specific WMI interfaces that are defined by the class or port driver. For example, a SCSI miniport driver must set WmiData Provider to TRUE in the PORT_CONFIGURATION_INFORMATION structure and handle SRB_FUNCTION_WMI requests from the SCSI port driver.

Similarly, a connection-oriented NDIS miniport driver that defines custom data blocks must support OID_GEN_CO_SUPPORTED_GUIDS; otherwise, NDIS maps those OIDs and status indications returned from OID_GEN_SUPPORTED_LIST that are common and known to NDIS to GUIDS defined by NDIS.

5. WMI Class Names and Base Classes

WMI class names are case-insensitive, must start with a letter, and cannot begin or end with an underscore. All remaining characters must be letters, digits, or underscores.

WMI client applications can access a driver’s WMI class names and display them to users. Descriptive class names can help make classes more intuitive to use.

WMI class names must be unique within the WMI name space. Consequently, a driver’s WMI class names cannot duplicate those defined by another driver.

To help prevent name collisions, a driver writer can define a driver-specific base class and derive all of the driver’s WMI classes from that base class. The class name and base class name together are more likely to yield a unique name. For example, the following shows an abstract base class for a serial driver’s data blocks:

// Serial drivers' base class for data blocks
[abstract]
class MSSerial {
}

// Example class definition for a data block
[
   // Class qualifiers
]
class MSSerial_StandardSerialInformation : MSSerial
{
   // Data items
}

Device-specific custom data blocks should include the manufacturer, model, and type of driver or device in the base class name. For example:

[abstract]
class Adaptec1542 {
}
class Adaptec1542_Bandwidth : Adaptec 1542 {
   // Data items
}
class Adaptec1542_Speed : Adaptec1542 {
   // Data items
}

WMI allows only one abstract base class in a given class hierarchy. Classes that define event blocks must derive from WmiEvent, which is an abstract base class, so the abstract qualifier cannot be used in a driver-defined base class for event blocks. Instead, derive a nonabstract base class from WmiEvent, then derive individual event classes from that base class. The following examples show class definitions from the schema of a serial port driver. Not that the guid values shown in these examples are placeholders. Each class definition must have a unique GUID generated by guidgen.exe or uuidgen.exe (which are included in the Microsoft Windows SDK).

// Standard class for reporting serial port information
// Class qualifiers
[WMI, guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
Dynamic, Provider("WMIProv"),
WmiExpense(1),
Locale("MS\\0x409"),
Description("Description of class"]

// Class name
class Vendor_SerialInfo {
// Required items
   [key, read]
      string InstanceName;
   [read]
      boolean Active;
// Bytes sent on port
// Property qualifiers
   [read,
      WmiDataId(1),
      WmiScale(0),
      WmiComplexity(1),
      WmiVolatility(1000)]
   Description("Description of property");
// Data item
   uint64 BytesSent;
// Bytes received on port
   [read,
      write,
      WmiDataId(2),
      WmiScale(0),
      WmiVolatility(1000)]
   uint64 BytesReceived
// Who owns the port
   [read,
      WmiDataId(4),
      WmiScale(0),
      WmiVolatility(6000)]
   string Owner;
// Status bit array
   [read, write,
      WmiDataId(3),
      WmiScale(0)]
   byte Status[16];
// The number of items in the XmitBufferSize array
   [read,
      WmiDataId(5),
      WmiScale(0),
      WmiComplexity(1),
      Wmivolatility(1000)]
   uint32 XmitDescriptionCount;
// Array of XmitDescription classes
   [read,
      WmiDataId(6),
      WmiSizeIs("XmitDescriptionCount"),
      WmiScale(0),
      Wmicomplexity(1),
      WmiVolatility(1000)]
   Vendor_XmitDescriptor XmitBufferSize[];
}

					  

The following is the class definition for the embedded class shown in the preceding example. Note that this class does not contain InstanceName or Active items.

// Example of an embedded class
[WMI, guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
class Vendor_XmitDescriptor {
   [read, WmiDataId(1)] int32 DestinationIndex;
   [read, WmiDataId(2)] int32 DestinationTarget;
}

The following is a class definition for an event block. The class is derived from WmiEvent.

// Example of an event
[WMI, guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
Dynamic, Provider("WMIProve"),
Locale("MS\\0x409),
Description("Serial Send Event"),
WmiExpense(1)]

class Vendor_SerialSentEvent : WMIEvent
{
// Required items
   [key, read]
      string InstanceName;
   [read]
      boolean Active;