windows-xp/Source/XPSP1/NT/base/ntos/wmi/sample/wmilib/readme.txt

    This directory contains a sample PnP upper filter driver whose only 
purpose is to provide WMI data blocks. Typically driver writers will copy the 
sample code into their own driver and make any minor modifications so that the
WMI data blocks are always available when the driver is loaded. Alternatively
WmiSamp can be left as a filter driver if WMI data blocks should only be made
available when the filter driver is loaded. Drivers that link to classpnp.sys
should use a similar library that is part of classpnp.

    WMI enabling a driver with the sample code consists of doing 5 things:

1. Determining what data needs to be provided and organize it into data blocks
   that contain related data items. For example packets sent and bytes sent
   could be part of a single data block while transmit errors could be part
   of a data block that contains other error counts. Determine if the device
   needs notifications of when to enable and disable collections in the case
   of data blocks that impose a performance hit to collect.

2. Write a Managed Object Format (.mof) file that describes the data blocks. 
   In doing this the driver writer will need to run the guidgen tool to 
   create globally unique guids that are assigned to the data blocks. Guidgen
   *MUST* be run so that no two data blocks will have the same guid. Reference
   the .bmf file (.bmf files are created when mof files are compiled by the 
   mofcomp tool) in the driver's .rc file so that the .bmf file data is 
   included as a resource of the driver's .sys file. WmiLib hardcodes the 
   resource name as MofResourceName.

3. Build the GUIDREGINFO structure with the guids for the data blocks defined
   in the .mof file. If the device wants to be notified of when to start and
   stop collection of a data block the WMIREG_FLAG_EXPENSIVE flag should be
   set for the data block in the GUIDREGINFO structure.

4. Implement the 6 WMI function callback routines and reference them in a 
   WMI_INFO structure.


    The sample code supports does not support more than one instance of a 
data block for each device, that is a single device object can only supply
one instance of a data block. Drivers that create multiple device objects
will supply multiple instances for a data block (ie, 1 data block per device
object).

    The sample code does not support dynamic instance names. Instance names 
are statically defined when device registers with WMI. The PQUERY_WMI_REGINFO
callback allows the device to specify a unique instance name for the device or
the PDO for the device. If the PDO is specified then WMI will translate it to 
the device instance name and use that as the unique instance name.

    All data blocks registered for a device will use the same instance name.
That is different data blocks for a device object cannot specify different 
instance names.

    The sample code can be extended to overcome these limitations if the need
arises, however this sample code should be sufficient for most applications.

    All WMI callback functions that pass the irp as a parameter are 
responsible to call WmiLibCompleteRequest when the request has been satisfied
so that the IRP can be completed. If the WMI callback function cannot 
complete the request immediately it can mark the irp pending and return
STATUS_PENDING, but it must call WmiLibComnpleteRequest when the request 
actually finishes.

    The sample code uses a simple linear search to determine the guid index
for any guid passed. If a driver provides a long list of guids then 
WmiLibFindGuid may need to be updated to use a better searching mechanism.

    WmiLib counts on a number of fields being present in the device extension
in order for it to process the WMI requests. See Wmilib.h for their 
description.

    Finally the sample code uses a static global variable to store the 
values for the data block. This is not quite correct since each device object
will typically have its own set of data that composes its instance of a 
data block. Really the global variable should be part of the device extension,
however I did not want to confuse the device extension with extra stuff.