API for NDIS (bindings) configuration?

OSR_Community_User · June 17, 2008, 5:34am

Hello,

I’m still working on the NDIS 5.1 IM driver based on Passtrhu Extd2, for which I already got a lot of usefull help from this forum.

The driver isn’t finished yet, but I’m already thinking about the final installation mechanism. There’s a requirement to have a user-friendly driver installation wizard. I’m thinking of a dialog that presents all available network adapters with checkboxes, so that the user can select adapters for IM filter driver installation.

Normally, I would delay such topics until the actual driver is finished. However, the required (un-)installation procedures are already time-consuming during development, so I got the idea to speed things up by writing the installation wizard early.

I already wrote a similiar application for other devices, and I would expect that system-wide installation as a net service can be done by some SetupDiInstallXXX function (correct?). But I also need to activate the driver on a per-adapter basis, and I cannot find any information how to do that. There’s presumably some kind of nids-specific usermode configuration API I haven’t found yet.

And there’s another (related) question that came up while writing this post: For the usermode components, we need means to be informed about NDIS configuration changes (not necessarily initiated by ourselves). Most importantly, our application needs to be informed when adapters are added or removed, and when critical parameters like MTU are changed. I know that I could create such notifications from inside the driver, but I don’t like the idea.

So: Is there any information about usermode NDIS configuration APIs I missed?

Thanks!

Philipp Beyer

David_R_Cattley · June 17, 2008, 9:36am

Philipp,

The WDK sample at src\network\config\bindview is the penultimate reference for and only tutorial for interacting with the network install/configuration mechanism (NetCfg).

In prior DDKs (W2K and maybe early XP) another sample src\network\config\netcfg was a console utility (and quite useful) which demonstrated install/uninstall of network components (other than adapters which are PnP devices).

The W2K DDK also had a document names src\network\config\inetcfg.doc which has largely been incorporated into the WDK Docs as the reference for INetCfg and related interfaces. The document, however, had a “Section 4” which was essentially a bunch of bulleted lists under ‘how-to’ topics. It was a very handy short-form reference and perhaps more understandable ‘top-down’ than reading BindView (especially for the beginner).

I don’t know if the W2K DDK is available to you but I found that document and the NetCfg sample to be useful introductions way-back-when in W2K days.

And for what it is worth, the ‘component’ you need to develop to track Network Configuration changes that effect your IM driver (or the system in general) is called a “Notify Object”. Any network component other than an Adapter (Class Net) can have one and many do. The WDK has a sample Notify Object at src\network\ndis\mux\notifyob. If you are interested in snooping on and perhaps influencing NetCfg changes, look at the INetCfgComponentNotifyBinding and INetCfgComponentNotifyGlobal interface handlers in the MUX\notifyob sample.

As for the specifics of caring when MTU changes, your IM driver will be notified in ‘effect’ because for NDIS5, the MTU cannot change while the underlying Miniport is initialized and protocols are bound to it. The IM driver will be unbound and rebound and then you can ask the NIC what the MTU is. Monitoring the NetCfg is not in my opinion a very good way to catch MTU changes since nothing says that the change needs to be UI driven or even involve the NetCfg. The only way to know is to ask the NIC with an NdisRequest(). If you really only care about it in User Mode, then consider using WMI and accomplish the same thing by having an Instance Creation Event registered for WIN32_NetworkAdapter and grabbing the MTU from WMI properties.

Good Luck,
Dave Cattley
Consulting Engineer
System Software Development

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of xxxxx@alliedvisiontec.com
Sent: Tuesday, June 17, 2008 5:34 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] API for NDIS (bindings) configuration?

Hello,

I’m still working on the NDIS 5.1 IM driver based on Passtrhu Extd2, for which I already got a lot of usefull help from this forum.

The driver isn’t finished yet, but I’m already thinking about the final installation mechanism. There’s a requirement to have a user-friendly driver installation wizard. I’m thinking of a dialog that presents all available network adapters with checkboxes, so that the user can select adapters for IM filter driver installation.

Normally, I would delay such topics until the actual driver is finished. However, the required (un-)installation procedures are already time-consuming during development, so I got the idea to speed things up by writing the installation wizard early.

I already wrote a similiar application for other devices, and I would expect that system-wide installation as a net service can be done by some SetupDiInstallXXX function (correct?). But I also need to activate the driver on a per-adapter basis, and I cannot find any information how to do that. There’s presumably some kind of nids-specific usermode configuration API I haven’t found yet.

And there’s another (related) question that came up while writing this post: For the usermode components, we need means to be informed about NDIS configuration changes (not necessarily initiated by ourselves). Most importantly, our application needs to be informed when adapters are added or removed, and when critical parameters like MTU are changed. I know that I could create such notifications from inside the driver, but I don’t like the idea.

So: Is there any information about usermode NDIS configuration APIs I missed?

Thanks!

Philipp Beyer

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at http://www.osronline.com/page.cfm?name=ListServer

Soren_Dreijer · June 18, 2008, 6:08am

You could also take a look at the notification mechanisms provided by the IP
Helper API:
http://msdn.microsoft.com/en-us/library/bb742902.aspx (search for
Notification Functions)

One such function would be NotifyIpInterfaceChange().

/ Soren

“David R. Cattley” wrote in message news:xxxxx@ntdev…
Philipp,

The WDK sample at src\network\config\bindview is the penultimate reference
for and only tutorial for interacting with the network install/configuration
mechanism (NetCfg).

In prior DDKs (W2K and maybe early XP) another sample
src\network\config\netcfg was a console utility (and quite useful) which
demonstrated install/uninstall of network components (other than adapters
which are PnP devices).

The W2K DDK also had a document names src\network\config\inetcfg.doc which
has largely been incorporated into the WDK Docs as the reference for INetCfg
and related interfaces. The document, however, had a “Section 4” which was
essentially a bunch of bulleted lists under ‘how-to’ topics. It was a very
handy short-form reference and perhaps more understandable ‘top-down’ than
reading BindView (especially for the beginner).

I don’t know if the W2K DDK is available to you but I found that document
and the NetCfg sample to be useful introductions way-back-when in W2K days.

And for what it is worth, the ‘component’ you need to develop to track
Network Configuration changes that effect your IM driver (or the system in
general) is called a “Notify Object”. Any network component other than an
Adapter (Class Net) can have one and many do. The WDK has a sample Notify
Object at src\network\ndis\mux\notifyob. If you are interested in snooping
on and perhaps influencing NetCfg changes, look at the
INetCfgComponentNotifyBinding and INetCfgComponentNotifyGlobal interface
handlers in the MUX\notifyob sample.

As for the specifics of caring when MTU changes, your IM driver will be
notified in ‘effect’ because for NDIS5, the MTU cannot change while the
underlying Miniport is initialized and protocols are bound to it. The IM
driver will be unbound and rebound and then you can ask the NIC what the MTU
is. Monitoring the NetCfg is not in my opinion a very good way to catch
MTU changes since nothing says that the change needs to be UI driven or even
involve the NetCfg. The only way to know is to ask the NIC with an
NdisRequest(). If you really only care about it in User Mode, then
consider using WMI and accomplish the same thing by having an Instance
Creation Event registered for WIN32_NetworkAdapter and grabbing the MTU from
WMI properties.

Good Luck,
Dave Cattley
Consulting Engineer
System Software Development

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of
xxxxx@alliedvisiontec.com
Sent: Tuesday, June 17, 2008 5:34 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] API for NDIS (bindings) configuration?

Hello,

I’m still working on the NDIS 5.1 IM driver based on Passtrhu Extd2, for
which I already got a lot of usefull help from this forum.

The driver isn’t finished yet, but I’m already thinking about the final
installation mechanism. There’s a requirement to have a user-friendly driver
installation wizard. I’m thinking of a dialog that presents all available
network adapters with checkboxes, so that the user can select adapters for
IM filter driver installation.

Normally, I would delay such topics until the actual driver is finished.
However, the required (un-)installation procedures are already
time-consuming during development, so I got the idea to speed things up by
writing the installation wizard early.

I already wrote a similiar application for other devices, and I would expect
that system-wide installation as a net service can be done by some
SetupDiInstallXXX function (correct?). But I also need to activate the
driver on a per-adapter basis, and I cannot find any information how to do
that. There’s presumably some kind of nids-specific usermode configuration
API I haven’t found yet.

And there’s another (related) question that came up while writing this post:
For the usermode components, we need means to be informed about NDIS
configuration changes (not necessarily initiated by ourselves). Most
importantly, our application needs to be informed when adapters are added or
removed, and when critical parameters like MTU are changed. I know that I
could create such notifications from inside the driver, but I don’t like the
idea.

So: Is there any information about usermode NDIS configuration APIs I
missed?

Thanks!

Philipp Beyer

—
NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

David_R_Cattley · June 18, 2008, 10:12am

Soren,

That is an excellent suggestion and quite simplifies an approach to getting
user mode notification of adapter arrival. The only caveat is of course
that the adapter of interest must be bound to TCPIP.SYS in order that it
show up as an IP interface. Since probably the only place in the world
left where NIC cards are *not* bound to TCPIP is in my lab, your suggestion
would be a reasonable and recommended way for the OP to avoid going crazy
trying to make WMI work

Cheers,
-dave

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Soren Dreijer
Sent: Wednesday, June 18, 2008 6:08 AM
To: Windows System Software Devs Interest List
Subject: Re:[ntdev] API for NDIS (bindings) configuration?

You could also take a look at the notification mechanisms provided by the IP

Helper API:
http://msdn.microsoft.com/en-us/library/bb742902.aspx (search for
Notification Functions)

One such function would be NotifyIpInterfaceChange().

/ Soren

OSR_Community_User · June 18, 2008, 11:53am

Thanks a lot for your answers and the precise links into MS APIs.

We’ll probably use WMI for notifications about adapter changes.
But it seems that I’ve missed a point about the IP Helper API: This is a kernel mode API, right? David, you mentioned to use it for user mode notifications. Did I really miss something or did you mean to implement some “inverted callback” in the driver (which still may be easier than WMI/COM usage).

In any case, I’m lucky to have a colleague with COM experience doing most of the usermode part, and he already received his first adapter-specific notifications through WMI.

David_R_Cattley · June 18, 2008, 1:08pm

IP Helper is a usermode API in NT5 and later systems. (There is a version for NT4 as well, and W9x but frankly, not relevant).

In NT6 the feature set and some of the API surface of the IP Helper was likewise made available to both user mode and kernel mode through a re-design to accommodate the ‘dual-stack’ IP4/IP6 architecture. A whole lot of FooBarApi2() showed up where there had only been FooBarApi() before. You will note that it is the ‘2’ versions that are available in both modes.

Well, you said NT5 so go look at ‘legacy’ IPHlpApi stuff that is only in the Platform SDK and does not end in ‘2’.

Good Luck,
Dave Cattley
Consulting Engineer
Systems Software Development

-----Original Message-----
From: xxxxx@lists.osr.com [mailto:xxxxx@lists.osr.com] On Behalf Of xxxxx@alliedvisiontec.com
Sent: Wednesday, June 18, 2008 11:55 AM
To: Windows System Software Devs Interest List
Subject: RE:[ntdev] API for NDIS (bindings) configuration?