windows-server-2003/base/ntos/wmi/sample/wmilib

    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.