NDI Object Registrations

NETDI gets all of the driver-specific information for a driver or network component (referred to generically as NDI objects) either from the registry section for the driver or from a custom NDI installer procedure. The registry section for the object is initially populated based on the driver install section in the INF file.

General Driver Information

NDI Registration parameters

If your component requires a custom NDI procedure DLL, this DLL must be copied before any of the other files are copied. This allows the DLL to display any custom UI before the user clicks the OK button in the Network Control Panel to cause NETDI to save the configuration. Furthermore, INF files that are not included with Windows 95 should copy themselves to the hard disk. To do this, copy the DLL and INFs by using a CopyFiles command in your registration section, as shown in the following example:

[MYDEVICE.ndi]
AddReg=MYDEVICE.ndi.addreg
CopyFiles=MYDEVICE.ndi.copyfiles,MYDEVICE.inf.copyfiles

[MYDEVICE.ndi.addreg]
HKR,Ndi,DeviceID,,MYDEVICE
HKR,Ndi,Installer,,"MyNDI.DLL,MyNDIProc"
; ...other registration info...
HKR,Ndi\Install,,,"MYDEVICE.Install"
[MYDEVICE.ndi.copyfiles]
MyNDI.DLL
[MYDEVICE.inf.copyfiles]
MyNDI.INF

[MYDEVICE.Install]
AddReg=MYDEVICE.Install.addreg
CopyFiles=MYDEVICE.Install.copyfiles

[MYDEVICE.Install.addreg]
; Registry keys needed to start this component
[MYDEVICE.Install.copyfiles]

[DestinationDirs]
MYDEVICE.ndi.copyfiles = 11 ; System directory
MYDEVICE.inf.coypfiles = 17 ; INF directory

Files needed by component.PCMCIA and Plug and Play drivers

Any network card that has a hardware enumerator (PCMCIA, EISA, PCI, ISAPNP, and so on) must have a special parameter set in the registration section to indicate that the card is a PnP card. The registration section for these cards should have a CardType parameter to indicate what the type of the card is:

Install section parameters

Statically loaded VxDs must also be stored in the HKLM\System\CurrentControlSet\Services\VxD\VXDNAME key, where VXDNAME is the name of the driver (usually the base name of the VxD file). Under this key, the following value must be set:

Help text

The Network Control Panel has an area on the bottom of the Configuration tab used to give the user a description of the selected object. By default, when the user selects an object, the help area simply displays a description of the class of the selected device. You can override this default and have the Network Control Panel display text specific to your device when the user selects it. This text is specified in the HelpText parameter:

This help text should be written to describe how the selected object benefits the user (such as, what can the user do with the object). For example, the help text for a client should not just say what the client is, but what it allows the user to connect to.

Driver Interface Rules

NETDI uses upper and lower interfaces to describe the possible relations between the layered drivers in the network system. The lower interface is the software or hardware interface that the driver talks to. For example, a network adapter driver might talk to "ethernet" or "tokenring." The upper interface is the software interface that the driver provides. For example, an NDIS 3.1 network adapter driver provides "ndis3" as an upper interface; an NDIS 3.1 transport driver has "ndis3" as a lower interface and might provide "netbios" or "ipx" as its upper interface.

The following interface names are predefined to cover the most common interfaces; however, any string of alphanumeric characters is a legal interface name. This allows you to create private interfaces between components. When defining your own interface, include the manufacturer name in the interface name to avoid conflicts with other vendors.

NETDI matches the upper and lower interfaces of drivers to validate bindings between drivers. In addition, NETDI also checks for other required or excluded interfaces down the chain of bound driver and in the entire network subsystem. If an object has a lower edge that does not match the upper edge of any of the installed components, NETDI will attempt to install a component that does match the interface. For example, the Client for Windows Networks has a lower edge of NetBIOS. If the user tries to install this client without a NetBIOS protocol, NETDI will automatically install a protocol to match the required interface. In this case it would install NetBEUI.

The following list shows the registry entries for specifying interfaces requirements for a network driver. An interface list is a comma-separated list of interface names, for example, "ndis2, ndis3, odi".

The current upper and lower interfaces are queried in an NDI procedure by sending the appropriate NDI_GET_UPPER_INTERFACES and NDI_GET_LOWER_INTERFACES messages. The default NDI procedure reads the interface list from the registry. A custom NDI procedure can therefore enable or disable interfaces by returning a different interface list.

Device Compatibility Rules

A driver can specify compatibility or incompatibility with other drivers in the system by specifying lists of device IDs. These can specify required or excluded devices. The following list shows the registry entries for specifying compatibility with other devices. A device is a Plug and Play device ID; a device list is a comma-separated list of device IDs. (Note that for non-hardware devices, the Plug and Play device ID is either the NDIS logical driver name or the base file name of the VxD or driver.)

Referring to other INFs

Using the Ndi\Compatibility keys described above, it is possible for an INF to install other devices. These devices may be described in other INFs. To accomplish this, an INF must do the following:

• Copy any other INFs that have devices that are referenced. This must be done in the registration section of the INF. (Note: all INFs must be distributed in the same directory)
• Add the InstallInf key to the registry to have the other INFs added to the INF database.

For example, if MYDEVICE in Myndi.inf required OTHERDEVICE in Other.inf, MYNDI should look like the following:

[MYDEVICE.ndi]
AddReg=MYDEVICE.ndi.addreg
CopyFiles=MYDEVICE.ndi.copyfiles,MYDEVICE.inf.copyfiles

[MYDEVICE.ndi.addreg]
HKR,Ndi,DeviceID,,MYDEVICE
HKR,Ndi,InstallInf,,"OTHER.INF"
; ...other registration info...
HKR,Ndi\Install,,,"MYDEVICE.Install"
[MYDEVICE.inf.copyfiles]
MyNDI.INF
OTHER.INF

[MYDEVICE.Install]
AddReg=MYDEVICE.Install.addreg
CopyFiles=MYDEVICE.Install.copyfiles

[MYDEVICE.Install.addreg]
; Registry keys needed to start this component
[MYDEVICE.Install.copyfiles]

[DestinationDirs]
MYDEVICE.inf.copyfiles = 17 ; INF directory

Install and Remove Information

When the driver is actually to be installed or removed, NETDI uses this information to tell which sections from the drivers INF files to execute. The install and remove entries can specify a base section that gets executed unconditionally whenever the driver is added or removed. The unconditional entries use the NULL value name. In addition, one can also specify interface-specific install and remove sections so only files or registrations that are a needed for the given upper interface are installed.

When installing, NETDI executes the base (null) section first, and then any interface-specific sections. When removing, NETDI executes interface-specific sections first and executes the base (null) section last.

Hardware Resources

For NDIS3 network adapter drivers, hardware resources for the card memory base address, base I/O address, DMA channel, and IRQ level are specified by a Logical Configuration entry in the INF file. These Logical Configuration entries are documented in the Windows 95 Device Information Files specification.

NDIS2 network adapter drivers store hardware resources in the parameters section (described below). The parameter key must be the same as the one used in Protocol.ini.

Note: On computers, IRQ2 and IRQ9 are really the same. For this reason PnP always refers to IRQ2 as IRQ9. If the network adapter driver requires that a 2 be passed to it for IRQ2, it must set the IRQ2 parameter flag (described in the next section).

Driver Parameters

You can specify any number of software parameters to be saved under the driver's registry key. For NDIS2 drivers, these are also saved in PROTOCOL.INI. The parameter descriptions are saved under the "Ndi\params" subkey; their current values are saved at the root of the driver key. For NDIS drivers, the NDIS wrapper can read these parameters from the root of the driver key and report them back to the driver. The user views and edits the parameters from the "Advanced" property sheet page provided by NETDI. Parameters can be numeric (int, long, word, dword), or text (edit, enum). For numeric types, you can specify the minimum, maximum and, optionally, the interval value. For the enum type, you must specify a list of values and descriptions. For the edit type, you can specify certain edit control options: maximum length, OEM-text compatibility, and upper case.

Range information for numeric types

Range information for enum types

Hardware resource parameters for NDIS2 network card drivers:

Use the following parameter to tell NETDI to store the parameter in some other location in the registry. Note, for this parameter, this will be the only value listed under Ndi\Params. The rest of the above parameters must be located in the desired registry key. (See the sessions parameter for NETBEUI listed in the example above.)

Storing parameters in an arbitrary registry location:

Parameter flags:

Text file processing

NETDI has the ability to search text files such as Autoexec.bat and Config.sys and insert or remove lines from them. It does this by using the following registry values in the registration section of your INF. The key name under the Ndi key is the name of the file to process. Each line to insert in this file is given a name (specified in the KeyOrder) value. For each line, you can insert or replace text in the file. Replacing a line with a null string effectively deletes the line.

NETDI executes these operations when it is committing changes to the disk.

NDIS 3 Driver Information

The NDIS 3 wrapper uses this information to load and bind NDIS 3.x drivers.

NDIS 2 DriverInformation

The device loader and NDIS 3 wrapper use this information to check if the real-mode NDIS 2 driver is in memory and to load the appropriate mapper if necessary.

Note: NETDI automatically copies the file specified in FileName, therefore it is not necessary to explicitly copy the file in a CopyFiles section in the INF file. You only need a CopyFiles section for NDIS2 if you have additional support files for your driver.

ODI Driver Information

The device loader and NDIS 3 wrapper use this information to check if the real-mode ODI driver is in memory and to load the appropriate mapper if necessary.

Note: NETDI automatically copies the file specified in FileName, therefore it is not necessary to explicitly copy the file in a CopyFiles section in the INF file. You only need a CopyFiles section for ODI if you have additional support files for your driver.

Other notes for network card drivers

Since they specify information for hardware devices, INF files for network cards also need all the other information a standard PnP INF file needs. This includes using approved PnP device IDs and having LogConfig sections for non-PnP cards. LogConfig sections are not needed for PCMCIA, EISA, MCA, and PCI devices.