.INF files and NCF_HAS_UI: how to write .dll for displaying advanced properties tab of network driver?

Question

I have a NDIS driver, which gets listed both in connection properties's installed items list and in device manager; the question is, how do I write an extension which will be used for managing driver's properties, and how to install it?

Of course, a plain GUI program may communicate with the driver, set properties, get version numbers and other statistical info etc, that's what DeviceIoControl exists for; but, does this means that no dedicated interface exists to inform the driver about configuration changes?

It would be pleasant if someone can forward this question to eggheadcafe/osr's ntdev lists.

Answer 1

If you want your network driver to have some UI in the LAN Properties dialog, then you need to do these things:

Create a NotifyObject (if you don't have one already)

A NotifyObject is essentially a COM object associated with your driver. To make one,

1. Make a DLL that can create your new COM class. (If you use ATL's class factory, it's only a couple lines of code. I highly recommend using ATL for implementing COM objects. This is out-of-scope of the LAN Properties GUI, but you should look up DllGetClassObject, a C++ class that inherits from CComObjectRoot and CComCoClass, a call to OBJECT_ENTRY_AUTO, and a BEGIN_COM_MAP if you're new to COM.)
2. Associate your COM object with the driver by putting ClsId={guid} and ComponentDll=filename into your INF.

Implement INetCfgComponentPropertyUi on your COM object

1. The key method is MergePropPages. In this method, you allocate propertysheet pages and merge them into the adapter properties. This operation looks something like this pseudocode:

   HPROPSHEETPAGE *psharray = CoTaskMemAlloc(NUMBER_OF_PAGES * sizeof(HPROPSHEETPAGE);
   for (i = 0; i < NUMBER_OF_PAGES; i++)
       psharray[i] = CreatePropertySheetPage(&psp);
   

2. The API is meant to be transactional. Make sure to apply any changes in the ApplyProperties method, and (if applicable) undo them in CancelProperties.

3. You don't need to do anything in QueryPropertyUi or SetContext, although you might want to save the context if you need to get the registry key location.

Test your changes

If all goes well, then your new Notify Object will be loaded up every time there are any network configuration changes. If the GUI is being displayed, then Windows will query your class for the INetCfgComponentPropertyUi interface and call MergePropPages.

I find it helpful to put hardcoded breakpoints in my DLL at key locations, and then attach a kernel debugger so that I can always find the DLL, no matter which process is loading it. (On Windows 7, you'll be loaded in drvinst.exe, which can be hard to find with a usermode debugger.)