MACADDR II

MACADDR II
IOCTL_NDIS_QUERY_GLOBAL_STATS
Sample Application
for
Windows NT, Windows 2000 and Higher

Background

The Windows NT 4.0 DDK includes a sample application called MACADDR. The MACADDR sample illustrated the use of Win32 DeviceIoControl calls to access NDIS MAC drivers using IOCTL_NDIS_QUERY_GLOBAL_STATS. Using this IOCTL a Win32 application can have limited access to a NDIS MAC driver without needing the support of a companion NDIS protocol driver. This can be useful to network-aware applications - especially MAC vendor diagnostic tools.

The technique illustrated in the MACADDR sample actually works on Windows 2000. However, it is not straightforward to use because on Windows 2000 and higher the "Adapter Name" is the HEX representation of a 128-bit GUID. The MACADDR sample is omitted from the Windows 2000 DDK, probably because it would simply be impractical to enter the GUID from the command line.

The PCAUSA MACADDR II sample illustrates the use of IOCTL_NDIS_QUERY_GLOBAL_STATS on both Windows NT and Windows 2000. In addition, it partially illustrates walking the Windows NetCard registry key to find known NDIS adapters.

The technique of using IOCTL_NDIS_QUERY_GLOBAL_STATS to access a NDIS MAC driver will NOT work on the Windows 9X platforms. Sorry!

Microsoft may very well modify the behavior of this function or deprecate it altogether in future Windows releases.

"August 20, 2003 - Jim Mateer (Microsoft) - It has come to Microsoft's attention that there are applications that misuse the output buffer in the IOCTL_NDIS_QUERY_GLOBAL_STATS DeviceIoControl call.

This buffer, which is designed to be used by the driver to return the requested information, is, in some cases, being used to send data from the application to the driver. Microsoft has determined that this procedure has the potential of crashing the OS, and therefore considers this to be a security flaw.

Future releases on Microsoft Operating Systems will eliminate this security weakness by preventing this behavior. Furthermore, Microsoft is deprecating the use of IOCTLS to query information from a Network driver. Microsoft recommends using WMI to send data to, and to query your driver- See the DDK documentation for more information on WMI."

PCAUSA has some thoughts on this proposition...

PCAUSA would agree with Microsoft about eliminating the misuse of the IOCTL query API for setting information. HOWEVER, we would strongly recommend preserving the IOCTL query capability simply because the alternative would be an unnecessary proliferation of additional NDISPROT-based kernel-mode components that perform essentially the same simple function.

Although WMI offers an excellent API for managing many aspects of a Windows platform, WMI is unfit (or at least much less than desirable) for some uses - such as real time monitoring of signal strengths, downloading firmware, etc.

Finally, if use of WMI is to be encouraged by Microsoft, then the NDIS OIDs that are settable by NDIS requests must be writable through WMI. As I understand it, an accommodation has been in WMI specifically to support WZC. Some 802.11 OIDs that are settable are not writable via WMI. This provides an obstacle to the use of WMI for 802.11 management by parties other than Microsoft.

There are some quirks in the behavior of this technique.

As an example, on Windows XP and lower making the OID_WAN_CURRENT_ADDRESS query on a 802.3 adapter fails.

On Windows Server 2003 making the OID_WAN_CURRENT_ADDRESS query on a 802.3 adapter may fail or it may succeed. If it succeeds then it returns zero bytes.

MACADDR II Usage

MACADDR II is a Win32 Console Application. It is meant to be run from within a Command Prompt window. To run MACADDR II, first change to the directory containing the MacAddr2.exe file. Then enter the command:

C:> macaddr2

The application will run and output to the console.

MACADDR II enumerates known MAC adapters in the NetCards registry key. It displays the following information extracted or constructed from the registry:

Adapter "Title"

Adapter Description

Adapter Name (name passed to NdisOpenAdapter)

For each MAC device found the program attempts to use the IOCTL_NDIS_QUERY_GLOBAL_STATS DeviceIoControl call to fetch:

OID_GEN_MEDIA_IN_USE

OID_XXX_CURRENT_ADDRESS.

Other information of interest to programmers is displayed as the MACADDR II application runs.

Sample MACADDR II Output

The output that you will see on your workstation will, of course, be different from the samples shown below. In addition, you need to understand that the NetCard registry enumeration mechanism will return all adapters that are currently "known" by the system. This includes adapters that may not be currently running.

For example, if you have installed a PC Card adapter but it is currently removed, the PC Card adapter will be returned in the enumeration. You would see an error message (e.g., CreateFile error 2) when this adapter is accessed.

In addition, MACADDR II has not been written to support all network media. A framework (current media switch table) can be easily extended to recognize and handle other media. If you make and test a modification to support other media, please send it to use to be included in a future release of MACADDR II.

Here are the sample outputs...

Windows NT MACADDR II Output

MACADDR II Sample For Windows NT And Windows 2000 V1.00.00.01.
Copyright (c) 2000 Printing Communications Associates, Inc.
<http://www.pcausa.com>
All rights reserved.
Running On Windows NT

+++++++++++++++++++++++++++++++++++
[1] 3Com Fast EtherLink XL Adapter (3C905)
    3Com Fast EtherLink XL PCI 10/100Mb Adapter (3C905)
    \Device\El90x1
Query On MS-DOS Device Name: "El90x1"
   DOS Device Name Existed.
   LinkName: "\Device\El90x1"
Medium: 802.3
Query On MS-DOS Device Name: "El90x1"
   DOS Device Name Existed.
   LinkName: "\Device\El90x1"
Mac address = 00-60-08-A3-29-D0

+++++++++++++++++++++++++++++++++++
[3] Intel EtherExpress PRO Adapter Bus 1 Slot 4
    Intel EtherExpress PRO Adapter
    \Device\E100B3
Query On MS-DOS Device Name: "E100B3"
   DOS Device Name Existed.
   LinkName: "\Device\E100B3"
Medium: 802.3
Query On MS-DOS Device Name: "E100B3"
   DOS Device Name Existed.
   LinkName: "\Device\E100B3"
Mac address = 00-90-27-8C-B4-91

+++++++++++++++++++++++++++++++++++
[4] Intel EtherExpress PRO Adapter Bus 1 Slot 5
    Intel EtherExpress PRO Adapter
    \Device\E100B4
Query On MS-DOS Device Name: "E100B4"
   DOS Device Name Existed.
   LinkName: "\Device\E100B4"
Medium: 802.3
Query On MS-DOS Device Name: "E100B4"
   DOS Device Name Existed.
   LinkName: "\Device\E100B4"
Mac address = 00-90-27-8C-B4-92

Windows 2000 MACADDR II Output

MACADDR II Sample For Windows NT And Windows 2000 V1.00.00.01.
Copyright (c) 2000 Printing Communications Associates, Inc.
<http://www.pcausa.com>
All rights reserved.
Running On Windows 2000

+++++++++++++++++++++++++++++++++++
[1] 3Com EtherLink XL 10/100 PCI TX NIC (3C905B-TX)
    3Com EtherLink XL 10/100 PCI TX NIC (3C905B-TX)
    \Device\{4750E11D-415E-4329-A6C5-645ACDCB1068}
Query On MS-DOS Device Name: "{4750E11D-415E-4329-A6C5-645ACDCB1068}"
   DOS Device Name Existed.
   LinkName: "\Device\{4750E11D-415E-4329-A6C5-645ACDCB1068}"
Medium: 802.3
Query On MS-DOS Device Name: "{4750E11D-415E-4329-A6C5-645ACDCB1068}"
   DOS Device Name Existed.
   LinkName: "\Device\{4750E11D-415E-4329-A6C5-645ACDCB1068}"
Mac address = 00-50-04-87-18-73

+++++++++++++++++++++++++++++++++++
[14] D-Link USB LAN Adapter
    D-Link USB LAN Adapter
    \Device\{A587CD7B-7308-41D8-8C51-BA46153EBC5C}
Query On MS-DOS Device Name: "{A587CD7B-7308-41D8-8C51-BA46153EBC5C}"
   DOS Device Name Existed.
   LinkName: "\Device\{A587CD7B-7308-41D8-8C51-BA46153EBC5C}"
Medium: 802.3
Query On MS-DOS Device Name: "{A587CD7B-7308-41D8-8C51-BA46153EBC5C}"
   DOS Device Name Existed.
   LinkName: "\Device\{A587CD7B-7308-41D8-8C51-BA46153EBC5C}"
Mac address = 00-E0-98-76-5B-7F

Release Notes

August 31, 2001 - Changed version number to V5.00.13.51 to track other PCAUSA products.

July 28, 2000 - Released V1.00.00.01.

Suggestions

Please let us know if you encounter difficulties using this program or if you have suggestions for improvement.

If you find missing functionality, have the time to make improvements and have the inclination to share your work, please let us know. We will consider incorporating your improvement and posting them here.

Terms Of Use

The MACADDR II software is provided "as is", without any guarantee made as to its suitability or fitness for any particular use. It may contain bugs, so use of this tool is at your own risk. PCAUSA takes no responsibly for any damage that may unintentionally be caused through its use.

You may use MacAddr II source code in your own product, either free or commercial, without requesting permission of PCAUSA. You will not owe PCAUSA any royalty for your use of code derived from MACADDR II. However, informing PCAUSA of products which benefit from PCAUSA code is encouraged.

You may NOT redistribute MacAddr II sources or executables or any of the MacAddr components that you downloaded without express written permission of PCAUSA.

If someone wants these items, then they must download them from the PCAUSA website.

Download MACADDR II Executables And Source

The PCAUSA MacAddr II sample code can be downloaded from the following URL:

macaddrsdk.exe
53.50KB (54784 bytes)

.

PCAUSA Home � Privacy Statement � Products � Ordering � Support � Utilities � Resources
Mailing Lists � PCAUSA Newsletter � PCAUSA Discussion List

Rawether for Windows and WinDis 32 are trademarks of Printing Communications Assoc., Inc. (PCAUSA)
Microsoft, MS, Windows, 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.
Send mail to webmaster@pcausa.com with questions or comments about this web site.
Copyright � 1996-2008 Printing Communications Assoc., Inc. (PCAUSA)
Last modified: December 31, 2007

MACADDR II IOCTL_NDIS_QUERY_GLOBAL_STATS Sample Application for Windows NT, Windows 2000 and Higher