Programmatically Installing
NDIS Protocol Drivers

Background

Previous articles related to this topic include:

bulletSelf-Signing NDIS Protocol Drivers - Discussed the basic process of signing a NDIS protocol driver executable. Is some cases simply self-signing the NDIS protocol driver executable is all that is required.
 
bulletMaking and Signing Driver Packages for NDIS Protocol Drivers - Discussed the additional steps needed to make a signed driver package that includes a companion INF file.

This topic provides a sample command-line application named ProtInstall that can be used to programmatically install the NDISPROT sample NDIS protocol driver.

ProtInstall uses the INetCfg API to install the driver. This API is discussed at length in the WDK Help file. The API is COM-based, and I personally am not a COM expert. So, I like start with working examples and bend them to suit my needs. I also like to use Visual Studio instead of the WDK to build user-mode components, but this is just a matter of taste.

The Windows XP DDK included a console-based sample application named SNetCfg. SNetCfg was intended to be an example of a general-purpose network component installer that used the INetCfg API. However, it was clumsy to use and had a few bugs.

The Windows Server 2003 DDK replaced SNetCfg with a GUI-based sample application named BindView. BindView provides functionality similar to that of the Network Control Panel for installing and uninstalling network components.

This note won't dwell on the INetCfg API in any detail. Instead, this note describes a console-based sample application that illustrates installing and uninstalling a NDIS protocol driver.

ProtInstall is an adaptation of SNetCfg. It specifically installs and uninstalls the NDISPROT sample NDIS protocol driver. ProtInstall is built under the Visual Studio 2003 development environment, but can be migrated to Visual Studio 2005 without too much effort. ProtInstall can be called easily from Windows Installer Custom Actions.

A link to download source code for ProtInstall is provided at the end of this note.

 

ProtInstall - NDISPROT Driver Installer

Summary

ProtInstall is a Win32 console application that is designed specifically to install and uninstall the WDK NDISPROT NDIS protocol driver. It is loosely based on the SNetCfg application from the Windows 2000 DDK.

The application is designed to be called from a Windows Command Prompt window or from a Windows Installer, and can be used to install on Windows 2000 through Windows Vista on both x86 and x64 hosts.

 

Building the Application

The application is built using Microsoft Visual Studio 2003.

Building the application does depend on additional header files from the DDK. You will have to adjust the project's "Additional Include Directories" property to point to your DDK install folders:

All Configurations
    C/C++
        General
            Additional Include Directories

Here are the additional include directories used at the time of this writing:

..\..\Include;C:\WINDDK\3790~1.183\inc\wxp;C:\WINDDK\3790.1830\inc\crt

Strings defined in the ProtInstall.H header file are used to select the driver's INF files, PnP IDs and Friendly Name. So, once built the application can only be used to install the WDK NDISPROT driver. You can, however, modify the sources to support your own needs.

 

Installing and Uninstalling the Driver using ProtInstall

As written ProtInstall must be run from a folder that also contains the NDISPROT driver package, which includes the driver executable, INF and CAT files.

To install NDISPROT the install folder would contain these items:

bulletProtInstall.EXE
bulletNDISPROT.SYS
bulletNDISPROT.INF
bulletNDISPROT.CAT

Installing the Driver

To install the driver run the ProtInstall application with the /Install command-line switch:

ProtInstall /Install

 

Uninstalling the Driver

To uninstall the driver run the ProtInstall application with the /Uninstall command-line switch:

ProtInstall /Uninstall

 

Hiding the Command Window

In some cases it may be desirable to hide the ProtInstall command window from view. This may be particularly desirable when using ProtInstall in conjunction with a Windows Installer. To hide the ProtInstall window append the /Hide command-line switch after the /Install or /Uninstall switch.

Here is an example command-line that hides the ProtInstall window during installation:

ProtInstall /Install /hide

 

Using ProtInstall in a Windows Installer

Use the Windows Installer Custom Actions feature to call ProtInstall.EXE.

For example, to call ProtInstall to install the driver, add a new "Install Driver" action to the pre-defined Install action. The Install Driver Arguments property would be /Install and the SourcePath property would be the path to the ProtInstall.exe file on the development computer.

To call ProtInstall to uninstall the driver, add a new "Uninstall Driver" action to the pre-defined Uninstall action. The Uninstall Driver Arguments property would be /Uninstall and the SourcePath property would be the path to the ProtInstall.exe file on the development computer.

CustomActions that install device drivers require elevated privileges. See some musings on this topic at http://ndis.blogspot.com/2009/03/i-just-wanted-to-install-my-dam-driver.html.

 

License for ProtInstall Usage

This software IS free software under the terms of a BSD-style license. The right to use this code in your own derivative works is granted so long as

  1. Your own derivative works include significant modifications of your own.
     
  2. You retain the above copyright notices and this paragraph in its entirety within sources derived from this code.

This product includes software developed by PCAUSA. The name of PCAUSA may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

 

Download ProtInstall Source Code

This ZIP file includes the Visual Studio 2003 project and sources for the ProtInstall application.

Download ProtInstall source code (Visual Studio 2003).

This ZIP file includes the Visual Studio 2005 project and sources for the ProtInstall application.

Download ProtInstall source code (Visual Studio 2005).

You may have to modify some Project Settings to build successfully.

 

Topic Status

September 14, 2009 Reviewed.
May 15, 2008 Added Visual Studio 2005 project.
November 23, 2006 Initial release.

 

PCAUSA Home Privacy Statement Products Ordering Support Utilities Resources
Mailing Lists  PCAUSA Newsletter PCAUSA Discussion List
Rawether for Windows, Rawether .NET, WinDis 32 and NDIS Press are trademarks of Printing Communications Assoc., Inc. (PCAUSA)
Microsoft, MS, Windows, Windows Vista, Windows 95, Windows 98, Windows Millennium, Windows 2000, and Win32 are registered trademarks and Visual C++ and Windows NT are trademarks of the Microsoft Corporation.
Copyright 1996-2013 Printing Communications Assoc., Inc. (PCAUSA)
Last modified: December 02, 2013