Network Monitor

Purpose

Network Monitor captures network traffic for display and analysis. It allows you to perform tasks such as analyzing previously captured data in user-defined methods, extracting data from defined protocol parsers, and analyzing real-time traffic on your network.

Developer Audience

All API sets provided by Network Monitor can be accessed using C/C++. Those developers also working with network packet providers must also be familiar with COM.

Runtime Requirements

To call the Network Monitor API sets, you must be running on Microsoft® Windows NT® Server version 4.0 or Microsoft® Windows® 2000 Server, or have Microsoft® Systems Management Server installed.

The NPP driver and supported functionality ship with all versions of Windows NT version 4.0 and Microsoft Windows 2000 Server.

About Network Monitor 2.0

Network Monitor concepts and services.

Using Network Monitor

Task-related topics that describe how to use Network Monitor functions and COM components.

Reference

Reference topics for Monitor APIs, Parser and Expert APIs, NPP APIs, and BLOB APIs.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Legal Information

Network Monitor

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

©1998-2000 Microsoft Corporation. All rights reserved.

Active Directory, ActiveX, BackOffice, Developer Studio, DirectX, JScript, Microsoft, MS-DOS, MSDN, Visual Basic, Visual C++, Visual J++, Win32, Win32s, Win64, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


The Network Monitor SDK

Platform SDK: Network Monitor

Network Monitor Introduction

The Network Monitor portion of the Platform SDK extends the functionality of Network Monitor by helping you to create custom experts, protocol parsers, real-time monitors, and network packet providers (NPPs). This section includes the following documentation:

  • Programming topics needed to create experts, monitors, and parsers. This information also covers how to write a capture filter and use BLOBs and NPPs.
  • API-related reference information about experts, monitors, parsers, BLOBs, and NPPs.
  • A glossary of terms used in Network Monitor documentation.


System Requirements

The Network Monitor portion of the Platform SDK supports Microsoft® Windows NT® version 4.0 Service Pack 3 or later.

Minimum computer configurations differ; for Network Monitor development purposes, it is recommended that a Microsoft® Win32® developer have a computer that includes the following minimum specifications:

  • Pentium processor
  • 32 MB RAM
  • 30 MB available hard disk space
  • Video monitor and video card support for 256 colors at an 800 X 600 resolution
  • Network connection
  • Microsoft® Internet Explorer® 4.01
  • Microsoft® Visual C++® version 5.0

Testing a Win32 application developed with Network Monitor requires a computer with the following minimum specifications:

  • 486 processor running at least 50 MHz
  • 16 MB RAM
  • 20 MB available hard disk space
  • Network connection


Installing Network Monitor Files

To install and run the Network Monitor portion of the Platform SDK, follow this procedure.

To install and run Network Monitor Platform SDK files

  1. To install the files, during Platform SDK setup, select the Network Monitor documents and sample code.

    When setup is complete, the Platform SDK setup program creates a batch file, Setenv.bat.

  2. To initialize the required environment variables, run Setenv.bat.
  3. To compile the samples, run nmake, supplied by Microsoft® Visual Studio®.


Sample Applications

The sample applications included with the Network Monitor portion of the Platform SDK provide the framework you need to develop custom Network Monitor enhancements and applications. The Platform SDK includes the following Network Monitor samples:

  • Boilerplate Expert
  • Property Distribution Expert
  • Boilerplate Parser
  • Boilerplate Monitor
  • ICMP Redirect Monitor

In addition, the Platform SDK includes the header and library files needed to use the C++ samples. These files are contained in the following subdirectories:

  • \include
  • \lib


About Network Monitor 2.0

Network Monitor is a component of Microsoft® Systems Management Server (SMS) that enables you to detect and troubleshoot problems on LANs, WANs, and serial links running the Microsoft® Remote Access Server (RAS). Network Monitor provides real-time and post-capture modes of network data analysis.

In real-time analysis, network traffic is examined by real-time monitors. These monitors test network traffic for a specific set of conditions, and when those conditions are detected, display events, which may prompt end-user action. For example, a monitor can detect conditions that indicate a SYN attack and aid a network administer to respond to the potential attack.

In post-capture analysis, network traffic is saved in a proprietary capture file so that the captured data can be analyzed later. In this case, analysis can be in the form of protocol parsers picking out specific network frame types and displaying the frame data in the Network Monitor UI; or analysis can be in the form of experts examining the network data and displaying a report (experts may also manipulate the network data).

Network Monitor provides the following types of functionality:

  • Captures network data in real-time or delayed mode.
  • Provides filtering capabilities when capturing data.
  • Uses monitors for real-time analysis and security.
  • Uses experts and parsers for detailed post-capture analysis.

This section provides basic descriptions of Network Monitor features and functionality. Topics include:

  • Network Monitor Architecture
  • Experts
  • Parsers
  • Network Packet Providers
  • Network Monitor BLOBs
  • Event Reference Page
  • Capture Filters


Network Monitor Architecture

The Network Monitor architecture can be separated into two sets of programming concepts, those related to expert and parser development and those related to monitor development.

Although both use the same components to capture the network traffic, they each use different interfaces to capture the data and different components to analyze what was captured.

For information on | Go to
The components of Network Monitor related to expert and parser development | Expert and Parser Architecture
The components of Network Monitor related to monitor development | Monitor Architecture


Expert and Parser Architecture

The following figure shows the relationship between expert and parser applications and other components of the Network Monitor architecture.

The network traffic is collected (as individual frames) from the NDIS driver. The Network Monitor driver (Nmnt.sys) then routes the frames to a network packet provider (NPP), which in turn captures the data and places it in one or more capture files. The NPP is a collection of COM interfaces used to capture data. In this case, the IDelaydC interface is used to perform a delayed capture.

Note The NPP is used for delayed and real-time captures. For real-time captures used by monitors, the IRTC interface is used.

Once the network frames are stored in the capture file and the file is accessible, experts and parsers can use the Network Monitor UI and the Network Monitor functions provided in Nmapi.dll to analyze the data. Capture files are not accessible until the capture is complete.


Monitor Architecture

The following figure shows the relationship between monitors and other components of the Network Monitor architecture.

The network traffic is collected (as individual frames) from the NDIS driver. The Network Monitor driver (Nmnt.sys) then routes the frames to a network packet provider (NPP), which in turn captures the data in real-time mode. The NPP is a collection of COM interfaces used to capture data. In this case, the IRTC interface is used to perform a real-time capture.

Note The NPP is used for delayed and real-time captures. For delayed captures used by experts and parsers, the IDelaydC interface is used.

The monitor then examines the captured data in real-time mode, detecting specific network conditions and generating events as needed.

Three other components are used by monitor applications: the Monitor Control Tool, the Monitor Control Service (MCSVC), and the Event Viewer:

  • The Monitor Control Tool is used to manage your monitor applications. This includes configuring and running all your monitor applications.
  • The Monitor Control Service (MCSVC) fires events, provides a communications link to WMI for event viewing, and coordinates the processing of monitor operations.
  • The Event Viewer displays the events fired by the Monitor Control Service.


Monitors

A monitor is a Microsoft® Win32® dynamic-link library (DLL) that examines real-time captures of network traffic. It searches for pre-defined conditions and then generates events when those conditions are detected. For example, an event may be fired when a network break-in is attempted, when a rogue workstation is handing out IP addresses, or when a router fails.

Note If you need to perform detailed analyses on network data that requires a post-capture analysis, you must use expert and parser applications.

The Monitor Control Service (MCSVC) provides the frameworkfor managing your monitors. It provides functions to load the monitor DLLs, and a communications interface to the Monitor Control Tool so that you can create, configure, start, stop, and disable multiple instances of your monitors.

Monitors run in two threads of execution. The MCSVC provides the first thread, which provides direct control of the monitor. The second thread is provided by the network packet provider (NPP), which provides a way to pass the captured network data, statistics, and the status of the capture from the NPP back to the monitor.

More than one instance of the same monitor can exist for each run-time NPP interface used to capture data.


Real-Time Captures

Monitors receive captured network frames in real-time mode. The frames are captured by a network packet provider (NPP) using the provider's IRTC COM interface, and passed on to the monitor in one of the monitor's two execution threads.

Monitors can limit the number of frames they have to process by passing a capture filter to the NPP that is supplying the frames. Typically, a specific monitor is designed to watch for specific types of traffic, such as HTTP, RIPX, or SMB. Unlike experts, which use sophisticated parsers to select the information to be analyzed, a monitor must examine each frame for the conditions it was designed to detect. The reason behind this frame-by-frame approach is performance. A monitor must process its frames quickly enough so that it does not fall behind the driver supplying the frames to the NPP. Otherwise, data will be lost.


Monitor Events

Monitors are designed to use Windows Management Instrumentation (WMI) to fire events to local or remote computers.

Note Because monitors use a real-time capture they can only capture data at the local computer. This is a limitation of the network packet provider's IRTC interface. However, by using WMI events, the captured data can be examined locally while events can be sent to local or remote computers.

Monitors do not communicate directly with WMI. The Monitor Control Service (MCSVC) provides an interface (called IMonitorEventer), which the monitor can use to obtain an event data structure and fill it with the relevant information. The MCSVC can then send the event data structure to WMI, which in turn fires the event.


Monitor Event Reference Pages

Event reference pages (ERPs) can be used connect your monitor to the Network Monitor UI. They can be used to alert end-users about detected conditions and problems, or they can be used to provide suggested fixes or explanatory data.


Monitor Configuration

Monitors can be configured using the Network Monitor UI. End-users can pass configuration criteria to your monitor using an HTML form that is stored as an HTM file in the following sub folder of your installed Network Monitor SDK:

%SystemRoot%\System32\Npp\Monitors

When an end user selects the Set Monitor Configuration button, the browser generates an HTML POST message, which includes the names and values for all the HTML form elements.

When the MCSVC calls the IMonitor::DoConfigure method, the pConfiguration parameter points to the data from the POST message. The following code fragment provides an example of POST message data:

ConfigString="FilePath=c%3A%5Ccaptures&StartingNumber=50 \
    &EndingNumber=256&MaximumNumberEver=10000 \
    &TimeBetweenNotification=120&\
    Addresses=157.54.23.23%0D%0A157.54.23.22% 0D%0A

This data is passed in as a long ASCII string. The string looks peculiar, both for its length and the appearance of sections such as %3A%5C and %0D%0A. This peculiarity is caused by HTML, which requires that a method put all possible ANSI, DBCS, and Unicode strings into an ASCII format. For example, the DoConfigure method inserts certain characters such as the ampersand (&) in front of each variable name to identify it as a variable name. The %3A%5C is an encoded form of the colon character, and %0D%0A indicates a carriage return/linefeed pair. The following code fragment provides the resulting HTML code as interpreted by the monitor:

FilePath = c:\captures
StartingNumber=50
EndingNumber = 256
MaximumNumberEver = 10000
TimeBetweenNotification = 120
Addresses= {157.54.23.23, 157.54.23.22}


Local-Only and Promiscuous Modes

Monitors can examine frames in local-only mode or promiscuous mode.

In local-only mode, the network packet provider (NPP) returns frames that are sent to or from the computer on which the monitor is running, including broadcasts and multicasts directed to the local machine. Although limited to locally directed frames, local-mode is also much less processor intensive.

In promiscuous mode, the monitor can also watch for traffic that is not directed to or from the local computer. Unless the monitor has specified the flag, MCS_CREATE_PMODE_NOT_REQUIRED, in the OnLoadingDLL function, the Monitor Control Service (MCSVC) assumes that the monitor requires promiscuous mode when it loads the monitor DLL.


Experts

Platform SDK: Network Monitor

Expert

An expert is a Microsoft® Win32® dynamic-link library (DLL) that analyzes network traffic collected by a network packet provider (NPP), and placed in a capture file. After the data is captured and stored in a capture file, the expert works with a parser (also referred to as a protocol parser) to analyze the data in the file. For example, you can examine the frames of the capture file and use a parser to recognize protocols such as server message block (SMB), or Transmission Control Protocol/Internet Protocol (TCP/IP).

Note An expert does not analyze real-time data. If you must analyze data in real-time mode, use the Network Monitor monitor.

You can design an expert to work with all of the Network Monitor parsers, and any parsers that you create yourself.

After a requested match of protocols identifies a specific frame, the expert extracts data from the frame. You can program the expert to manipulate information into usable data that the Network Monitor Event Viewer displays.

You can configure an expert at run time, and then use Network Monitor to save user configuration data for reuse with different capture files. You can use an expert to provide correlation data and custom resolutions for end users. For more information about the creation of HTML-based configuration information, see Event Reference Page.

During Network Monitor setup, the following expert DLLs are installed in the Experts sub-directory:

  • Coalesce.dll
  • Propdist.dll
  • Protdist.dll
  • Resptime.dll
  • Tcpipe.dll
  • Topuser.dll

When you start Network Monitor, the DllMain function builds all experts in the experts subdirectory. When the user selects Experts on the Tools menu of the Network Monitor UI, Network Monitor loads the expert DLLs. The expert is called through the Register Expert entry point to provide basic details about the expert.

Network Monitor calls the following functions to manage the expert:

  • DllMain
  • Register Expert
  • Run
  • Configure

The expert must implement each of the preceding functions.


Parsers

Platform SDK: Network Monitor

Parser

A parser is the Network Monitor component that inspects the information in a delayed capture, and passes specific protocol information to the application that calls the parser. A parser is passive because it works only when Network Monitor or an expert call it.

Each parser identifies one protocol, and typically, a parser is implemented within its own parser DLL. However, a parser DLL can contain multiple parsers which means that one DLL can be used to detect more than one protocol.

The information passed to a parser is taken from a delayed capture, and passed to the parser on a frame-by-frame basis. You cannot parse a real-time capture.

To parse the data in a frame, the parser must recognize the protocol instance, identify the properties that exist in the protocol instance, and attach a property definition to each property. Note that the frame contains only a stream of data. The frame does not contain data that indicates which protocols or protocol properties the data represents.

The following illustration shows a frame that contains an instance of a protocol.

If Network Monitor is going to display parsed data in the UI, the parser must format the information. However, some experts use the parser output programmatically, and do not display the output in the Network Monitor UI. Displayed information includes both parser-defined data, and the data in the capture. For example, the parser typically provides both a name for a property that is displayed, and the data in the capture that is associated with the property.

For information on | See
Which entry points must be implemented within the parser DLL. | Parser DLL Architecture
How to implement parser DLL export functions. | Writing a Protocol Parser
Which functions and structures parsers use. | Parser Functions and Structures


Parser DLL Architecture

The architecture of the parser DLL must provide the functionality shown in the following illustration. Note that some functionality requires the implementation of only one entry point. However, if your parser DLL supports multiple protocols, then the functionality requires the implementation of multiple entry points.

For information on | See
How to implement parser DLL export functions. | Writing a Protocol Parser
Specific functions and structures that parsers use — reference topics. | Parser Functions and Structures


Property Definition and Property Instance Structures

Network Monitor provides a PROPERTYINFO structure to define the properties of a protocol, and a PROPERTYINST, and PROPERTYINSTEX structure to define an instance of a property.

The parser allocates and fills-in the PROPERTYINFO structure for all the properties that a protocol supports. The parser passes the structure to Network Monitor where the structure is added to the protocol property database. The information in the PROPERTYINFO structure is used when parsing an instance of a property, and when formatting the data that is displayed in the Network Monitor UI.

Network Monitor allocates the PROPERTYINST and PROPERTINSTEX structures when the parser attaches a property definition to an instance of a property.

The following procedure identifies the steps necessary to attach a property definition.

To attach a property definition

  1. Identify each property that exists in an instance of the protocol. When attaching a definition, Network Monitor passes the captured data to the parser. The data is passed on a protocol instance basis.
  2. Determine the location of the property in the protocol instance.
  3. Attach a property definition to the property location.

Network Monitor implements a PROPERTYINST structure when the parser uses the property data as it exists in the capture. Network Monitor implements a PROPERTYINSTEX structure when the parser must modify the property data in the capture.


Network Packet Providers

Network packet providers (NPPs) are Network Monitor system components that collect network traffic (frames) from the network and pass them on to the Network Monitor UI, custom monitors, and NPP applications.

The illustration below shows two NPPs: the NDIS NPP provided by Network Monitor and a custom NPP.

The NDIS NPP provided by Network Monitor is Ndisnpp.dll. This NPP uses the Network Monitor system driver (Nmnt.sys) to get the frames collected from the network and several COM interfaces (referred to as the NPP interfaces) to pass the frames on to the Network Monitor UI, monitor applications, and NPP applications, where they can be displayed and analyzed.

Ndisnpp.dll connects to the NDIS layer to obtain its network traffic. (Custom NPPs can bypass the NDIS layer and communicate directly with the networking hardware.) Note that regardless of whether an NPP uses NDIS, NPPs can connect to any number of network cards and that all NPPs must support the same NPP interfaces.

Before an application can start to capture data, it must do three things: select the network interface card (NIC) that will connect the NPP to the network, select the NPP interface that will be used to capture the network frames, and use the selected interface to connect to the NIC.

For information on | See
The three ways to enumerate and select a network interface card | Selecting a Network Interface Card
COM interfaces exposed by NPPs | Selecting an NPP Interface


Selecting a Network Interface Card

Network Monitor provides three functions for selecting a network interface card (NIC). These functions provide three ways to enumerate a set of NICs and select the one you want to use. The following table describes these functions.

Function | Description
GetNPPBlobFromUI | Uses the Network Monitor UI to display the registered NICs and returns the NPP BLOB that represents the NIC you are interested in.
GetNPPBlobTable | Returns a BLOB table. It is the application's responsibility to enumerate the table and select an NPP BLOB.
SelectNPPBlobFromTable | Uses the Network Monitor interface to display the supplied NPP BLOBs and returns the NPP BLOB that represents the NIC you are interested in.

Each NIC is represented by an NPP binary large object (BLOB). These functions can return a single NPP BLOB from those registered on the computer, a single NPP BLOB from a supplied NPP BLOB table, or a table of NPP BLOBs that the caller must then use to select a specific BLOB. In the first two cases, when selecting from the registered NICs or from a supplied NPP BLOB table, the Network Monitor UI displays the NICs you can select.

Note Network Monitor uses a feature called the NPP Finder to enumerate the NICs registered on the local computer. The NPP Finder is a component of Npptools.dll.

For information on | See
Selecting a NIC registered on the local computer | Selecting a Registered NIC
Selecting a NIC from a supplied NPP BLOB table | Selecting a NIC from a Supplied NPP BLOB Table
Retrieving an NPP BLOB table | Selecting a NIC from a Returned NPP BLOB table


Selecting a Registered NIC

To select one of the NICs registered on the local computer, call the GetNPPBlobFromUI function. This function uses the Network Monitor UI to display the registered NICs and returns the NPP BLOB that represents the NIC you select. You can display all the NICs registered on the local computer or a smaller set of filtered NICs. To filter the NICs that are displayed, you can provide a filter BLOB when the call is made.

Note When the GetNPPBlobFromUI function is called, the NPP Finder communicates with the NPP DLLs to obtain the NPP BLOB structures that represent the registered NICs. For a procedure on how to use the Network Monitor UI directly, see the "Select a Network Dialog Box" topic in the Network Monitor online help.

When you call the GetNPPBlobFromUI function, the Select a network dialog box appears. From it, you can view the details of the NPPs registered on the local computer. This information includes both local NPPs and remote NPPs. From the dialog box, you can select a specific NIC and view the details of its associated NPP BLOB structure.

The following illustration shows typical settings of an NDIS NPP supplied by Network Monitor.

Use the following table to find the topic that describes each NIC selection method.

For information about | See
How to specify a filter that limits the NICs displayed in the Select a network dialog box. | Specifying a Filter BLOB
How to select a NIC by calling the GetNPPBlobFromUI function. | Selecting a NIC using GetNPPBlobFromUI
How to select a NIC from a supplied NPP BLOB table. | Selecting a NIC from a Supplied NPP BLOB Table


Selecting a NIC from a Supplied NPP BLOB table

To select a network interface card (NIC) from a supplied NPP BLOB table, call the SelectNPPBlobFromTable function. This function uses the Network Monitor UI to display the NICs represented in the BLOB table and returns the NPP BLOB that represents the NIC that is selected.

When you call the SelectNPPBlobFromTable function, the Select a network dialog box appears. From it, you can view the details of the NPPs represented in the NPP BLOB table, select a specific NIC, and view the details of its associated NPP BLOB structure.

The following illustration shows the NICs represented in a supplied NPP BLOB table.

For information about | See
Selecting a NIC registered on the local computer | How to select a registered NIC
Retrieving an NPP BLOB table | How to select a NIC from a Returned NPP BLOB table


Selecting a NIC from a Returned NPP BLOB table

To select a NIC from an NPP BLOB table returned by Network Monitor, call the GetNPPBlobTable function. This function returns an NPP BLOB table, which can then be enumerated by your application to select the NIC you are interested in.

When you call this function you can return either a BLOB table of all the NICs registered on the local computer or a smaller set of filtered NICs. To filter the NICs that are returned, you can provide a filter BLOB when the call is made.

For information about | See
How to specify a filter that limits the NICs returned in an NPP BLOB table. | Specifying a Filter BLOB
How to select a NIC registered on a local computer. | Selecting a Registered NIC
How to select a NIC from a supplied NPP BLOB table | Selecting a NIC from a Supplied NPP BLOB Table


Specifying a Filter BLOB

When you select a registered network interface card (NIC) listed on a local computer, you can use a filter BLOB to disregard the NICs you are not interested in. For example, you could restrict the search for a specific type of card (such as ETHERNERT) or a specific MAC address.

During the search for a NIC, every entry in the filter BLOB must match an equivalent entry in the NPP BLOB that represents the NIC. Filter BLOBs can also be special BLOBs.

When the GetNPPBlobFromUI function is called, the filter BLOB restricts the NICs displayed in the Select a network dialog box. When the GetNPPBlobTable function is called, the filter BLOB restricts the NICs returned in the BLOB table.

To use the filter, you must create a filter BLOB, set the values of the properties you want to filter on (including any special BLOB entries), and then specify the BLOB filter and a call to the GetNPPBlobTable or GetNPPBlobFromUI function.

For information on | See
How to select a NIC registered on a local computer | Selecting a Registered NIC
Retrieving an NPP BLOB table | Selecting a NIC from a Returned NPP BLOB table


Selecting an NPP Interface

Network packet providers (NPPs) expose the IDelaydC, IESP, IRTC, and IStats interfaces. Each of these interfaces provides similar methods for connecting the NPP to the network, capturing network traffic, and collecting statistical information about the captured data. To choose which interface to use, refer to the following table.

Note When you connect an NPP to the network with one of these interfaces, you can only use the methods provided by that interface. For example, if you connect to the network using the IRTC interface and then try to start a capture with IDelaydC, your call to start the capture will fail, and an error code will be returned.

Interface | When to use
IDelaydC | Use to capture network traffic and store it in a capture file. This interface is used by the Network Monitor UI and other NPP applications, which require storing captured network information.
IESP | Used to provide enhanced statistics in a special ESP file format. This interface is used by NPP applications that require the enhanced statistics provided by the ESP format.
IRTC | Use to capture real-time network traffic and to trigger events when they occur. This interface is used by monitors and NPP applications that require run-time captures. Note that this interface does not provide the statistics that the other NPP interfaces provide, nor does it allow you to insert frames into the captured network traffic.
IStats | Use to retrieve capture statistics but not the captured frames.


The Capture Process

The capture process is the same for each of the four NPP interfaces. In each case, the process includes:

  • Obtaining the NPP interface object you want to use
  • Connecting to the network
  • Starting and then stopping the capture
  • Disconnecting from the network

Note Once you obtain the interface object that you want, make sure you call only the methods included in that interface. As you can see in the illustration below, each interface provides similar methods for capturing network data. An error is returned if you connect to the network with one interface and then try to run a capture using the methods from another interface.

The following illustrations show two different ways you could run a capture. The first illustration shows how to run one or more sequential captures, allowing you to create any number of independent captures.

As shown above, after you connect to the network you can start and stop a capture as many times as you wish, starting a new capture and generating new statistics every time you restart the capture. For example, for a delayed capture using the IDelaydC interface, a new capture file would be created each time you restarted the capture.

However, also note that every time you restart the capture process you must call the appropriate configure method to reconfigure the connection. For the initial call to start the capture, the connection is configured by the call to connect to the network.

The second illustration shows how you could run a single capture by pausing and restarting.

In this case, you can pause and restart a capture as many times as you want. With this approach, you can run a capture whose data (and its related statistics) are recorded as a single capture. For example, to perform a delayed capture using the IDelaydC interface, all the captured network information would be saved in a single capture file.


Network Monitor BLOBs

The Network Monitor binary large object (BLOB) is a generic data structure that contains configuration and location information of network interface cards (NICs). You can use BLOBs to represent NICs and to filter entries in a list of NICs. BLOBS can also contain application-specific information without affecting the other data that they hold. BLOB implementation is opaque to all levels that must access BLOBs with BLOB APIs.

BLOB Structure

Think of a BLOB as a hierarchical tree that you can use to designate strings. This tree has three layers: Owner, Category, and Tag. Owner is a string that indicates, in general, who cares about (and in most cases, who will be reading) an entry. The Category is also a string, which designates a general functional grouping of tags under the owner. The Tag is the actual name of the entry.

BLOBs also have these structural characteristics:

  • BLOB helpers within one process are protected from one another by a mutex built into each BLOB.
  • Each BLOB has an internal version number so that the helpers can deal with both present and future BLOB forms. Version conflicts may occur if you send a BLOB to another machine with RPC.
  • The BLOB itself is just a pointer to a void. It is very important that applications allocate BLOBs with the const modifier to keep from altering the contents.
  • Each of the designators, as well as their values, are strings. Remember that the strings returned by GetString functions are actually pointers into the BLOB and should not be changed. For this reason, these strings must be specified as const char *pX to keep applications from accidentally changing them.

In general, all parameters with the const designator encourage the caller to refrain from changing the values rather than prohibit the helper functions from changing them. In fact, the helper functions will usually change those values.


BLOB Types

Network Monitor uses three types of binary large objects (BLOBs) to select and connect network interface cards (NICs), capture data, and manipulate NPP data.

NPP BLOB

Applications use NPP BLOBs to connect to a specific NIC through an NPP. (The application makes the connection with a call to CreateNPPInterface and location information in the NPP BLOB.) An application can also store its configuration data in the NPP BLOB to configure the NPP. Also, an application that saves its NPP BLOB does not need to go through the Finder to use that BLOB again.

Filter BLOB

A filter BLOB contains application-defined criteria that you can use to select an NPP and a NIC. For instance, an application can request a specific NIC, only Ethernet cards, or cards that support a specific frame capture rate.

Special BLOB

When an NPP requires additional information before it can return an NPP BLOB to an application, the NPP uses a special BLOB. Most often, the application will not need or use special BLOBs so they aren't returned to an application unless a specific flag is set in one function call. For example, a remote NPP uses a special BLOB because a path name is required to make a connection. An application that receives a remote NPP special BLOB could add the string and call back into the Finder to get an NPP BLOB table. See Special BLOB Entries for examples.


BLOB Components

A binary large object (BLOB) includes the following hierarchical components:

  • Owners
  • Categories
  • Tags
  • Values

Textual Representation

For convenience, BLOBs appear in the Owner:Category:Tag:Value format that they appear in when they are saved to a file. The internal structure of the BLOB is opaque because it represents pointers and tables. For example, here is an entry from a BLOB that can be used to configure an NPP:

NPP:Configure:BufferSize=32768

The Owner is NPP. (Although a monitor may have made the entry in the BLOB, the NPP is listed as the Owner because the NPP is the component that must read the entry.) The Category is Configure, the Tag is BufferSize, and the Value is 32768.


Special BLOB Entries

The following code fragments are examples of special BLOB entries.

NPP Name

SetStringInBlob(
   hBlob,
   OWNER_NPP,
   CATEGORY_LOCATION,
   TAG_NAME,
   "My NPP Name");

NPP Class Identifier

SetClassIDInBlob(
   hBlob,
   OWNER_NPP,
   CATEGORY_LOCATION,
   TAG_CLASSID,
   &CLSID_ThisNPP);

CFGPROC Procedure Name

SetStringInBlob(
   hBlob,
   OWNER_NPP,
   CATEGORY_FINDER,
   TAG_PROCNAME,
   "MyGetNPPBlobs");

Tree Root Name for Finder UI

SetStringInBlob(
   hBlob,
   OWNER_NPP,
   CATEGORY_FINDER,
   TAG_ROOT,
   "My Tree Root name");

Display String for Finder UI

SetStringInBlob(
   hBlob,
   OWNER_NPP,
   CATEGORY_FINDER,
   TAG_DISP_STRING,
   "Double click to select my UI");

Interface Tags

This should include every interface supported by the NPP.

SetBoolInBlob(
   hBlob,
   OWNER_NPP,
   CATEGORY_CONFIG,
   TAG_INTERFACE_REALTIME_CAPTURE,
   TRUE);


Event Reference Page

This section describes the event reference page (ERP), an HTML-based document that you can write to display events that occur during the operation of a Network Monitor expert or monitor. After you define the requirements of creating experts or monitors, you can use ERPs to help Network Monitor or Monitor Control Tool users to solve network problems.


About Event Reference Pages

An event reference page (ERP) is an HTML document that gives Network Monitor and Monitor Control Tool users information about events detected during expert or monitor operation.

You can view ERPs in the Event Viewer of Network Monitor, Monitor Control Tool, or in any browser that supports the HTML features of Microsoft® Internet Explorer Version 4.01 or later. This means that you can add supported controls or scripted languages into your ERP.

However, ERPs appear only if the monitor or expert designates the HTML document by name. When properly designated, the ERP appears in the lower pane when the event in the Event Viewer is selected. The figure below shows an ERP associated with the Internet Protocol (IP) Range monitor.

Expert and Monitor Events

When the IP Range monitor finds an invalid IP destination address on a network packet, the monitor generates an event. This event appears in the top pane of the Event Viewer (The justification field of the NMEVENTDATA structure occupies the middle pane.) The Event Viewer then seeks an HTM file that corresponds with the IP Range monitor event. When the file is found, the ERP appears in the bottom pane of the Event Viewer. The ERP indicates what the event means and how the user might deal with the situation. For example, the ERP might indicate, "The corporate firewall has been breached. Call the Network Security Administrator."

Expert or monitor events are identified by the EventIdent member of an NMEVENTDATA structure. When you write an expert or monitor, you determine the EventIdent values, which are typically numbered 1, 2, 3, and so on. For example, suppose that an expert generates two events (EventIdent1 and EventIdent2). If you want the Event Viewer to display the events separately, you must create two separate ERP documents.


Capture Filters

The Network Monitor SDK includes capture filters, with which you can restrict the number of frames a monitor or network packet provider (NPP) application receives during its operation. By specifying which frames of network traffic you want a custom monitor or NPP application to examine, you can improve its processing efficiency.

This section includes these topics:

  • About Capture Filters
  • The CAPTUREFILTER Structure


About Capture Filters

A capture filter is an element of a monitor or NPP application that tells the Network Monitor driver (Nmnt.sys) which frames of network information to retain and which frames to ignore. The advantage of setting a capture filter is greater efficiency. You don't have to examine captured frames; the Network Monitor driver examines them automatically. This approach eliminates frame copying, which provides a memory use advantage.

Capture Filter Structure

Capture filters consist of three elements:

  • Etype/SAP settings
  • Address
  • Pattern match

Together, these elements logically evaluate which frames to include or exclude during the operation of a monitor or NPP application. The capture filter supplies complex matches and exclusions of frame elements to the client monitor or NPP application.

Network Monitor implements the capture filter through a data structure, CAPTUREFILTER, which is passed to the NPP and then passed on to the Network Monitor driver when you start the capture.

For more information about NPP operations and BLOB functionality, see Network Packet Providers and Network Monitor BLOBS.


The CAPTUREFILTER Structure

In Network Monitor, the capture filter is defined by the CAPTUREFILTER structure. The absence or combination of flags, values, and expressions determines which frames will be passed on or dropped by the Network Monitor driver. The illustration below shows the three areas of the capture filter analysis: Etype/SAP, address, and pattern match.

The following table describes the function of each capture filter element.

Filter element | Action
Etype/SAP | Evaluates Etype/SAP settings. The combination of flags determines which setting types or values are included or excluded.
Address | Evaluates source and destination addresses and address pairs. Different combinations of flags determine which individual values or combinations of address pairs are included or excluded.
Pattern Match | Defines complex pattern matches within a frame. Flags are provided for different types and offsets. You can combine pattern matches with logical AND or OR statements.
Clipping | Clips frames in a manner specified by various byte values. You can use only this element to clip all frames or use it with other capture filter elements (to find and then clip a single frame, for example).
Trigger | This capture filter element is obsolete. Triggers are no longer part of a capture filter; they are now contained in their own BLOB tags, which are specified separately.

A frame is evaluated against all three portions of the capture filter. Therefore, a successfully transmitted frame must pass each element. Note that the Network Monitor driver evaluates the absence of any of the three elements as TRUE. For example, the driver evaluates the absence of an Etype/SAP section as "ALL frames with the ANY Etype/SAP value are valid."


Using Network Monitor 2.0

You can use Network Monitor for a wide variety of monitoring and analytical tasks, including:

  • Monitoring real-time network data
  • Analyzing network traffic
  • Providing network statistics and packet information
  • Creating expert and monitor event reference pages
  • Creating capture filters
  • Writing a Protocol Parser


Monitoring Real-Time Network Data

This section describes how to develop, test, and implement real-time monitors that can be used with the Monitor Control Tool. This section includes the following topics:

  • Specifying Protocol Information
  • Setting the Callback Frequency
  • Installing a Monitor to Network Monitor
  • Coding the Monitor
  • Creating a Monitor Capture Filter
  • Building a Generic Monitor
  • Testing a Monitor
  • Debugging a Monitor


Specifying Protocol Information

The Network Monitor driver can add information to the frame table by specifying which low-level protocol (IP or IPX) was found and the offset to the beginning of the protocol. To add this information to the frame table, set the ANY capture filter.


Setting the Callback Frequency

Use the following code to set the callback frequency:

DWORD Value = 1;

rc = SetDwordInBlob(hNPPBlob, OWNER_NPP, CATEGORY_CONFIG,
                    TAG_UPDATE_FREQUENCY, Value);

This code fragment sets the callback frequency to 1 second (the minimum value). The maximum value must be much larger than 1. If the network packet provider (NPP) buffer is full, the NPP calls the monitor back sooner.


Installing a Monitor to Network Monitor

Installing a monitor DLL is a simple process. First, copy the DLL and the associated HTML configuration form to your NPP Monitors subdirectory (for example, C:\Winnt\System32\Npp\Monitors). When copied to the directory, the monitor will be recognized and available the next time the Monitor Control Tool or Monitor Control Service (MCSVC) is activated.

For example, if the environment variable, %SystemRoot%, in Microsoft® Windows NT®/Windows® 2000 is C:\Winnt, then the monitor subdirectory is C:\Winnt\System32\Npp\Monitors.


Coding the Monitor

All monitors are Component Object Model (COM) DLLs that support the IMonitor interface. Each monitor DLL also has two exported functions that the Monitor Control Service (MCSVC) uses to load default values and to create instances of the monitors.

Unlike most COM objects, monitors do not require class factories or a unique CLSID because they can only be used by the MCSVC.

The Network Monitor SDK includes the functions and sample code you need to build custom monitors. The following list identifies the functions you need to build a monitor:

  • OnLoadingDLL
  • DllGetMonitorObject
  • DoInitialize
  • DoConfigure
  • OnStart
  • OnStop
  • OnFrames
  • OnStatus

To customize your source code, review the monitor interface and function reference pages. Then, use the sample code and procedures listed in Building a Generic Monitor to create a generic monitor.

Monitors can notify the MCSVC of event conditions by using the methods of the IMonitorEventer interface. These interfaces are:

  • GetEventData
  • SendNMEvent
  • FreeEventData

The MCSVC hands the monitor (in DoInitialize) an IUnknown pointer. The monitor makes a QueryInterface call to get the IMonitorEventer interface. (For information about BLOB functions that are supplied to monitors, see Network Monitor BLOBS.)

As a general rule, it is most efficient for a monitor to get all its NMEVENTDATA structures allocated once (probably in DoConfigure), rather than trying to allocate just when they are needed.

Note The NMEVENTDATA structure is used for experts, as well as monitors.

STDMETHODIMP CTestMon::DoInitialize(IUnknown*  pUnk)
{
    HRESULT hr = pUnk->QueryInterface(IID_IMonitorEventer,
                                      (LPVOID*) &m_pMonitorEventer);

    if (hr != NOERROR)
        return hr;

      // Create an event with space for two columns
    hr = m_pMonitorEventer->GetEventData(2, &m_pEventData);
    if (hr != NOERROR)
        return hr;

    // Initialize our eventdata –
 // In this case we're going to send back IP addresses in
 // the columns.
    m_pEventData->EventIdent   = 1;
    m_pEventData->Version   = 1;
    m_pEventData->Flags   = 0;
    m_pEventData->Severity   = 1;
    m_pEventData->NumColumns   = 2;
    m_pEventData->Column[0].szColumnName   = "Src Address";
    m_pEventData->Column[0].VariantData.Type  = NMCOLUMNTYPE_IPADDR;
    m_pEventData->Column[1].szColumnName   = "Dst Address";
    m_pEventData->Column[1].VariantData.Type   = NMCOLUMNTYPE_IPADDR;
    m_pEventData->Justification   = "justification here";
    m_pEventData->szEventName   = NULL;
    m_pEventData->szUrl   = NULL;
    m_pEventData->szDescription   = "Warning from TestMon";
    return 0;
}

When it is appropriate to send an event (usually in the OnFrames function), the monitor may add other data. For example:

// Add the time to the event
GetLocalTime(&(m_pEventData->SysTime));

// copy the src and dst addresses
m_pEventData->Column[0].VariantData.Value.IPAddrVal = ulpIP->SrcAddr;
m_pEventData->Column[1].VariantData.Value.IPAddrVal = ulpIP->DstAddr;

// have the MonitorEventer send the event
rc = m_pMonitorEventer->SendNMEvent( m_pEventData );


Creating a Monitor Capture Filter

Creating a capture filter that works with Network Monitor is a five-step process:

  • Setting the Etype or SAP Filter
  • Writing ADDRESSTABLE Filter
  • Writing the PATTERNMATCH Filter
  • Clipping a Frame
  • Implementing the Capture Filter Code

A capture filter is a series of additions to the NPP BLOB that selects which frames are passed back to the monitor. If a monitor does not alter the NPP BLOB, then the NPP will go into promiscuous mode and send all network traffic to the monitor. The NPP is most efficient if it can reduce the data handed up to a driver, so a monitor should create a capture filter. A monitor sets its capture filter by writing to the NPP BLOB in the call to the DoConfigure function. The MCSVC then calls the NPP with the NPP BLOB. See Capture Filters for more details on the capture filter, Network Packet Providers on NPPs, and Network Monitor Blobs on BLOB functions.


Setting the Etype or SAP Filter

Setting the Etype or SAP portion of the capture filter is the first step in the capture filter creation process.

In the following example, the capture filter is set to only retrieve IPX traffic:

BYTE Sap[]   = { 0x10, 0xE0 };
WORD Etype[] = { 0x8137 };

rc = SetNPPEtypeSapFilter(m_hBlob,
     2,      //  nSaps,
     1,      //  nEtypes,
     &Sap,   //  LPBYTE lpSapTable,
     &Etype, //  LPWORD lpEtypeTable,
     0,      //  DWORD  FilterFlags,
     NULL
);

Notes SAP and Etype values are usually available in RFCs.

Both SAP and Etype values can be in an array.


Setting a Pattern Match

See Capture Filters for details on setting a pattern match within a capture filter.


Processing Frame Data

In the following example, the monitor sets a capture filter specifying IP only and requested protocol information:

STDMETHODIMP CTestMon::OnFrames(UPDATE_EVENT Event)
{
    DWORD i;
    LPFRAMETABLE lpFrameTable = Event.lpFrameTable;

    // the frame table can wrap the indices
    for (
    i = lpFrameTable->StartIndex;
    i != lpFrameTable->EndIndex;
    (i == lpFrameTable->FrameTableLength ) ? i=0: i ++ )
{
    LPFRAME_DESCRIPTOR lpFrameDesc = &lpFrameTable->
Frames[i];

    // Cast the frame data to an unaligned pointer to an IP
    // structure We might want to put a try/catch around this,
    // but if set the capture filter correctly we KNOW this is
    // IP
    ULPIP ulpIP = (ULPIP)
(&lpFrameDesc->FramePointer[lpFrameDesc->
LowProtocolOffset]);
    // Now examine the IP frame for something.

}
return NOERROR;
}


Building a Generic Monitor

The Platform SDK includes a sample monitor called BLRPLATE Monitor, which is located in the \Monitors\Blrplate subdirectory (C:\Program Files\Platform SDK\Samples\Netds\Netmon\Monitors\Blrplate, for example.)

To build a custom monitor by using the sample DLL

  1. Open a Network Monitor command prompt and navigate to the Network Monitor SDK monitors subdirectory.
  2. Verify that you have set the Platform SDK build environment variables. For details about this procedure, see Installing Network Monitor Files.
  3. Type xcopy /e /s /v BLRPLATE MyMonitor; when prompted, type D.
  4. Navigate to the MyMonitor subdirectory.
  5. Type ren MyMon*.* MyMonitor*.*.
  6. Make certain that all of the files are properly renamed by comparing the files in the Monitors\Blrplate subdirectory.
  7. Open Makefile and then replace all occurrences of MyMon with MyMonitor.
  8. Open the MyMonitor.cpp file and then replace all occurrences of MyMon with MyMonitor.
  9. Open MyMonitor.h and then replace all occurrences of MyMon with MyMonitor.
  10. Type nmake.

The compiler should build the DLL file. To verify, change directories to \Obj and verify the file exists.

When the process is complete, you should have a basic monitor that you can modify to suit your network monitoring requirements. If you encounter problems during the monitor build process, see Debugging a Monitor. For information about how to install the completed monitor, see Installing a Monitor to Network Monitor.


Testing a Monitor

After a monitor is installed, you can test it with live data from your network operations, or you can test a known set of events by capturing the data with Network Monitor, saving the capture file, and then transmitting the data locally. (For details about how to transmit a capture file on a network, see Network Monitor online Help.)


Debugging a Monitor

To debug a monitor

  1. Install the monitor DLL and the program database (.pdb) file generated when you compiled the monitor in the correct location. See Installing a Monitor to Network Monitor for further details.
  2. Verify that the Monitor Control Service is configured as a server instead of a service by selecting Control Panel, Services.
  3. Open a command prompt and go to the Network Monitor directory. Type:
    Mcsvc.exe /RegServer

    After the monitor debugging session is complete, you can return the MCSVC to its default condition by typing:

    Mcsvc.exe /Service
  4. In Microsoft® Visual Studio®, launch Microsoft® Visual C++®.
  5. From the File, Open menu option, select the name of your monitor DLL.
  6. After Microsoft Visual C++ loads, click Project, Settings.
  7. Click the Debug tab under Executable for debug session and type the full path of Mcsvc.exe. For example:
    C:\Program files\Netmon2\Mcsvc.exe
  8. Set the breakpoints in the code.

Note Do not use a message box for monitor debugging. If the MCSVC is running as a service, you will not see the popup, and MCSVC will appear to hang.


Analyzing Network Traffic

With Network Monitor, monitors filter and capture network data; experts help you analyze the data that is captured. This section describes how to use Network Monitor experts. Topics include:

  • Configuring Experts
  • Starting and Running Experts
  • Programming an Expert


Configuring Experts

You can configure experts by using custom dialog boxes and the Configure function. When you write Network monitor experts, you have a choice. You can create a set of default configuration items that can be used when the expert initially runs, or you can allow Network Monitor users to configure the expert at run time. Configurations for each expert are stored by Network Monitor. As an option, users can reset the expert configuration back to original default settings. Note that you can bypass the use of Configure by developing an expert that passes a fixed configuration to Network Monitor.


Starting and Running Experts

Clicking Run Experts from the Experts window of the Network Monitor UI starts the experts selected for the capture file and calls the Run function. When started, the expert analyzes the capture file by using several expert frame functions.

The ExpertIndicateStatus function provides status information from the expert. When you run an expert with Network Monitor, the Expert Status View window displays periodically updated status information (from 0 to 100 percent completion).

The expert is active until the data completes its pass though the capture file. When the pass is complete, an Event Viewer window appears. The information in this window depends on the type of expert that analyzed the data. The following illustration shows a Property Distribution Expert view, which summarizes the frame data that the expert analyzed.

A second report (not shown), summarizes the results of the Transmission Control Protocol (TCP) Retransmit expert.

You can also:

  • Create an entry for an event reference page (ERP) that advises the user of detected conditions or problems (as shown in the Analysis window).
  • Create entries for suggested fixes or explanatory data that provide additional information (as shown in the Resolution window).

After the expert completes its task, Network Monitor removes the expert from active memory. Experts should use the protected memory functions included in the Platform SDK; these functions clean up memory if the experts fail during run time.


Programming an Expert

The Network Monitor SDK includes the functions and sample code you need to build experts. However, you can also use existing tools, including a dialog editor.

Minimum Requirements to Run an Expert

The following table lists the DLL entry points and expert functions you must use to build an expert.

Name | Type | Required?
DllMain | DLL entry function | Yes
Register Expert | DLL entry function | Yes
Run | DLL entry function | Yes
Configure | DLL entry function | Only if the expert provides user configuration.
ExpertIndicateStatus | Expert function | Yes
ExpertSubmitEvent | Expert function | Yes

Review the expert and parser reference topics in the Network Monitor SDK to update your source code and then use the sample code and procedures provided in these topics:

  • Building an Expert
  • Installing an Expert
  • Debugging an Expert

Expert DLLs require the C, not the C++, calling convention because functions are called through function pointers by using an overlay. Through a set of specialized expert functions, the expert has access to the frames in the capture. The expert can use most of the Network Monitor API to manipulate the returned data. When an expert finds information to send to the user, it packages the information in an event data structure and submits it to Network Monitor, which then displays the information in an expert output window. The expert must periodically update Network Monitor with percentage-completion status information, which is provided by the ExpertIndicateStatus function.

The expert's exported functions are called as follows:

  • When Network Monitor is creating the list of experts to present to the user, Network Monitor calls the Register Expert function.
  • After the call to Register, if the expert is configurable, Network Monitor calls the Configure function.
  • When the Network Monitor user clicks Run Experts, Network Monitor calls the Run function.

When experts analyze the requested frames and find a problem, they use ExpertSubmitEvent to submit an event that contains information about the problem. Network Monitor distributes the event to either the standard (shared) Event Viewer or (if the expert registers for it) to a private Event Viewer.


Using Microsoft Foundation Classes

Because of the footprint of statically linked DLLs, you should avoid using Microsoft Foundation Classes (MFCs) to write an expert. However, if you use the MFC, ensure access to any of the MFC DLL resources by including the following code immediately upon entry:

#ifdef _AFXDLL
      AFX_MANAGE_STATE(AfxGetStaticModuleState());
#endif


Managing Memory

Should your expert fail during run time, if you use Network Monitor functions for memory management, Network Monitor will free allocated memory. However, when you write an expert, it might be necessary to acquire system resources and data structure information. For example, the Network Monitor Protocol Coalesce Expert acquires a file handle to build a new capture. It is up to each expert to build its own try/catch handling so that the expert can free resources it acquired.

So, when you allocate memory, use these existing memory functions:

  • ExpertAllocMemory
  • ExpertReallocMemory


Building an Expert

This topic explains how to build a generic expert that ships with the Network Monitor SDK .

Note Before creating the following samples, you must install the Network Monitor SDK and initialize the MySetEnv.bat file. (For more details, see Network Monitor SDK Startup.)

To build a generic expert

  1. Open a Network Monitor command prompt and navigate to the \Experts subdirectory (C:\Program Files\NetMonSDK2\Experts, for example).
  2. Type xcopy /e /s /v Blrplate MyExpert; then, when prompted, type D.
  3. Move to the MyExpert subdirectory.
  4. Type ren Blrplate*.* MyExpert*.*. Make certain that all of the files are properly renamed. Verify the file names by comparing the files in the \Experts\Blrplate subdirectory.
  5. Edit Makefile by replacing all occurrences of Blrplate with MyExpert.
  6. Edit both .cpp files by replacing all occurrences of Blrplate with MyExpert. Note that the dialog box identifier in Config.cpp must be capitalized (for example, MYEXPERT).
  7. Edit MyExpert.h by replacing all occurrences of Blrplate with MyExpert.
  8. Edit Resrc1.h by renaming BLRPLATE to MYEXPERT. (Remember, MYEXPERT must be capitalized).
  9. Edit MyExpert.rc by renaming IDD_BLRPLATE_CONFIG_DIALOG to IDD_MYEXPERT_CONFIG_DIALOG.
  10. Type nmake to build the DLL file. To verify a good build, change directory to the \Obj subdirectory and verify that the file exists. See Viewing Expert DLL Properties to view the details.

When the build is complete, you will have an expert DLL that you can test and deploy with Network Monitor. For information about installing the expert, see Installing an Expert to Network Monitor 2.0. For information about debugging experts, see Debugging an Expert.


Installing an Expert to Network Monitor 2.0

Install an expert DLL by copying it to the Network Monitor\Experts subdirectory (for example, C:\Program Files\NetMon2\Experts). After installation, the expert will be recognized and available the next time Network Monitor starts.


Debugging an Expert

Use the following procedure to debug experts written in Microsoft® Visual C++®.

Debugging an Expert

  1. Install the expert (DLL file) and the program database file (.pdb) generated when you compiled the expert in the correct location. For further details, see Installing an Expert to Network Monitor 2.0.
  2. Start Microsoft® Visual C++®.
  3. From the File menu, click Open and select the name of your expert DLL.
  4. After Microsoft Visual C++ loads, click the Project menu and then click Settings.
  5. Click Debug. Under Executable for debug session, type the full path of Netmon.exe, for example:
    C:\Program files\Netmon2\Netmon.exe
  6. Set the breakpoints in your code.


Viewing Expert DLL Properties

Use the following procedure to view an expert's properties.

To view DLL properties

  1. Open Windows Explorer and go to the \Experts subdirectory of Network Monitor (C:\Program Files\NetMon2\Experts, for example).
  2. Select the desired DLL and right-click the file.
  3. Click Properties and Version. The following example shows the DLL properties.

  4. Click the desired Item name to display information in the Value pane.
  5. Click OK to close the Properties dialog box.


Writing a Protocol Parser

This topic contains information about writing a protocol parser, and includes examples of the export functions that the parser DLL must implement.

The following topics are included in this section.

  • Programming Considerations identifies the basic programming tips to help you write a parser DLL.
  • Implementing Parser Export Functions provides examples of implementing export functions.
  • Formatting Displayed Data identifies the process of formatting data that is displayed in the details pane of the Network Monitor UI.
  • Specifying a Follow Set identifies the process of specifying a follow set, and shows you how Network Monitor accesses the follow set of a parser to determine the next protocol.
  • Specifying a Handoff Set identifies the process of specifying a handoff set, and shows you how the parser accesses its handoff set to get a handle to the next protocol.


Programming Considerations

This topic contains programming information. The following list identifies some programming tips to help you write a parser.

Auto-installing your parser
Implement the ParserAutoInstallInfo function to automatically install your parser, and update the associated INI files. If you install your parser manually, you must update all associated INI files manually.
Parsing protocol properties
Implement the AttachProperties function to parse the protocol properties. Avoid using the AttachPropertyInstanceEx function when you attach a property instance, and use it for only non byte-aligned data, or data that must be decoded. Attaching properties refers to mapping a property instance to a specific location in a capture.
Parsing protocols that are split between frames
Assume that each piece of the protocol is complete within a frame, and assume that the user calls the Protocol Coalesce tool to combine the pieces into one protocol. Do not look back at a previous frame when parsing a protocol, and avoid trying to reconstruct a protocol that is split between frames.
Formatting displayed data
Call the FormatPropertyInstance function to use the generic formatter to format the data displayed in the details pane of the Network Monitor UI. Avoid writing a custom formatter for UI display data. However, you can call a custom formatter to create a summary property line for the protocol you are parsing.
Using CCAlloc
Use CCAlloc when you want Network Monitor to allocate data on a per-capture basis. Network Monitor does not specify the order that frames call the parser.
Keeping a parser stateless
Keep parser operation stateless because when Network Monitor parses a capture, it does not pass the frames to the parser in a specific order. For this reason, it is recommended that you do not retain global data.


Implementing Parser Export Functions

Platform SDK: Network Monitor

›Implementing Parser Export Functions

The parser export functions provide all the functionality of the parsers in the parser DLL. Each parser DLL must implement ParserAutoInstallInfo and DllMain. The remaining export functions must be implemented for each parser included in the parser DLL.

The following topics show you how to implement the export functions.

  • Implementing ParserAutoInstallInfo provides a description and code example of implementing the ParserAutoInstallInfo function, which identifies the parsers located in a parser DLL.
  • Implementing DllMain Parser provides a description and code example of implementing the DllMain Parser function, which identifies the existence of a parser, and then releases resources that Network Monitor uses for the parser.
  • Implementing Register provides a description and code example of implementing the Register function, which records all the properties of a protocol.
  • Implementing RecognizeFrame provides a description and code example of implementing the RecognizeFrame function, which identifies an instance of a protocol in a frame.
  • Implementing AttachProperties provides a description and code example of implementing the AttachProperties function, which separates the data that the parser recognizes, and then attaches property descriptions to each protocol property that exists in the recognized data.
  • Implementing FormatProperties provides a description and code example of implementing the FormatProperties function, which formats the data that is displayed in the details pane of the Network Monitor UI.
  • Implementing Deregister provides a description and code example of implementing the Deregister function, which releases the resources used to register protocol properties.


Implementing ParserAutoInstallInfo

Network Monitor uses the ParserAutoInstallInfo export function to install a parser. When ParserAutoInstallInfo is called, the parser returns a PF_PARSERDLLINFO structure containing all the information that Network Monitor needs to install a parser DLL.

Network Monitor keeps a list of existing parsers in the Parser.ini file, and creates a separate INI file for each installed parser.

During the installation process, the parser DLL must identify the following:

  • The number of parsers in the DLL — including a name and comment description for each parser.
  • The protocols that precede the parser protocol.
  • The protocols that follow the parser protocol.

Note Network Monitor uses the preceding and following parser protocol information to update the handoff sets and follow sets of parsers that your parser DLL identifies.

The following procedure identifies the steps necessary to implement ParserAutoInstallInfo.

To implement ParserAutoInstallInfo

  1. Allocate a PF_PARSERDLLINFO structure using HeapAlloc.

    Note that this call must also allocate a PF_PARSERINFO structure for each parser in the DLL.

  2. Specify the number of parsers (typically one) that the DLL contains in the nParsers member of PF_PARSERDLLINFO.
  3. Specify a name, comment, and optional Help file in the szProtocolName, szComment, and szHelpFile members of each PF_PROTOCOLINFO structure.
  4. Specify the protocols that precede each DLL protocol. The following conditions apply to an incoming handoff set.
    • If you know the protocols that precede a protocol, set the pWhoHandsOffToMe member of PF_PROTOCOLINFO. In this case, the protocols are added to the handoff sets of the protocols.

      – or –

    • If you do not know the protocols that precede a protocol, set pWhoCanPrecedeMe member of PF_PROTOCOLINFO. In this case, the protocols are added to the follow sets of the protocols.
  5. Specify the protocols that follow each DLL protocol. The following conditions apply to an outgoing follow-set.
    • If you know the protocols that follow a protocol, set the pWhoDoIHandOffTo member of PF_PROTOCOLINFO. In this case, the protocols are added to the handoff set of the protocols.

      – or –

    • If you do not know the protocols that follow a protocol, set pWhoCanFollowMe member of PF_PROTOCOLINFO. In this case, the protocols are added to the follow set of the protocols.
  6. Return the PF_PARSERDLLINFO structure to Network Monitor.

The following code example identifies a basic implementation of ParserAutoInstallInfo. The code example is taken from the generic parser that Network Monitor provides.

PPF_PARSERDLLINFO WINAPI ParserAutoInstallInfo()
{

  /////////////////////////////////////////////////////////////////
  //
  // Allocate memory for PF_PARSERDLLINFO structure.
  //
  /////////////////////////////////////////////////////////////////
  PPF_PARSERDLLINFO pParserDllInfo;
  PPF_PARSERINFO    pParserInfo;
  DWORD NumProtocols;
  NumParsers = 1;

  pParserDllInfo = (PPF_PARSERDLLINFO)HeapAlloc( GetProcessHeap(),
                                                 HEAP_ZERO_MEMORY,
                                                 sizeof( PF_PARSERDLLINFO ) +
                                                 NumParsers * sizeof( PF_PARSERINFO) );
  if( pParserDllInfo == NULL)
  {
    return NULL;
  }

  /////////////////////////////////////////////////////////////////
  //
  // Specify the number of parsers in the DLL.
  //
  /////////////////////////////////////////////////////////////////

  pParserDllInfo->nParsers = NumParsers;

  /////////////////////////////////////////////////////////////////
  //
  // Specify the name, comment, and Help file for each protocol.
  //
  /////////////////////////////////////////////////////////////////
  pParserInfo = &(pParserDllInfo->ParserInfo[0]);
  wsprintf( pParserInfo->szProtocolName, "TestProtocol" );
  wsprintf( pParserInfo->szComment,      "Test protocol for SDK" );
  wsprintf( pParserInfo->szHelpFile,     "");

  /////////////////////////////////////////////////////////////////
  //
  // Specify preceding protocols.
  //
  /////////////////////////////////////////////////////////////////
  PPF_HANDOFFSET    pHandoffSet;
  PPF_HANDOFFENTRY  pHandoffEntry;

  // Allocate PF_HANDOFFSET structure.
  NumHandoffs = 1;
  pHandoffSet = (PPF_HANDOFFSET)HeapAlloc( GetProcessHeap(),
                                           HEAP_ZERO_MEMORY,
                                           sizeof( PF_HANDOFFSET ) +
                                           NumHandoffs * sizeof( PF_HANDOFFENTRY) );
  if( pHandoffSet == NULL )
  {
     return pParserDllInfo;
  }

  // Fill in handoff set
  pParserInfo->pWhoHandsOffToMe = pHandoffSet;
  pHandoffSet->nEntries = NumHandoffs;

  // TCP PORT FFFF
  pHandoffEntry = &(pHandoffSet->Entry[0]);
  wsprintf( pHandoffEntry->szIniFile,    "TCPIP.INI" );
  wsprintf( pHandoffEntry->szIniSection, "TCP_HandoffSet" );
  wsprintf( pHandoffEntry->szProtocol,   "BLRPLATE" );
  pHandoffEntry->dwHandOffValue =        0xFFFF;
  pHandoffEntry->ValueFormatBase =       HANDOFF_VALUE_FORMAT_BASE_DECIMAL;

  /////////////////////////////////////////////////////////////////
  //
  // Specify the following protocols.
  //
  /////////////////////////////////////////////////////////////////
  PPF_FOLLOWSET     pFollowSet;
  PPF_FOLLOWENTRY   pFollowEntry;

  // Allocate PF_FOLLOWSET structure
  NumFollows = 1;
  pFollowSet = (PPF_FOLLOWSET)HeapAlloc( GetProcessHeap(),
                                         HEAP_ZERO_MEMORY,
                                         sizeof( PF_FOLLOWSET ) +
                                         NumFollows * sizeof( PF_FOLLOWENTRY) );
  if( pFollowSet == NULL )
  {
    return pParserDllInfo;
  }

  // Fill in the follow set
  pParserInfo->pWhoCanFollowMe = pFollowSet;
  pFollowSet->nEntries = NumFollows;

  // Add SMB
  pFollowEntry = &(pFollowSet->Entry[0]);
  wsprintf( pFollowEntry->szProtocol,   "SMB" );

  /////////////////////////////////////////////////////////////////
  //
  // Return the PF_PARSERDLLINFO structure.
  //
  /////////////////////////////////////////////////////////////////
  return pParserDllInfo;

}


Implementing DllMain Parser

Network Monitor uses the DllMain export function to identify the existence of the parser, and release resources that Network Monitor uses to store information about the parser.

When Network Monitor calls DllMain for the first time, the parser DLL calls CreateProtocol to do the following:

  • Specify the protocol that the parser detects.
  • Provide entry points for remaining parser export functions that Network Monitor calls.

When Network Monitor calls DllMain for the last time, DllMain calls DestroyProtocol to release all resources that Network Monitor uses to store information about the parser.

The following procedure identifies the steps necessary to implement DllMain.

To implement DllMain

  1. Specify the ENTRYPOINTS structure for the CreateProtocol function and global Attach variable. The Attach variable is used to track the number of protocol instances that are running.
  2. Look at the value of the Command parameter that the operating system sets.

    If the Command parameter is set to DLL_PROCESS_ATTACH and Attach is 0, then call CreateProtocol to provide the protocol name and entry points for the following export functions.

    • Register
    • Deregister
    • RecognizeFrame
    • AttachProperties
    • FormatProperties (only required if Network Monitor will be displaying the protocol properties).

    If the Command parameter is set to DLL_PROCESS_DETACH and Attach is 0, then call DestroyProtocol using the instance handle that CreateProtocol returns.

  3. Return TRUE because the DllMain parser function must always return TRUE.

The following code example identifies a basic implementation of DllMain. The code example uses a case statement to trap values of the Command parameter to determine if CreateProtocol or DestroyProtocol should be called.

// Entry point structure for parser export functions and global
// Attach variable.
ENTRYPOINTS EntryPoints =
{
  Register,
  Deregister,
  RecognizeFrame,
  AttachProperties,
  FormatProperties
};

DWORD Attached = 0;

BOOL WINAPI DllMain(HANDLE hInstance, ULONG Command, LPVOID Reserved)
{
  switch(Command)
  {
  // Call CreateProtocol.
  case DLL_PROCESS_ATTACH:
       // Loading parser DLL.
       if(Attached == 0)
       {
         hProtocol = CreateProtocol( "ProtocolName",
                                     &EntryPoints,
                                     ENTRYPOINTS_SIZE);
       }
       Attached++;
       break;
  // Call DestroyProtocol.
  case DLL_PROCESS_DETACH:
       // Unloading parser DLL.
       Attached--;
       if(Attached == 0)
       {
         DestroyProtocol( hProtocol);
       }
       break;
  }
  return TRUE;
}


Implementing Register

Network Monitor loads a capture from the capture file, and then starts calling the Register function for all the protocols that it can identify. Each parser DLL must implement a Register function for each protocol that the parser DLL supports.

Each implementation of the Register function must call the CreatePropertyDatabase and AddProperty functions to create and fill-in the property database for the protocol, and then the CreateHandoffTable to create the handoff table for the protocol — if needed.

Note Protocol properties are defined for Network Monitor. Properties are not mapped to a location in a capture data until the AttachProperties export function is called.

The following procedure identifies the steps necessary to implement the Register function.

To implement Register for one protocol

  1. Define an array of PROPERTYINFO structures to describe each property that the protocol supports.
  2. Call CreatePropertyDatabase to provide a protocol handle, and the number of properties that the protocol supports.
  3. Call AddProperty in a loop to add each property defined in the PROPERTYINFO structure array.
  4. If the protocol uses a handoff table, call CreateHandoffTable — after all the properties of the protocol are added to the property database.

The following code example identifies a basic implementation of Register. Note that a property database is created for a protocol that supports only two properties. This code example is taken from the generic parser that Network Monitor provides.

PROPERTYINFO MyProtocolPropertyTable[];
{
  // Summary property (0)
  {
     0,                               // Handle to property.
     0,                               // Reserved.
     "Summary",                       // Property label.
     "Summary of protocol packet",    // Property comment.
     PROP_TYPE_SUMMARY,               // Data type of property.
     PROP_QUAL_NONE,                  // Data type qualifier.
     NULL,                            // Reserved.
     80,                              //
     FormatPropertyInstance           //
  }

  // WORD property (1)
  {
     0,                               // Handle to property.
     0,                               // Reserved.
     "WORD property",                 // Property label.
     "16-bit WORD property",         // Property comment.
     PROP_TYPE_WORD,                  // Data type of property.
     PROP_QUAL_NONE,                  // Data type qualifier.
     NULL,                            // Reserved.
     80,                              //
     FormatPropertyInstance           //
  }

}

void BHAPI MyProtocolRegister( HPPROTOCOL hProtocol)
{
  // Create property database.
  DWORD dwNumberOfProperties = 2;
  CreatePropertyDatabase (hProtocol,
                          dwNumberOfProperties
                          );

  // Add properties to database.
  WORD i;
  for( i=0; i< dwNumberOfProperties; i++)
  {
     AddProperty(hProtocol, &MyProtocolPropertyTable[i]);
  }

  // Create handoff table.
  CreateHandoffTable("myProtocolHandoffTable",
                          "myProtocol.ini",
                           hTable,
                           MaxEntries,
                           10       // Handoff set values are base 10.
                          )
}


Implementing RecognizeFrame

Network Monitors calls the RecognizeFrame function of a parser to determine that the parser recognizes the unclaimed data of a frame. The unclaimed data may be at the start of a frame, but typically, unclaimed data is located in the middle of a frame. The following graphic shows unclaimed data located in the middle of a frame.

Network Monitor provides the following information when it calls the RecognizeFrame function.

  • A handle to the frame.
  • A pointer to the start of the frame.
  • A pointer to the start of the unclaimed data.
  • The MAC value of the first protocol in the frame.
  • The number of bytes in the unclaimed data (that is, the number of bytes that remain in the frame).
  • A handle to the previous protocol.
  • The offset of the previous protocol.

When the parser DLL determines that unclaimed data starts with the parser protocol, the parser DLL determines where the next protocol starts, and which protocol follows. The parser DLL functions in the following conditional ways.

  • If the parser DLL recognizes unclaimed data, the parser DLL sets the pProtocolStatus parameter, and returns a pointer to either the next protocol in the frame, or NULL. NULL is returned if the current protocol is the last protocol in the frame.
  • If the parser DLL recognizes unclaimed data and identifies the protocol that follows (from information provided in the protocol), then the parser DLL returns a pointer to the handle of the next protocol in the phNextProtocol parameter of the function.
  • If the parser DLL does not recognize unclaimed data, the parser DLL returns the pointer to the start of unclaimed data, and Network Monitor continues trying to parse the unclaimed data.

To implement RecognizeFrame

  1. Test to determine that you recognize the protocol.
  2. If you recognize unclaimed data and you know which protocol follows, set pProtocolStatus to PROTOCOL_STATUS_NEXT_PROTOCOL, set phNextProtocol to a pointer that points to the handle for the next protocol, and then return a pointer to the next protocol.

    –or–

    If you recognize unclaimed data and you do not know which protocol follows, set pProtocolStatus to PROTOCOL_STATUS_RECOGNIZED, and then return a pointer to the next protocol.

    –or–

    If you recognize unclaimed data and your protocol is the last protocol in a frame, set pProtocolStatus to PROTOCOL_STATUS_CLAIMED, and then return NULL.

    –or–

    If you do not recognize unclaimed data, set pProtocolStatus to PROTOCOL_STATUS_NOT_RECOGNIZED, and then return the pointer that is passed to you in pProtocol.

The following code example identifies a basic implementation of RecognizeFrame.

LPBYTE BHAPI MyProtocol_RecognizeFrame( HRAME     hFrame,
                                        LPBYTE    pMacFrame,
                                        LPBYTE    pProtocol,
                                        DWORD     MacType,
                                        DWORD     BytesLeft,
                                        HPROTOCL  hPrevProtocol,
                                        DWORD     nPreviuosProtOffset,
                                        LPDWORD   pProtocolStatus,
                                        LPDWORD   phNextProtocol,
                                        LPDWORD   InstData)

  // Test unclaimed data.

  // If unclaimed data is recognized but you do not know what follows.
  *ProtocolStatus =  PROTOCOL_STATUS_RECOGNIZED;
  return pProtocol + MY_PROTOCOL_LENGTH

  // If unclaimed data is recognized and you know what follows.
     *ProtocolStatus =  PROTOCOL_STATUS_NEXT_PROTOCOL;
     phNextProtocol = GetProtocolFromTable(
                                           hTable,
                                           ItemToFind,
                                           lpInstData);
  return  pProtocol + MY_PROTOCOL_LENGTH

  // If unclaimed data is recognized and the protocol is the last
  // protocol in the frame.
  *ProtocolStatus =  PROTOCOL_STATUS_CLAIMED;
  return NULL;

  // If the unclaimed data is not recognized.
  *ProtocolStatus =  PROTOCOL_STATUS_NOT_RECOGNIZED;
  return *pProtocol;

}


Implementing AttachProperties

Network Monitor calls the AttachProperties function to map the properties that exist in a piece of recognized data. The AttachProperties function maps the properties to a specific location.

Network Monitor uses the following process to parse the data in a frame.
  • First, Network Monitor calls RecognizeFrame to recognize all the protocols that exist in a frame.
  • Then, Network Monitor calls AttachProperties for each parser that recognizes a piece of data.

When Network Monitor calls the AttachProperties function for the recognized data, the parser that is called must parse the data, and then map each existing property to a location in the recognized data. The parser determines which properties exist, and where each property is located in the data. The following illustration shows a piece of data that a parser recognizes.

During the implementation of AttachProperties, you must call one of the following functions for each property that exists in a data frame.

  • Call the AttachPropertyInstanceEx function when you want to modify the property data in a frame.
  • Call the AttachPropertyInstance function when you do not want to modify the property data in a frame.

Note It is recommended that you use the data as it exists in the capture.

The following procedure identifies the steps necessary to implement AttachProperties.

To implement AttachProperties

  1. Determine which properties exist, and the property location in the data.
  2. Call AttachPropertyInstanceEx for each property with a value that you want to modify.
  3. Call AttachPropertyInstance for each property with a value that you do not want to modify. Typically, this is the only function that you need to call.

The following code example identifies a basic implementation of AttachProperties. Note that the example does not include either the code to determine which properties exist, or the code to locate the properties.

LPBYTE BHAPI MyProtocolAttachProperties( HFRAME   hFrame,
                                         LPBYTE   pMacFrame,
                                         LPBYTE   pBLRPLATEFrame,
                                         DWORD    MacType,
                                         DWORD    Bytesleft,
                                         HPROTOCOL  hPreviousProtocol,
                                         DWORD    nPrevProtocolOffset,
                                         DWORD    InstData)
{
  PBLRPLATEHDR pBLRPLATEHdr = (PBLRPLATEHDR)pBLRPLATEFrame

  // Attach summary property.
  AttachPropertyInstance( hFrame,
                          BLRPLATEPropertyTable[BLRPLATE_SUMMARY].hProperty,
                          (WORD)BytesLeft,
                          (LPBYTE)pBLRPLATEFrame,
                          0,        // No Help file.
                          0,        // Indent level.
                          0);      // Data flag.

  // Attach signature property.
  AttachPropertyInstance( hFrame,
                          BLRPLATEPropertyTable[BLRPLATE_SIGNATURE].hProperty,
                          sizeof(DWORD),
                          &(pBLRPLATEHdr->Signature),
                          0,        // No Help file.
                          1,        // Indent level.
                          0);        // Data flag.

  // Attach opcode.
  AttachPropertyInstance( hFrame,
                          BLRPLATEPropertyTable[BLRPLATE_OPCODE].hProperty,
                          sizeof(WORD),
                          &(pBLRPLATEHdr->Opcode),
                          0,        // No Help file.
                          1,        // Indent level.
                          0);        // Data flag.

  // Attach flags summary.
  AttachPropertyInstance( hFrame,
                          BLRPLATEPropertyTable[BLRPLATE_FLAGS_SUMMARY].hProperty,
                          sizeof(BYTE),
                          &(pBLRPLATEHdr->Flags),
                          0,        // No Help file.
                          1,        // Indent level.
                          0);       // Data flag.

// Attach flags decode.
  AttachPropertyInstance( hFrame,
                          BLRPLATEPropertyTable[BLRPLATE_FLAGS_FLAGS].hProperty,
                          sizeof(BYTE),
                          &(pBLRPLATEHdr->Flags),
                          0,        // No Help file.
                          2,        // Indent level.
                          0);       // Data flag.

  RETURN null;

}


Implementing FormatProperties

Network Monitor calls the FormatProperties function to format the data that is displayed in the details pane of the Network Monitor UI. Typically, FormatProperties is called to format the summary line for a protocol, and then to format all the property instances of the protocol within a frame. However, Network Monitor does not identify the number of times that FormatProperties is called for a specific parser.

When calling FormatProperties, Network Monitor provides a PROPERTYINST structure for each property that it displays. The PROPERTYINST structure provides information about the data to be displayed, including a pointer to the PROPERTYINFO structure that specifies the function to use for formatting the displayed data property.

Note A PROPERTYINFO structure is specified when adding a property to the property database of the parser.

Network Monitor identifies the format function to call for each property instance. The InstanceData member of the PROPERTYINFO structure can specify the following:

  • The FormatPropertyInstance function to use the generic formatter that Network Monitor provides.

    – or –

  • The name of a custom format function that the parser provides.

The FormatPropertyInstance and the custom format functions return the formatted data that is displayed in the details pane of the Network Monitor UI.

The following illustration shows how Network Monitor identifies the function to call for each property instance.

The following procedure identifies the steps necessary to implement FormatProperties.

To implement FormatProperties

  • Using a loop structure, call the format function for each PROPERTYINST structure that is passed to the parser in the lpPropInst parameter of the FormatProperties function.

The following code example identifies a basic implementation of FormatProperties.

DWORD BHAPI MyProtocolFormatProperties( HFRAME         hFrame,
                                        LPBYTE         pMacFrame,
                                        LPBYTE         pBLRPLATEFrame,
                                        DWORD          nPropertyInsts
                                        LPPROPRTYINST  p)
  {
    while( nProprtyInsts-- > 0)
      {
         ( (FORMAT) p->lpPropertyInfo->InstacnceData) ) (p);
         p++;
      }
  return NMERR_SUCCESS;
  }


Implementing Deregister

Network Monitor passes all the frames of a capture to the parsers, and then starts calling the Deregister function for all the protocols it identifies. Each parser DLL must implement a Deregister function for each protocol that the parser DLL supports.

Each implementation of the Deregister function must call the DestroyProtocolDatabase function to release the resources that are used to create the database.

The following procedure identifies the one step necessary to implement Deregister.

To implement Deregister for one protocol

  • Call DestroyPropertyDatabase to release the database resources.

The following code example identifies a basic implementation of Deregister. Note that the code example shows the release of resources that are used to create a property database.

VOID WINAPI MyProtocolDeregister (HPROTOCOL hProtocol)
{
  DestroyProtocolDatabase (hPtotocol);
}


Specifying a Handoff Set

A handoff set specifies the protocols that follow a protocol. The parser uses a handoff set only when the parser can identify the next protocol from the data in a protocol instance.

For example, the TCP protocol has a port property that identifies the protocol that follows the TCP protocol. A property value of 20 indicates that the next protocol is FTP. A property value of 53 indicates that the next protocol is DNS. Because the port property identifies the protocol that follows, the TCP parser can use the following handoff set to get a handle for the protocol that the port property specifies.

[TCP_HandoffSet]
  20    = FTP
  21    = FTP
  23    = TELNET
  25    = SMPT
  53    = DNS
  79    = FINGER
  80    = HTTP
  102   = ISO
  111   = RPC
  119   = NNTP
  137   = NBT, 1000
  138   = NBT, 1002
  139   = NBT, 1001
  389   = LDAP
  445   = NBT, 1001
  515   = LPR
  612   = HMMP
  613   = HMMP
  1024  = NBT, 1001
  1047  = NBT, 1001
  1362  = TDS
  1433  = TDS
  1723  = PPTP
  3020  = NBT, 1001
  3268  = LDAP
  5678  = PPTP

Handoff sets are stored in the parser INI file. For example, the preceding TCP handoff set is located in tcpip.ini file. Note that if a parser DLL supports multiple protocols, each parser that uses a handoff set has its own location in the INI file.

Handoff set information is specified during the implementation of the ParserAutoInstallInfo function. The parser can specify the protocols that precede the parser protocol, and the protocols that follow the parser protocol. Network Monitor takes all the protocols that precede, and adds the parser protocol to the follow set sections of the parser INI file — for each preceding protocol. Network Monitor stores the list of protocols that follow in the handoff set section of the parser INI file.

Network Monitor stores the handoff set information in the parser INI file, but the parser does not access the INI files directly. To use the information in the handoff set, the parser calls the CreateHandoffTable function to create a handoff table. Typically, the handoff table is created when the parser registers the protocol. After the protocol is registered, Network Monitor creates a handoff set table that the parser can use.

The parser uses its handoff set when recognizing data. First the parser reads the value of the property that identifies the next protocol. Then the parser calls the GetProtocolFromTable to get a handle to the next protocol. Last, the parser returns a pointer to the handle in the phNextProtocol parameter of RecognizeFrame.


Specifying a Follow Set

A follow set specifies the protocols that follow a protocol. Network Monitor uses a follow set when the parser cannot identify the next protocol from the data in a protocol instance.

For example, the NetBIOS parser specifies a follow set because the data in the NetBIOS protocol does not identify which protocol is next. As a result the NetBIOS parser must create a follow set of all the protocols that may follow.

The following code example identifies the NetBIOS follow set in the Parser.ini file. The follow set contains server message block (SMB), and Microsoft® remote procedure call (MSRPC) protocols. These are the only protocols that can follow an instance of the NetBIOS protocol.

[NETBIOS]
   Comment    = "Network Basic Input/Output System protocol"
   FollowSet  = SMB, MSRPC
   HelpFile   =

A parser specifies a follow set during the implementation of the ParserAutoInstallInfo function. A parser can specify which protocols precede, and which protocols follow. When a parser specifies the protocols that precede, Network Monitor adds the parser protocol to the follow sets of the specified protocols. When a parser specifies the protocols that follow, Network Monitor creates a new section in the Parser.ini file that includes the follow set of the parser.


Formatting Displayed Data

Network Monitor or your parser DLL can format the data that is displayed in the details pane of the Network Monitor UI.

Network Monitor provides a generic formatter that provides the basic services needed to display most data types that exist within a protocol. However, the generic formatter does not support all data types. For example, the generic formatter does not support the following:

  • Several address types.
  • Source and destination-friendly names.
  • Object identifiers.
  • Large integer data types.
  • Variable length small integer data types.

The following example identifies two formatted strings for the Privilege ID property.

  • The first line of code shows the output of the generic formatter. The output is based on the data type.
  • The second line of code shows the output of a custom formatter with a string to the property data.
Privilege ID (PID) = 0x0029
Privilege ID   (PID) = 0x0029   The Process has privileges

Note When possible, use the generic formatter to display your data because it allows you to control the size of your parser DLL, and provides better cross-platform capabilities for your parser DLL.


Generic Formatter Output

The lists and tables in this section show the output of the generic formatter. Note that the generic formatter uses the DataType and DataQualifier members of the PROPERTYINFO structure to determine how to format the displayed data.

To view an example of the output for a specific property data type, click on a data type in the following list.

  • PROP_TYPE_VOID
  • PROP_TYPE_SUMMARY
  • PROP_TYPE_BYTE
  • PROP_TYPE_WORD
  • PROP_TYPE_DWORD
  • PROP_TYPE_LARGEINT (generic formatter does not support)
  • PROP_TYPE_ADDR (generic formatter does not support)
  • PROP_TYPE_TIME
  • PROP_TYPE_STRING
  • PROP_TYPE_IP_ADDRESS
  • PROP_TYPE_BYTESWAPPED_WORD (Obsolete, see PROP_TYPE_WORD)
  • PROP_TYPE_BYTESWAPPED_DWORD (Obsolete, see PROP_TYPE_DWORD)
  • PROP_TYPE_TYPED_STRING (Obsolete)
  • PROP_TYPE_RAW_DATA
  • PROP_TYPE_COMMENT
  • PROP_TYPE_SRCFRIENDLYNAME (generic formatter does not support)
  • PROP_TYPE_DSTFRIENDLYNAME (generic formatter does not support)
  • PROP_TYPE_TOKENRING_ADDRESS (generic formatter does not support)
  • PROP_TYPE_FDDI_ADDRESS (generic formatter does not support)
  • PROP_TYPE_ETHERNET_ADDRESS (generic formatter does not support)
  • PROP_TYPE_OBJECT_IDENTIFIER (generic formatter does not support)
  • PROP_TYPE_VINES_IP_ADDRESS (generic formatter does not support)
  • PROP_TYPE_VAR_LEN_SMALL_INT (generic formatter does not support)

PROP_TYPE_VOID and PROP_TYPE_COMMENT

The table in this section shows the generic format output for PROP_TYPE_VOID and PROP_TYPE_COMMENT data type properties.

In the formatter output column, the value of the data in the capture is XYZ.

Property qualifier | Formatter output
PROP_QUAL_NONE | XYZ
PROP_QUAL_RANGE | XYZ
PROP_QUAL_BITFIELD | Obsolete
PROP_QUAL_LABELED_SET | XYZ
PROP_QUAL_LABELED_BITFIELD | Obsolete, see PROP_QUAL_FLAGS
PROP_QUAL_CONST | XYZ
PROP_QUAL_FLAGS | XYZ
PROP_QUAL_ARRAY | XYZ

PROP_TYPE_SUMMARY

The table in this section shows the generic format output for PROP_TYPE_SUMMARY data type properties.

In the example output column, the value of the data in the capture is XYZ.

Property qualifier | Example output
PROP_QUAL_NONE | XYZ
PROP_QUAL_RANGE | XYZ
PROP_QUAL_BITFIELD | Obsolete
PROP_QUAL_LABELED_SET | XYZ
PROP_QUAL_LABELED_BITFIELD | Obsolete, see PROP_QUAL_FLAGS
PROP_QUAL_CONST | XYZ
PROP_QUAL_FLAGS | XYZ
PROP_QUAL_ARRAY | XYZ

PROP_TYPE_BYTE

The table in this section shows the generic format output for PROP_TYPE_BYTE data type properties.

In the example output column, the value of the data in the capture is 10.
Property qualifier | Example output
PROP_QUAL_NONE | 10 (0xa)"
PROP_QUAL_RANGE | 10 (0xa) Range:(1 (0x1) - 20 (0x14))
PROP_QUAL_SET 10 (0xa) Matches Set Value

or

10 (0xa) Unknown Set Value
PROP_QUAL_BITFIELD | Obsolete.
PROP_QUAL_LABELED_SET | Corresponding label in a label set or number.
PROP_QUAL_LABELED_BITFIELD | Obsolete. See PROP_QUAL_FLAGS.
PROP_QUAL_CONST | No output. No data is displayed in the detail pane.
PROP_QUAL_FLAGS .......0 = Label Off String
......1. = Label On String
.....0.. = Label Off String
....1... = Label On String
PROP_QUAL_ARRAY | 0a ff ...

PROP_TYPE_WORD

The table in this section shows the generic format output for a PROP_TYPE_WORD data type property.

Note For non-Intel, byte-swapped DWORD properties, you must change the data to an Intel format. To change the format, set the IFlags parameter of the Attach property instance function IFLAG_SWAPPED when you map the property instance to a location

In the example output column, the value of the data in the capture is 10.

Property qualifier | Example output
PROP_QUAL_NONE | 10 (0xa)
PROP_QUAL_RANGE | 10 (0xa) Range:(1 (0x1) - 20 (0x14))
PROP_QUAL_SET 10 (0xa) Matches Set Value

or

10 (0xa) Unknown Set Value
PROP_QUAL_BITFIELD | Obsolete.
PROP_QUAL_LABELED_SET | Corresponding label in the label set or number.
PROP_QUAL_LABELED_BITFIELD | Obsolete. See PROP_QUAL_FLAGS.
PROP_QUAL_CONST | No output. No data is displayed in the detail pane.
PROP_QUAL_FLAGS .......0 = Label Off String
......0. = Label Off String
.....0.. = Label Off String
....0... = Label Off String
...0.... = Label Off String
..1..... = Label On String
.0...... = Label Off String
1....... = Label On String
PROP_QUAL_ARRAY | 000a ffff ...

PROP_TYPE_DWORD

The table in this section shows the generic format output for PROP_TYPE_DWORD data type properties.

Note For non-Intel, byte-swapped DWORD properties, you must change the data to an Intel format. To change the format, set the IFlags parameter of the Attach property instance function IFLAG_SWAPPED when you map the property instance to a location

In the example output column, the value of the data in the capture is 10.

Property qualifier | Example output
PROP_QUAL_NONE | 10 (0xa)
PROP_QUAL_RANGE | 10 (0xa) Range:(1 (0x1) - 20 (0x14))
PROP_QUAL_SET 10 (0xa) Matches Set Value

or

10 (0xa) Unknown Set Value
PROP_QUAL_BITFIELD | Obsolete.
PROP_QUAL_LABELED_SET | Corresponding label in label set or number.
PROP_QUAL_LABELED_BITFIELD | Obsolete. See PROP_QUAL_FLAGS.
PROP_QUAL_CONST | No output. No data is displayed in the detail pane.
PROP_QUAL_FLAGS ...............0 = Label Off String
..............0. = Label Off String
.............0.. = Label Off String
............0... = Label Off String
...........0.... = Label Off String
..........0..... = Label Off String
.........0...... = Label Off String
........0....... = Label Off String
.......0........ = Label Off String
......0......... = Label Off String
.....0.......... = Label Off String
....0........... = Label Off String
...0............ = Label Off String
..1............. = Label On String
.0.............. = Label Off String
1............... = Label On String
PROP_QUAL_ARRAY | 0000000a ffffffff ...

PROP_TYPE_RAW_DATA

The table in this section shows the generic format output for a PROP_TYPE_RAW_DATA data type property. Note that the formatter output does not display the raw data, but does display the property label.

Property qualifier | Formatter output
PROP_QUAL_NONE | Property label.
PROP_QUAL_RANGE | Property label.
PROP_QUAL_BITFIELD | Property label.
PROP_QUAL_LABELED_SET | Property label.
PROP_QUAL_LABELED_BITFIELD | Property label.
PROP_QUAL_CONST | Property label.
PROP_QUAL_FLAGS | Property label.
PROP_QUAL_ARRAY | Property label.

PROP_TYPE_TIME

The table in this section shows the generic format output for a PROP_TYPE_TIME data type property. Note that the formatted output may vary depending on the data qualifier of the property.

The generic formatter calls GetDateFormat to get a time that is based on the system clock of the local computer.

Property qualifier | Formatter output
PROP_QUAL_NONE | Displays the system time based on the local computer clock.
PROP_QUAL_RANGE | Displays the system time based on the local computer clock.
PROP_QUAL_BITFIELD | Obsolete.
PROP_QUAL_LABELED_SET | Displays the system time based on the local computer clock.
PROP_QUAL_LABELED_BITFIELD | Obsolete. See PROP_QUAL_FLAGS.
PROP_QUAL_CONST | Displays the system time based on the local computer clock.
PROP_QUAL_FLAGS | Displays the system time based on the local computer clock.
PROP_QUAL_ARRAY | Displays the system time based on the local computer clock.

PROP_TYPE_STRING

The table in this section shows the generic format output for PROP_TYPE_STRING data type properties. Note that the formatter output may vary depending on the data qualifier of the property.

Property qualifier | Formatter output
PROP_QUAL_NONE | Attached string.
PROP_QUAL_RANGE | Attached string.
PROP_QUAL_BITFIELD | Obsolete.
PROP_QUAL_LABELED_SET | Attached string.
PROP_QUAL_LABELED_BITFIELD | Obsolete. See PROP_QUAL_FLAGS.
PROP_QUAL_CONST | Attached string.
PROP_QUAL_FLAGS | Attached string.
PROP_QUAL_ARRAY | Attached string.

PROP_TYPE_IP_ADDRESS

The table in this section shows the generic format output for PROP_TYPE_IP_ADDRESS data type properties. Note that the formatted output may vary depending on the property data qualifier of the property.

In the example output column, the value of the data in the capture is "129.65.100.2".

Property qualifier | Example output
PROP_QUAL_NONE | 129.65.100.2
PROP_QUAL_RANGE | 129.65.100.2
PROP_QUAL_BITFIELD | Obsolete.
PROP_QUAL_LABELED_SET | 129.65.100.2
PROP_QUAL_LABELED_BITFIELD | Obsolete. See PROP_QUAL_FLAGS.
PROP_QUAL_CONST | 129.65.100.2
PROP_QUAL_FLAGS | 129.65.100.2
PROP_QUAL_ARRAY | 129.65.100.2


Viewing Parsed Information

The Network Monitor frame viewer displays parsed data in three panes. The upper pane displays a summary of the frame that includes the identified protocol. The middle pane displays the formatted data properties that can be organized hierarchically as part of the parser display. The lower pane displays highlighted raw data that is selected from the middle pane.

You can specify how the information in the viewer is displayed when you develop your own parser. The following illustration shows how information can be displayed in the Network Monitor frame viewer.

Note Parsers do not display frames. Parsers recognize fields in the information provided, and then notify Network Monitor to display the frame. Filtering is a higher level operation that allows filter queries to span parsers.

In your parser, use only functions that can run on Microsoft® Win32® applications. Before attaching properties to the raw data, a parser must first register all possible properties with the Network Monitor kernel. The parser sends a message to the kernel to create a property database, and then fills the property database with every possible property for its protocol. Each property in the property database contains information such as a textual description, a data type and qualifier that are used to format the raw data, and a formatting routine that is used to display the data.


Providing Network Statistics and Packet Information

The Network Packet Provider (NPP) is a DLL that communicates with the Network Monitor driver and provides network statistics and packet information. The most common ways to use the NPP are as a source of:

  • Network statistics.
  • Frames that are handed up to the application in real time.
  • Packets accessible only after the capture has been stopped.

This section includes the following topics:

  • Selecting a NIC
  • Using GetNPPBlobTable


Selecting a NIC Using GetNPPBlobFromUI

With Network Monitor, selecting a NIC programmatically is a two-step process. First, create the filter BLOB by calling the CreateBlob method. Then, select the NIC by calling the GetNPPBlobFromUI method.

In this example a filter BLOB is used to select the NIC that is needed:

DWORD rc;

// Call CreateBlob to create a filter blob.
///////////////////////////////////////////
HBLOB hFilterBlob;
rc = CreateBlob(&hFilterBlob);
if (FAILED (rc));
{
  // Failed creating filter BLOB. Add appropriate error handling.
}

// Call GetNPPBlobFromUI to retrieve the NPP Blob.
//////////////////////////////////////////////////
rc = GetNPPBlobFromUI(hwnd,
                      hFilterBlob,
                      &hBlob);
if (FAILED (rc));
{
  // Failed retrieving NPP BLOB. Add appropriate error handling.
}


Using GetNPPBlobTable

DWORD rc;
PBLOB_TABLE pBlobTable;
// Create the filter blob
HBLOB hFilterBlob;
if (NMERR_SUCCESS != (rc = CreateBlob(&hFilterBlob)))
    return FALSE;

// Set test criteria
// To obtain delayed capture interface
if (NMERR_SUCCESS != (rc = SetBoolInBlob (
                      hFilterBlob,
                                 OWNER_NPP,
                                 CATEGORY_CONFIG,
                            TAG_INTERFACE_DELAYED_CAPTURE,
                                 TRUE)))
    return FALSE;

// Only obtain Ethernet cards
if (NMERR_SUCCESS != (rc = SetStringInBlob(hBlob,
                               OWNER_NPP,
                              CATEGORY_NETWORKINFO,
                                 TAG_MACTYPE,
                                 PROTOCOL_STRING_ETHERNET_TXT)))
    return FALSE;

// To get SpecialBlobs back
if (NMERR_SUCCESS != (rc = SetBoolInBlob(hBlob,
                               OWNER_NPP,
                              CATEGORY_FINDER,
TAG_GET_SPECIAL_BLOBS,
                                 TRUE)))
    return FALSE;

// Make the call to the finder
rc = GetNPPBlobTable(    hFilterBlob,
                         &pBlobTable);

// Did we get anything?
if (rc != NMERR_SUCCESS)
    return FALSE;

//  To obtain a "special" blob.
//  Should have set
//  the filter blob to include the TAG_INTERFACE_REMOTE
//  interface – then only a TAG_INTERFACE_REMOTE interface
//  would return.

HBLOB OurBlob = NULL;
DWORD index;
for (index = 0; index < pBlobTable->dwNumBlobs; index++)
{
// Here is the test for a special blob
if (NMERR_SUCCESS ==
 (rc = GetStringFromBlob(pBlobTable->Blobs[index],
                           OWNER_NPP,
                           CATEGORY_FINDER,
                           TAG_DLL_FILENAME,
                           &DLLFileName)))
{
       // this is a special blob.
       // Check to see if it is supports the remote interface.
        BOOL bGoesRemote;
rc = GetBoolFromBlob( hBlob,
                           OWNER_NPP,
                           CATEGORY_CONFIG,
                           TAG_INTERFACE_DELAYED_CAPTURE,
&bGoesRemote);
        if (rc == NMERR_SUCCESS && bGoesRemote)
        {
             // This is the one we want
             // Save it off
             OurBlob = pBlobTable->Blobs[index];
             break;
        }
}
if (OurBlob == NULL)
        return FALSE;

// Set the computer name in our special blob.
rc = SetStringInBlob(OurBlob,
                     OWNER_NPP,
                     CATEGORY_LOCATION,
                     TAG_REMOTE_MACHINE_NAME,
                     "mycomputer");

PBLOB_TABLE pSecondBlobTable;
// Call the finder again.
rc = GetNPPBlobTable(        OurBlob,
                                & pSecondBlobTable);

// Did we get anything?
if (rc != NMERR_SUCCESS)
        return FALSE;

// A Blob is now on mycomputer.
// Use the blob as shown in the previous example.


Creating Expert and Monitor Event Reference Pages

This section describes how to plan, develop, and test event reference pages (ERPs) and how to deploy them in an expert or monitor. For information about ERPs and how to use them with Network Monitor, see Event Reference Page.

To develop a new ERP, the first step is determining the events that require individual ERPs for your custom expert or monitor. You must create separate ERPs for each event you wish to display in the Network Monitor Event Viewer. For example, suppose that:

  • You develop a monitor named Game Monitor and Stock Watcher.
  • The monitor is located in a file called Gamemon.dll.
  • The monitor generates two events, Game Running and My Internet Stock Soars.
  • You plan to develop two ERPs, Gamemon1.htm and Gamemon2.htm.

Note It's not necessary to have a one-to-one correspondence of ERPs to monitor or expert events.

After you have established a list of unique ERPs, follow these steps to create each ERP.

  • Write the HTML source document.
  • Save and name the HTML source file as an .htm file.
  • Test the ERP with the completed expert or monitor.


Writing an Event Reference Page

Use event reference pages (ERPs) to describe how to solve a problem that is detected by the expert or monitor. Because ERPs consist of HTML text, you can use any HTML editor or text editor to create one.

The Network Monitor Event browser pane that displays the ERP supports all the functionality of Microsoft® Internet Explorer 4.01 and later. Embed any supported controls or scripted language in your ERP to display information or launch other functionality from your ERP. For example, you can create a control that sends e-mail to network operations.

The following code is an example of a Game Monitor ERP created in Microsoft® FrontPage® Editor and displayed in HTML format:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>

<head>
<title>Eliminate Unauthorized Network Usage</title>
<meta name="AUTHOR" content="Hal &amp; Monitor Writer">
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
</head>

<body bgcolor="#FFFFFF">

<p><font FACE="Arial"><font size="2"><br>
</font><b><font size="4">Eliminate Unauthorized Network Usage </font><font size="2"><br>
</font></b></font><br>
<font size="2" face="Arial">The <strong>Game Monitor</strong> detects unauthorized use of
company network resources. </font></p>
<font FACE="Arial">

<p><font size="2"><b>MORE INFORMATION </b></font></p>

<p><b><font size="2">Troubleshooting Tips and Techniques </font></b></font></p>

<pre>
1. View IP destination address and MAC address from Event viewer.</pre>

<pre>2. Generate Log File Access Violation. Click the <strong>Send Log File</strong>
<strong>   </strong>button below to send the file to the network operations center</pre>

<pre>3. Verify that the Network File Access list updates with the event queue.

</pre>

<form method="POST" action="--WEBBOT-SELF--">
  <!--webbot bot="SaveResults" U-File="_private/form_results.txt" S-Format="TEXT/CSV"
  S-Label-Fields="TRUE" --><p><input type="button" value="Send Log File" name="B1"></p>
</form>
<font FACE="Arial">

<hr>
</font>
</body>
</html>

When editing is complete, name the ERP in accordance with the naming convention.

For more information about creating an ERP, see the following topics:

  • Creating Expert and Monitor Event Reference Pages
  • Naming an Event Reference Page
  • Testing an Event Reference Page


Naming an Event Reference Page

After you author an event reference page (ERP) source HTML document, you must name it before Network Monitor can display it in the Event Viewer.

Name monitor and expert ERP files with this format:

<ExpertName><EventIdent>.htm (or <MonitorName><EventIdent>.htm)
ExpertName
DLL file name, excluding the file extension.
EventIdent
Event identifier of the expert ERP.

The event identifier is also found in the EventIdent member of the NMEVENTDATA structure.

For more information about creating an ERP, see the following topics:

  • Creating Expert and Monitor Event Reference Pages
  • Writing and Event Reference Page
  • Testing an Event Reference Page


Installing Existing ERPs to Network Monitor 2.0

After you write and name an event reference page (ERP), you must install it.

To install an event reference page

  1. Create an ERP directory. These examples demonstrate directories for monitors and experts, respectively:
    C:\Program Files\NetMon2\Bok\Monitor\
C:\Program Files\NetMon2\Bok\Expert\
  2. Create a subdirectory for each new expert or monitor that will display the ERPs. The following subdirectory listings are for a monitor and an expert:
    C:\Program Files\NetMon2\Bok\Experts\MyMonitor
C:\Program Files\NetMon2\Bok\Experts\MyExpert
  3. Copy the ERP files to the associated subdirectory. The following examples provide complete paths to installed monitor and expert ERPs:
    C:\Program Files\NetMon2\Bok\Experts\MyMonitorMyEMonitor1.htm
C:\Program Files\NetMon2\Bok\Experts\MyExpert\MyExpert1.htm


Testing an Event Reference Page

The final step of creating an event reference page (ERP) is to test it. You can test an ERP by viewing the file in an HTML browser such as Microsoft® Internet Explorer. Or, you can install the ERP and its expert or monitor DLL to test it for event invocation and display it in the Network Monitor Event Viewer.

Viewing ERPs that Have No DLL

To view the completed ERP without an installed expert or monitor DLL, open the file with an HTML viewer that supports your embedded sources. The following figure shows the sample ERP file described in Writing an ERP as it is displayed using Microsoft Internet Explorer Version 4.01.

Testing ERPs that Have a DLL

After the ERP files and the expert (or monitor) DLL is created, you can test the complete functionality of your ERPs with Network Monitor. It is assumed that the DLL is debugged and can generate valid events.

To test ERPs that have a DLL

  1. Verify that the correct expert or monitor DLL is installed in the appropriate directory. For more information, see Installing an Expert to Network Monitor 2.0 and Installing a Monitor to Network Monitor.
  2. Verify the correct name of the ERP file.
  3. Verify the correct location of the ERPs in the Network Monitor directory.
  4. Test expert ERPs in the Network Monitor UI or test monitor ERPs with the Monitor Control Tool.
  5. Generate a test event.
  6. Verify that the ERP appears in the Network Monitor Event Viewer.

For more information about creating an ERP, see the following topics:

  • Creating Expert and Monitor Event Reference Pages
  • Writing an Event Reference Page
  • Naming an Event Reference Page


Creating Capture Filters

This section describes how to create a capture filter (a CAPTUREFILTER structure). Topics in this section include:

  • Writing Etype/Sap Filter Portion
  • Writing ADDRESSTABLE Filter Portion
  • Writing the PATTERNMATCH Filter
  • Clipping a Frame
  • Implementing the Capture Filter Code


Writing Etype/SAP Filter Portion

The Etype/SAP portion of the capture filter notifies the Network Monitor driver to accept frames that have a specific combination of Etypes and service access points (SAPs). Etypes and SAPs are both ways that low-level protocols such as Ethernet, LLC, and Snap indicate which protocol follows them. Specifically:

  • Ethernet specifies an Etype
  • LLC specifies a SAP
  • Snap specifies an Etype

Etype/SAP Capture Filter Flags

Use the following information to set the flags in the FilterFlags member of the CAPTUREFILTER structure.

Flag | Meaning
CAPTUREFILTER_ FLAGS_INCLUDE_ ALL_SAPS | Passes all SAP values and notifies the driver that all SAP values are valid. If combined with any values in the lpSapTable member, this flag notifies the driver that all SAP values except those in the lpSapTable are valid.
CAPTUREFILTER_ FLAGS_INCLUDE_ ALL_ETYPES | Passes all Etype values and notifies the driver that all Etype values are valid. If combined with any values in the lpEtypeTable member, this flag notifies the driver that all Etype values except those in the lpEtypeTable are valid.
CAPTUREFILTER_ FLAGS_LOCAL_ONLY | Setting this flag will not set a NIC to P-Mode. You will only see local traffic (any frames to the local machine).
CAPTUREFILTER_ FLAGS_KEEP_RAW | Keeps SMT and Token Ring MAC frames.

Etype/SAP Capture Filter Settings

Use the following information to set the lpSapTable and lpEtypeTable members of the CAPTUREFILTER structure.

Setting | Meaning
lpSapTable | Lists the SAP values that you want the driver to pass. This list tells the Network Monitor driver to validate any frame that contains a match. If CAPTUREFILTER_FLAGS_INCLUDE_ALL_SAPS is set, this becomes an exception list (if found, do not pass).
lpEtypeTable | Lists the Etype values that you want the Network Monitor driver to pass. This list alone tells the driver to validate any frame that contains a match. If CAPTUREFILTER_FLAGS_INCLUDE_ALL_ETYPES is set, this becomes an exception list (if found, do not pass).


Writing ADDRESSTABLE Filter Portion

The address filter notifies the Network Monitor driver to accept frames that have one of a variety of specified MAC address types (Ethernet, Token Ring, and FDDI). You can specify a maximum of eight address pairs. An address pair can specify a source, a destination, both, or neither.

The address portion of the filter consists of two structures: ADDRESSTABLE and ADDRESSPAIR.

If you specify NO addresses, then ALL frames will pass the address filter. However, if you specify any addresses, only those frames that pass the given address filter will pass.

Building the address filter involves allocating an ADDRESSTABLE structure and filling in members of the ADDRESSPAIR structure.

To build the address portion of a capture filter

  1. Use the CAPTUREFILTER_FLAGS_LOCAL_ONLY flag of the CAPTUREFILTER structure to restrict the capture to traffic to and from your local computer.

    Setting this flag will not set the NIC to promiscuous mode; the capture file will capture only local traffic.

  2. Use the following code sample to define the ADDRESSTABLE structure:
    typedef struct _ADDRESSTABLE
{
    DWORD           nAddressPairs;
    DWORD           nNonMacAddressPairs;
    ADDRESSPAIR     AddressPair[MAX_ADDRESS_PAIRS];
} ADDRESSTABLE;

typedef ADDRESSTABLE *LPADDRESSTABLE;

typedef struct _ADDRESSPAIR
{
    WORD        AddressFlags;
    WORD        NalReserved;
    ADDRESS     DstAddress;
    ADDRESS     SrcAddress;
} ADDRESSPAIR;
typedef ADDRESSPAIR *LPADDRESSPAIR;
  3. Use the following information to select an ADDRESSPAIR flag type.
    Flag | Meaning
    ADDRESS_FLAGS_MATCH_DST | Matches a destination address.
    ADDRESS_FLAGS_MATCH_SRC | Matches a source address
    ADDRESS_FLAGS_EXCLUDE | Excludes the frame if this address is found (either a defined source or destination).
    ADDRESS_FLAGS_DST_GROUP_ADDR | Matches group bit (of the destination address) only for broadcast-type messages.
    ADDRESS_FLAGS_MATCH_BOTH | Matches both the destination and source addresses.

  4. Fill in a destination address, which is evaluated against the ADDRESSPAIR flag that you select.
  5. Fill in a source address, which is evaluated against the ADDRESSPAIR flag that you select.
  6. Populate the ADDRESSTABLE structure with an array of ADDRESSPAIR structures, which includes the address pairs that the driver evaluates. All address pairs are evaluated as a logical OR statement (ADDRESSPAIR 1 || ADDRESSPAIR 2). You can include a maximum of eight address pairs in a capture filter.


Writing the PATTERNMATCH Filter

The pattern match filter notifies the driver to accept frames that have a specific pattern at a specific offset. You can specify a maximum of four detailed pattern matches, which can be combined in logical AND or OR statements for Network Monitor driver evaluation.

You implement pattern matches by using the following Network Monitor structures:

  • EXPRESSION
  • ANDEXP
  • PATTERNMATCH

To evaluate an OR statement, combine two to four pattern matches an ANDEXP structure (PatternMatch1 || PatternMatch2 || PatternMatch3). To evaluate an AND statement, combine one to four ANDEXP structures and an EXPRESSION structure (AndExp1 && AndExp2).

Pattern Match Definitions

A single pattern match is defined by the PATTERNMATCH structure. An individual match can operate in one of two ways.

Normally, the driver will take the offset basis (which can be OFFSET_BASIS_RELATIVE_TO_FRAME, OFFSET_BASIS_RELATIVE_TO_EFFECTIVE_PROTOCOL, OFFSET_BASIS_RELATIVE_TO_IPX, or OFFSET_BASIS_RELATIVE_TO_IP) and start counting there. The driver will count offset bytes from there and then match the data it finds with the first length bytes in PatternToMatch. If they are the same, and the PATTERN_MATCH_FLAGS_NOT flag is not set, then this pattern passes. If they are different and the PATTERN_MATCH_FLAGS_NOT has been set, the pattern passes. Otherwise this pattern fails.

Or:

If the PATTERN_MATCH_FLAGS_PORT_SPECIFIED flag is set, and the basis is set to OFFSET_BASIS_RELATIVE_TO_IPX or OFFSET_BASIS_RELATIVE_TO_IP, the comparison is more complex. First, the driver ensures that the offset basis protocol is there, then the driver verifies that the specified port matches the port in the frame. Finally the driver ensures that the PatternToMatch member matches as before, with the exception that the offset is from the end of IP or IPX. Note that if the basis is not one of these two, then the PATTERN_MATCH_FLAGS_PORT_SPECIFIED flag will be ignored, and the pattern will be evaluated as above.

To evaluate a single pattern match, an EXPRESSION structure must have one AndExp member containing a single pattern match.

Building the pattern match filter involves creating PATTERNMATCH structures and logically combining them with EXPRESSION and ANDEXP structures.

To write a PATTERNMATCH filter

  1. In the ANDEXP structure, populate the array with pattern matches.
  2. Populate the EXPRESSION structure with an array of AndExp members.

    Do not exceed a total of four pattern matches for the capture filter.

  3. In the PATTERNMATCH structure, select a flag type.
  4. Select an offset basis.
  5. Enumerate a port value.
  6. Define offset value.
  7. Define the pattern length.
  8. Enumerate the pattern value.

PATTERNMATCH Examples

This frame represents a standard offset.

The code fragment is implemented as:

Basis  ->   IP
Offset ->   4 (bytes)
Length ->   2 (bytes)
PatternToMatch[ ] = {x00, x00}

This frame depicts a port-specified offset (against IPX).

The code fragment is implemented as:

Port   ->   544
Basis  ->   IPX
Offset ->   2 (bytes)
Length ->   2 (bytes)
PatternToMatch[ ] = {x00, x00}


Clipping a Frame

You can specify that the driver clip the frames. (If the other capture filter sections are omitted, this may be the only function of your capture filter). If the nFrameBytesToCopy field is not zero (0), its value specifies how many bytes of each frame received to retain. If the field is zero, then the whole frame is retained.

Note You may clip any frame that passes the other portions of your capture filter by setting nFrameBytesToCopy.


Implementing the Capture Filter Code

After you determine how to organize your filter through a CAPTUREFILTER structure, you must allocate and fill in the structure, which is then passed to the Network Monitor driver through a configuration BLOB.

For monitors, you add the capture filter to the BLOB handed to the IMonitor::DoInitialize method. Direct NPP users add the capture filter to the configuration BLOB that is passed to Connect, Configure, or both. For a list of COM interfaces that you can use to communicate with the NPP, see NPP Interfaces.

The Network Monitor SDK contains sample code that shows a complete implementation of a capture filter in a monitor. Review the ICMP Redirect monitor code (Icmprd.cpp) located in the Monitors subdirectory (a typical installation would be C:\Program Files\NetMon2SDK\Monitors).


Reference

This section provides complete reference information for the following COM interfaces, functions, and structures used to develop monitor, expert, parser, and NPP applications.

Item | Description
Monitor Interfaces | COM interfaces used to develop custom real-time monitors.
Monitor Functions | Helper functions used to develop custom real-time monitors.
Expert and Parser Common Functions | Functions used to develop parser and experts.
Expert Functions, Structures, and Enumerations | Export functions, helper functions, structures, and enumerations used to develop experts.
Parser Functions and Structures | Export functions, helper functions, and structures used to develop parsers.
NPP Interfaces | COM interfaces used to develop NPP applications.
NPP Structures | Structures used to develop NPP applications.
BLOB Functions | Functions used to manage Network Monitor BLOBs.
BLOB Structures | Structures used by BLOB functions.


Monitor Interfaces

The following COM interfaces are used to develop monitors.

Interface | Description
IMonitor | Provides methods that control monitor operation. This interface must be implemented by the monitor
IMonitorEventer | Provides methods used to send events. This interface is provided by the Monitor Control Service (MCSVC).


IMonitor

The IMonitor interface provides methods that control monitor operation. These methods are called by the Monitor Control Service (MCSVC).

Methods in Vtable Order

Method | Description
DoInitialize | Initializes a monitor.
DoConfigure | Updates monitor configuration.
OnStart | Indicates that the monitor has been configured successfully and that the data capture is about to begin.
OnStop | Indicates data capture completion.
OnFrames | Indicates the status of a frame event.
OnStatus | Indicates an NPP status event.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


IMonitor::DoInitialize

The DoInitialize method must be implemented by the monitor. The MCSVC calls this method to obtain a capture filter immediately before calling the NPP's IRTC::Connect method.

HRESULT DoInitialize(
  IUnknown *pUnkMonitorCtrl,
  HBLOB hNPPBlob
);

Parameters

pUnkMonitorCtrl
[in] An IUnknown pointer passed in by the MCSVC. To obtain a supported monitor control interface, the monitor must call IUnknown::QueryInterface on the pointer.
hNPPBlob
[in, out] On input, a handle to an NPP BLOB.

On output, an NPP BLOB that contains a capture filter.

Return Values

If the method is successful, the return value is S_OK (which is the same as NOERROR).

If the method is unsuccessful, the return value is an error code. On error, the MCSVC will not create the monitor or call IUnknown::Release on the interface pointer.

Remarks

The MCSVC calls the DoInitialize method to perform any required monitor initialization.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


IMonitor::DoConfigure

The DoConfigure method must be implemented by the monitor. The MCSVC calls this method to obtain configuration information for the capture.

HRESULT STDMETHODCALLTYPE DoConfigure(
  char *pName,
  char *pConfiguration,
  char **ppScriptInstance
);

Parameters

pName
[in] Name of an instance of the monitor.
pConfiguration
[in] Configuration string provided by the MCSVC. The monitor must parse this string for configuration data.
ppScriptInstance
[out] Address of the HTML string used to configure the monitor. If a default script is used for configuration, this value should be set to NULL.

Return Values

If the method is successful, the return value is S_OK (which is the same as NOERROR), and the MCSVC will run the monitor.

If the method is unsuccessful, the return value is an error code. A return value of NMERR_MONITOR_CONFIG_FAILED is acceptable, but when this error is returned, the monitor cannot start until a future DoConfigure call succeeds. Any other error prevents the instance of the monitor from being enabled.

Remarks

The MCSVC calls this method after it has connected to the network and before the IRTC::Configure method is called.

The monitor can store information provided by this call, update the HTML script or configuration string, and set the capture filter in the NPP BLOB.

The MCSVC may call this method several times, but it cannot be not called while the monitor is capturing data. Note that every time an NPP starts a capture, the connection to the network must be configured. This restriction includes situations in which the NPP starts and stops the same capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


IMonitor::OnFrames

The OnFrames method must be implemented by the monitor. The MCSVC calls this method when either the capture buffer is full or the update time has passed.

HRESULT OnFrames (
  UPDATE_EVENT Event
);

Parameters

Event
[in] UPDATE_EVENT structure that holds frame information used to update events.

Return Values

If the method is successful, the return value is S_OK (which is the same as NOERROR). The MCSVC passes the returned value back to the NPP for processing.

If the method is unsuccessful, the return value is an error code. The MCSVC passes the returned value back to the NPP for processing.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


IMonitor::OnStart

The OnStart method is an optional method that can be implemented by the monitor. The MCSVC calls this method to request that the monitor start the capture.

HRESULT OnStart(
  IUnknown *pUnkNPP
);

Parameters

pUnkNPP
[in] An IUnknown pointer to the IRTC interface. The monitor can use this interface to obtain statistics that can be used to determine if the capture should be started.

Return Values

If the method is successful, the return value is S_OK (which is the same as NOERROR). When S_OK is returned, the MCSVC calls the IRTC::Start method.

If the method is unsuccessful, the return value is an error code. The MCSVC will not start the capture if any error code is returned.

Remarks

The MCSVC calls this method before the NPP's IRTC::Start method is called to start the capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.

See Also

Network Packet Providers


IMonitor::OnStatus

The OnStatus method must be implemented by the monitor. The MCSVC calls this method to notify the monitor that an NPP status event exists.

HRESULT OnStatus(
  UPDATE_EVENT Event
);

Parameters

Event
[in] An UPDATE_EVENT structure.

Return Values

If the method is successful, the return value is S_OK (which is the same as NOERROR), and the MCSVC passes the returned value back to the NPP for processing.

If the method is unsuccessful, return an error code. On error, the MCSVC passes the returned value back to the NPP for processing.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


IMonitor::OnStop

The OnStop method must be implemented by the monitor. The MSCVC calls this method to notify the monitor that the capture will be stopped.

HRESULT OnStop( void );

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is S_OK (which is the same as NOERROR).

If the method is unsuccessful, the return value is an error code. When an error code is returned, the monitor cannot be restarted.

Remarks

The MCSVC calls this method after IRTC::Stop is called.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


IMonitorEventer

The IMonitorEventer interface provides methods for submitting events and allocating and freeing monitor resources.

Methods in Vtable Order

Method | Description
GetEventData | Allocates space for monitor data.
SendNMEvent | Submits events to WMI.
FreeEventData | Frees space allocated for monitor data.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


IMonitorEventer::FreeEventData

The FreeEventData method frees space allocated for the NMEVENTDATA structure.

HRESULT FreeEventData(
  PNMEVENTDATA pNMEventData
);

Parameters

pNMEventData
[in] Address of the NMEVENTDATA structure, the memory of which is freed.

Return Values

This method always returns S_OK.

Remarks

Monitors call this method to free the memory they allocate for the event data structure. Note that while the monitor still has a pointer to strings in an allocated NMEVENTDATA structure, the memory for these strings must be freed before the FreeEventData method is called.

To allocate memory for an NMEVENTDATA structure, see IMonitorEventer::GetEventData.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.

See Also

IMonitorEventer::GetEventData, NMEVENTDATA


IMonitorEventer::GetEventData

The GetEventData method allocates space for the NMEVENTDATA and NMCOLUMNINFO structures.

HRESULT GetEventData (
  BYTE bNumColumns,
  PNMEVENTDATA *ppNMEventData
);

Parameters

bNumColumns
[in] Number of NMCOLUMNINFO structures needed.
ppNMEventData
[out] Address of the NMEVENTDATA structure that is returned.

Return Values

If the method is successful, the return value is S_OK.

If the method is unsuccessful, the return value is NMERR_OUT_OF_MEMORY.

Remarks

Monitors call this method to allocate memory for the event data and column information structures. To free memory allocated for an NMEVENTDATA structure, see IMonitorEventer::FreeEventData.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.

See Also

IMonitorEventer::FreeEventData, NMEVENTDATA, NMCOLUMNINFO


IMonitorEventer::SendNMEvent

The SendNMEvent method submits events to Windows Management Instrumentation (WMI).

HRESULT SendNMEvent (
  PNMEVENTDATA pNMEventData
);

Parameters

pNMEventData
[in] Pointer to the event submitted to WMI.

Return Values

If the method is successful, the return value is S_OK.

If the method is unsuccessful, the return value is NMERR_OUT_OF_MEMORY.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


Monitor Functions

This section describes the helper functions you can use to develop custom monitors.

Function | Description
DllGetMonitorObject | Creates an instance of the monitor.
HTMLValueToUnicode | Converts an HTML CP_UTF8 version string to Unicode.
LoadDWORD | Loads a DWORD from an HTML configuration string.
LoadIPAddresses | Loads an IP address list from an HTML TEXTAREA configuration string.
LoadIPXAddresses | Loads an IPX address list from an HTML TEXTAREA configuration string.
LoadMACAddresses | Loads a MAC address list from an HTML TEXTAREA configuration string.
LoadStringAddr | Transforms a string (such as "157.54.32.45") to a DWORD address.
LoadTCHAR | Searches for a requested variable name in the configuration string, and allocates sufficient space (by using HeapAllocMemory) to store, copy, and return it.
OnLoadingDLL | Indicates that the DLL has begun to load. The MCSVC calls this function when it first loads the monitor DLL.


DllGetMonitorObject

The DllGetMonitorObject function must be implemented by the monitor. The MCSVC calls this function to create an instance of the monitor.

HRESULT DllGetMonitorObject(
  REFIID riid,
  LPVOID *ppObj
);

Parameters

riid
[in] UUID of monitors, shown below, as defined in the IMonitor.h header file. If an invalid UUID is provided, the function fails, and the monitor must return E_NOINTERFACE.
IID_IMonitor
ppObj
[out] Pointer to a pointer that receives the interface requested in riid.

Return Values

If the function is successful, the return value is S_OK (which is the same as NOERROR).

If the function is unsuccessful, the return value is a failure code. When a failure code is returned, the MCSVC does not create the monitor object, and the IUnknown::Release method is not called on the interface pointer.

Remarks

The DllGetMonitorObject function is called each time the MCSVC tries to create an instance of the monitor. This function intentionally bears a strong resemblance to the more common DllGetClassObject function. The main difference is that a CLSID is not passed in to DllGetMonitorObject.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


HTMLValueToUnicode

The HTMLValueToUnicode function converts an HTML CP_UTF8 string to a Unicode string.

WCHAR* HTMLValueToUnicode(
  const char *pValue
);

Parameters

pValue
[in, out] On input, pointer to the HTML string supplied by the MCSVC.

On output, pointer to the converted Unicode string.

Return Values

The function returns the Unicode equivalent of the string.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Monhlprs.h.
Library: Use Monitors.lib.


LoadDWORD

The LoadDWORD function is called by the monitor to set a DWORD variable with a value taken from an HTML configuration string variable.

BOOL LoadDWORD(
  const char *pConfig,
  const char *pVarName,
  DWORD *pValue
);

Parameters

pConfig
[in] Pointer to the HTML configuration string passed to the monitor by the IMonitor::DoConfigure method.
pVarName
[in] Pointer to the name of the variable in the configuration string.
pValue
[in] Pointer to the DWORD variable that is set to the value of the configuration string variable.

Return Values

If the function is successful (if the variable name was found and had a non-zero-length string), the DWORD is inserted, and the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

The following code shows the calling syntax used to set a DWORD variable. Note that in this example, if the call succeeds, dwStartNumber will contain the value of the configuration string's starting number variable.

DWORD dwStartNumber:
LoadDWORD(
    "ConfigString",
    "StartingNumber",
    &dwStartNumber
);

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Monhlprs.h.
Library: Use Monitors.lib.


LoadIPAddresses

The LoadIPAddresses function is called by the monitor to fill in an IP address list with addresses taken from an HTML configuration string variable.

BOOL LoadIPAddresses(
  const char *pConfig,
  const char *pVarName,
  DWORD **ppAddresses,
  DWORD *pNumAddresses
);

Parameters

pConfig
[in] Pointer to the HTML configuration string passed to the monitor by the IMonitor::DoConfigure method.
pVarName
[in] Pointer to the name of the variable in the configuration string.
ppAddresses
[out] Pointer to a pointer to an array of addresses. If the variable specified in pVarName is found and has a non-zero-length, the function allocates sufficient space (by using HeapAllocMemory) and stores all the IP addresses as an array.
pNumAddresses
[out] Pointer to the DWORD variable that is set to the number of IP addresses taken from the configuration string.

Return Values

If the function is successful (the variable name was found and had a non-zero-length string that represented IP addresses), the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

The IP addresses must be in x.x.x.x format (for example, 127.0.0.1).

The following code shows the calling syntax for setting an IP address list. Note that in this example, pAddresses will contain the IP addresses taken from the configuration string and dwNumAddresses will contain the number of address.

DWORD* pAddresses;
DWORD  dwNumAddresses;

LoadIPAddresses(
    "ConfigString",
    "Addresses",
    &pAddresses,
    &dwNumAddresses
);

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Monhlprs.h.
Library: Use Monitors.lib.


LoadIPXAddresses

The LoadIPXAddresses function is called by the monitor to fill in an IPX address list taken from an HTML configuration string variable.

BOOL LoadIPXAddresses(
  const char *pConfig,
  const char *pVarName,
  IPX_ADDRESS **ppAddresses,
  DWORD *pNumAddresses
);

Parameters

pConfig
[in] Pointer to the HTML configuration string passed to the monitor by the IMonitor::DoConfigure method.
pVarName
[in] Pointer to the name of the variable in the configuration string.
ppAddresses
[out] Pointer to a pointer to an array of addresses. If the variable specified in pVarName is found and has a non-zero-length, sufficient space is allocated (by using HeapAllocMemory), and all the IPX addresses are stored as an array.
pNumAddresses
[out] Pointer to the DWORD variable that is set to the number of IPX addresses taken from the configuration string.

Return Values

If the function is successful (the variable name was found and had a non-zero-length string that represented IPX addresses), the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Monhlprs.h.
Library: Use Monitors.lib.


LoadMACAddresses

The LoadMACAddresses function is called by the monitor to fill in a MAC address list with addresses taken from an HTML configuration string variable.

BOOL LoadMACAddresses(
  const char *pConfig,
  const char *pVarName,
  LPBYTE *ppAddresses,
  DWORD *pNumAddresses
);

Parameters

pConfig
[in] Pointer to the HTML configuration string passed to the monitor by the IMonitor::DoConfigure method.
pVarName
[in] Pointer to the name of the variable in the configuration string.
ppAddresses
[out] Pointer to a pointer to an array of addresses. If the variable specified in pVarName is found and has a non-zero-length, the function allocates sufficient space (by using HeapAllocMemory) and stores all the MAC addresses as an array.
pNumAddresses
[out] Pointer to the DWORD variable that is set to the number of MAC addresses taken from the configuration string.

Return Values

If the function is successful, (the variable name was found and had a non-zero-length string that represented MAC addresses), the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Monhlprs.h.
Library: Use Monitors.lib.


LoadStringAddr

The LoadStringAddr function transforms a string (such as "157.54.32.45") and creates a DWORD address.

BOOL LoadStringAddr(
  DWORD *pAddress,
  const char *str
);

Parameters

pAddress
Pointer to a DWORD.
str
Pointer to a character string with x.x.x.x representation of an IP address (for example,127.0.0.1).

Return Values

If the function is successful (the address name was found); the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Monhlprs.h.
Library: Use Monitors.lib.


LoadTCHAR

The LoadTCHAR function is called by monitors to set a string variable to a string taken from an HTML configuration string.

BOOL LoadTCHAR(
  const char *pConfig,
  const char *pVarName,
  char **ppszString
);
pConfig
[in] Pointer to the HTML configuration string passed to the monitor by the IMonitor::DoConfigure method.
pVarName
[in] Pointer to the name of the variable in the configuration string.
ppszString
[out] Pointer to a string pointer. If the requested variable name is found, the string is allocated (by using HeapAllocMemory) and assigned to this pointer. It is the user's responsibly to free the memory associated with the string.

Return Values

If the function is successful (if the variable name was found and had a non-zero-length string), the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

The following code shows the calling syntax used to set the string. Note that in this example, pFilePath will contain the file path provided by the configuration string.

char *pFilePath;
LoadTCHAR(
    "ConfigString",
    "FilePath",
    &pFilePath
);

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Monhlprs.h.
Library: Use Monitors.lib.


OnLoadingDLL

The MCSVC calls the OnLoadingDLL function to load the monitor DLL.

HRESULT OnLoadingDLL(
  HBLOB hFilterBlob,
  DWORD *pCreateFlags,
  char **ppDefaultName,
  char **ppDescription,
  char **ppDefaultScript,
  char **ppDefaultConfig
);

Parameters

hFilterBlob
[in, out] BLOB that the MCSVC uses to match a monitor with available NICs. This parameter always contains a request for an IRTC interface, so most monitors do not need to add any entries to the BLOB. However, a custom monitor can add additional filter criteria (for example, that the MAC type must be Ethernet).
pCreateFlags
[in] Flags that indicate how the MCSVC controls the creation of a monitor. This parameter must be one of the following values:
MCS_CREATE_ONE_PER_NETCARD
The MCSVC ensures that only one instance of this monitor exists for each NIC. A second instance can be created only if the first one is destroyed.
MCS_CREATE_CONFIGS_BY_DEFAULT
If the monitor has a default internal configuration, the MCSVC does not require the user to configure the monitor before the instance is created.
ppDefaultName
[out] Pointer to a pointer to the address of the default name of the monitor. The MCSVC uses the default name when creating instances of the monitor.

For example, if the returned default name is "Router Monitor", the first monitor instance would be "Router Monitor 1", the second would be "RouterMonitor2, and so on. If NULL is returned, the MCSVC uses the name of the DLL.

ppDescription
[out] Pointer to a pointer to the address of the description of the monitor. The description is passed to the Monitor Control Tool, which uses the description to indicate to the user that the monitor exists. This parameter can return NULL.
ppDefaultScript
[out] Pointer to a pointer to the address of the default HTML Form script used to configure the monitor. Although the instances of the monitor can alter their own script, most monitors simply load their script once, from a file. The value of ppDefaultScript can be NULL; however, then either the monitor cannot be externally configured, or it must supply a script later. It is more efficient to supply a default script here.
ppDefaultConfig
[out] Address of the default string used to configure the monitor when it is created. This parameter can be set to NULL.

Return Values

If the function is successful, the return value is S_OK (which is the same as NOERROR).

If the function is unsuccessful, the MCSVC omits the specified monitor from all its lists (afterward, no monitor of this type can be created).

Remarks

The OnLoadingDLL function is called just once by the MCSVC, when it first loads the DLL. The DLL then provides the default values that will be used by the MCSVC when creating an instance of a monitor.

The monitor must allocate all the necessary memory for the strings returned to the MCSVC. On return, the MCSVC makes copies of all the strings and will not attempt to free the returned strings.

The monitor should use BLOB helper functions to alter the filter BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Imonitor.h.


Expert and Parser Common Functions

You can use the following functions with Network Monitor to develop either parsers or experts.

Function | Description
CompareAddresses | Compares two given addresses.
CompareFrameDestAddress | Compares a given address to the destination address of a frame.
CompareFrameSourceAddress | Compares a given address to the source address of a frame.
FilterAddObject | Adds a single object to a filter.
FindPropertyInstance | Finds the first instance of a given property.
FindPropertyInstanceRestart | Finds the next instance of a given property.
GetCaptureComment | Retrieves the comment of a capture.
GetCaptureCommentFromFilename | Retrieves the comment of a capture from its capture file.
GetCaptureMacType | Retrieves the MAC type of the capture.
GetCaptureTimeStamp | Retrieves the capture timeout stamp.
GetCaptureTotalFrames | Retrieves the total frames in the capture.
GetEnabledProtocols | Retrieves a list of all the protocols marked as enabled.
GetFrame | Retrieves a handle to a given frame.
GetFrameCaptureHandle | Retrieves a handle to a given capture.
GetFrameDstAddressOffset | Retrieves the destination address offset for a given frame.
GetFrameFromFrameHandle | Retrieves a frame for a given frame handle.
GetFrameLength | Retrieves the length of a given frame.
GetFrameMacHeaderLength | Retrieves the length of the MAC header for a given frame.
GetFrameMacType | Retrieves the MAC type for a given frame.
GetFrameNumber | Returns the number of a given frame.
GetFrameRecognizeData | Retrieves the protocol identifiers (and their offsets) of all recognized protocols.
GetFrameSrcAddressOffset | Retrieves the offset to the source address of a given frame.
GetFrameStoredLength | Retrieves the length of a given frame.
GetFrameTimeStamp | Retrieves the time stamp of a given frame.
GetPreviousProtocolOffsetByName | Retrieves the previous instance of a given protocol.
GetProperty | Retrieves a property with a given name.
GetPropertyInfo | Retrieves the information of a specific property.
GetPropertyText | Retrieves the text of a given property.
GetProtocolFromName | Retrieves a specific protocol by name.
GetProtocolInfo | Uses the protocol handle to retrieves protocol-related information.
GetProtocolStartOffsetHandle | Retrieves the offset of a given protocol.
MacTypeToAddressType | Converts a MAC type to an address type.
ModifyFrame | Updates an existing frame with new data.

For information about functions and structures that are only used by experts and functions and structures that are only used by parsers, see the following topics:

For information about | See
Expert-specific functions that you can used to develop expert DLLs. | Expert Functions, Structures, and Enumerations
Parser-specific functions that you can used to develop parser DLLs. | Parser Functions and Structures


CompareAddresses

The CompareAddresses function compares two addresses, indicating that one of the addresses is greater than, less than, or equal to the other address.

int WINAPI CompareAddresses(
  LPADDRESS lpAddress1,
  LPADDRESS lpAddress2
);

Parameters

lpAddress1
[in] Pointer to the first address.
lpAddress2
[in] Pointer to the second address.

Return Values

If the addresses are the same, the function returns zero.

If the lpAddress1 parameter specifies an address that is less than the address that the lpAddress2 parameter specifies, the return value is a negative number.

If the lpAddress1 specifies an address that is greater than the address that the lpAddress2 parameter specifies, the return value is a positive number.

Remarks

An address that is less than another address indicates a previous frame. An address that is greater than another address indicates a later frame.

Network Monitor provides two other functions, CompareFrameDestAddress and CompareFrameSourceAddress, which you can use to compare addresses. The CompareFrameDestAddress function compares a given address to the frame's destination address, and the CompareFrameSourceAddress function compares a given address to the frame's source address.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

CompareFrameDestAddress, CompareFrameSourceAddress


CompareFrameDestAddress

The CompareFrameDestAddress function compares an address to the destination address of a frame.

BOOL WINAPI CompareFrameDestAddress(
  HFRAME hFrame,
  LPADDRESS lpAddress
);

Parameters

hFrame
[in] Handle to a frame.
lpAddress
[in] Pointer to an address.

Return Values

If the addresses are the same, the return value is TRUE.

If the addresses are not the same, the return value is FALSE.

Remarks

For the CompareFrameDestAddress function to return successfully, the destination address type must match the type of address specified in the lpAddress parameter.

Network Monitor provides two other functions, CompareFrameSourceAddress and CompareAddresses, which you can use to compare addresses. The CompareFrameSourceAddress function compares a given address to the frame's source address, and the CompareAddress function compares two given addresses.

Experts and parsers can call the CompareFrameDestAddress function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

CompareAddresses, CompareFrameSourceAddress


CompareFrameSourceAddress

The CompareFrameSourceAddress function compares an address to the source address of a frame.

BOOL WINAPI CompareFrameSourceAddress(
  HFRAME hFrame,
  LPADDRESS lpAddress
);

Parameters

hFrame
[in] Handle to a frame.
lpAddress
[in] Pointer to an address.

Return Values

If the addresses are the same, the return value is TRUE.

If the addresses are not the same, the return value is FALSE.

Remarks

For the CompareFrameSourceAddress function to succeed, the source address type must match the type of address specified in the lpAddress parameter.

Network Monitor provides two other functions for comparing addresses: CompareFrameDestAddress and CompareAddresses. The CompareFrameDestAddress function compares a given address to the frame's destination address, and the CompareAddress function compares two given addresses.

Experts and parsers can call the CompareFrameSourceAddress function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

CompareAddresses, CompareFrameDestAddress


FilterAddObject

The FilterAddObject function adds a single object to a display filter.

DWORD WINAPI FilterAddObject(
  HFILTER hFilter,
  LPFILTEROBJECT lpFilterObject
);

Parameters

hFilter
[in] Handle to the display filter.
lpFilterObject
[out] Pointer to a FILTEROBJECT structure that defines the object to be added to the filter. Each object can be an operator, value, or property.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is an error code.

Error Codes

Code | Meaning
NMERR_INVALID_PARAMETER | The hFilter parameter has an invalid value.
NMERR_OUT_OF_MEMORY | Network Monitor does not have enough memory to create the object.

Remarks

Experts and parsers can call the FilterAddObject function.

The FilterAddObject function is called each time a filter object is added to the display filter. The display filter is a postfix stack of objects that can be an operator, value, or property.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Filter.h.
Library: Use NMAPI.lib.

See Also

FILTEROBJECT


FindPropertyInstance

The FindPropertyInstance function finds the first instance of the property specified by the hProperty parameter.

LPPROPERTYINST WINAPI FindPropertyInstance(
  HFRAME hFrame,
  HPROPERTY hProperty
);

Parameters

hFrame
[in] Handle to the frame. The frame handle can be retrieved by a call to the GetFrame function.
hProperty
[in] Handle to the property you want to find. The property handle can be retrieved by a call to the GetProperty function.

Return Values

If the function is successful (that is, if the property is found), the return value is a pointer to the first instance of the property.

If the function is unsuccessful, the return value is NULL.

Remarks

To retrieve the next instance of the property, call FindPropertyInstanceRestart.

Experts and parserscan call the FindPropertyInstance function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

FindPropertyInstanceRestart


FindPropertyInstanceRestart

The FindPropertyInstanceRestart function finds the next instance of the property specified by the hProperty parameter.

LPPROPERTYINST WINAPI FindPropertyInstanceRestart(
  HFRAME hFrame,
  HPROPERTY hProperty,
  LPPROPERTYINST *lpRestartKey,
  BOOL DirForward
);

Parameters

hFrame
[in] Handle to the frame. The frame handle can be retrieved by a call to the GetFrame function.
hProperty
[in] Handle to the property you want to find. The property handle can be retrieved by a call to the GetProperty function.
lpRestartKey
[in] Pointer to the property instance used as the starting point of the search. If the lpRestartKey parameter is set to NULL, the search begins at beginning of the frame, or the end of the frame, depending on the value of the DirForward parameter.

If lpRestartKey points to NULL, the search begins at the beginning of the frame if DirForward is TRUE or the at end of the frame if the parameter is FALSE.

DirForward
[in] Indicator of the search direction. If the value is TRUE, the search moves from the current location to the end of the frame. If the value is FALSE, the search moves from the current location to the beginning of the frame.

Return Values

If the function is successful, the return value is the next valid LPPROPERTYINST.

If the function is unsuccessful, the return value is NULL.

Remarks

Experts and parsers can call the FindPropertyInstanceRestart function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

GetFrame, GetProperty


GetCaptureComment

The GetCaptureComment function returns a pointer to the comment of a capture.

LPSTR WINAPI GetCaptureComment(
  HCAPTURE hCapture
);

Parameters

hCapture
[in] Handle to the capture. See Remarks for information about obtaining the capture handle.

Return Values

If the function is successful (that is, if the capture contains a comment), the return value is a pointer to the comment string.

If the function is unsuccessful, the return value is NULL.

Remarks

Do not alter the returned comment string which is the actual comment string that is in the loaded capture. Any changes can corrupt the capture. Attempts to modify the string result in an access violation.

The handle of the capture can be obtained in several ways, depending if the call is made by an expert or parser. For experts, the handle is specified in the hCapture member of the EXPERTSTARTUPINFO structure. For parsers, the capture handle can be obtained by calling the GetFrameCaptureHandle function.

To retrieve the comment of a capture from its capture file, call the GetCaptureCommentFromFilename function.

Experts and parsers can call the GetCaptureComment function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

EXPERTSTARTUPINFO, GetCaptureCommentFromFilename, GetFrameCaptureHandle


GetCaptureCommentFromFilename

The GetCaptureCommentFromFilename function extracts the capture comment from a capture file.

DWORD  WINAPI GetCaptureCommentFromFilename(
  LPSTR lpFilename,
  LPSTR lpComment,
  DWORD BufferSize
);

Parameters

lpFilename
[in] Pointer to the name of the capture file.
lpComment
[in] Pointer to a pre-allocated string for the comment.
BufferSize
[in] Size of the string.

Return Values

If the function is successful (that is, if the comment is found and copied, or there is no comment in the capture file), the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is an error code.

Error Codes

NMERR_FILE_READ_ERROR
The capture comment cannot be read.
NMERR_INVALID_FILE_FORMAT
The Comment frame is not a valid file format.
NMERR_FILE_NOT_FOUND
The file specified by the lpFilename parameter cannot be found.
NMERR_INVALID_PARAMETER
One of the parameters is specified incorrectly.

Remarks

Experts and parsers can call the GetCaptureCommentFromFilename function.

To retrieve the comment of a real-time capture, call the GetCaptureComment function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

GetCaptureComment


GetCaptureMacType

The GetCaptureMacType function returns the MAC type of a given capture.

DWORD WINAPI GetCaptureMacType(
  HCAPTURE hCapture
);

Parameters

hCapture
[in] Handle to the capture. For information about obtaining the capture handle, see the Remarks section in this GetCaptureMacType topic.

Return Values

If the function is successful, the return value is one of the following MAC types.

  • MAC_TYPE_UNKNOWN
  • MAC_TYPE_ETHERNET
  • MAC_TYPE_TOKENRING
  • MAC_TYPE_FDDI

If the function is unsuccessful, the return value is an error code.

Error Codes

Code | Meaning
NMERR_MAC_TYPE_UNKNOWN | Network Monitor could not find a known MAC type.

Remarks

The handle of the capture can be obtained in several ways, depending on who makes the call. For experts, the handle is specified in the hCapture member of the EXPERTSTARTUPINFO structure. For parsers, the capture handle can be obtained by calling the GetFrameCaptureHandle function.

Experts and parsers can call the GetCaptureMacType function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetCaptureTimeStamp

The GetCaptureTimeStamp function returns the time and date when the capture started recording frames.

LPSYSTEMTIME WINAPI GetCaptureTimeStamp(
  HCAPTURE hCapture
);

Parameters

hCapture
[in] Handle to the capture. For information about obtaining the capture handle, see the Remarks section of this GetCaptureTimeStamp topic.

Return Values

If the function is successful, the return value is a pointer to a SYSTEMTIME structure.

If the function is unsuccessful, the return value is NULL.

Remarks

The GetCaptureTimeStamp function returns the time when the Network Packet Provider (NPP) starts collecting data, not when the expert loads the capture for analysis.

Do not overwrite the data in the SYSTEMTIME structure. The data is part of the capture. Trying to modify the data causes an access violation.

Experts and parsers can call the GetCaptureTimeStamp function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

SYSTEMTIME


GetCaptureTotalFrames

The GetCaptureTotalFrames function returns the total number of frames in the capture.

DWORD WINAPI GetCaptureTotalFrames(
  HCAPTURE hCapture
);

Parameters

hCapture
[in] Handle to the capture. For information about obtaining the capture handle, see the Remarks section of this GetCaptureTotalFrames topic.

Return Values

If the function is successful, the return value is the total number of frames in the capture.

If the function is unsuccessful, the return value is 0.

Remarks

Experts and parsers can call the GetCaptureTotalFrames function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetEnabledProtocols

The GetEnabledProtocols function returns a table of all protocols that are marked Enabled.

LPPROTOCOLTABLE WINAPI GetEnabledProtocols(
  HCAPTURE hCapture
);

Parameters

hCapture
[in] Handle to the capture.

Return Values

If the function is successful, the return value is a pointer to a PROTOCOLTABLE structure that lists all the enabled protocols in the capture.

If the function is unsuccessful, the return value is NULL.

Remarks

Experts and parsers can call the GetEnabledProtocols function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

PROTOCOLTABLE


GetFrame

The GetFrame function returns a handle to a given frame within a capture.

HFRAME WINAPI GetFrame(
  HCAPTURE hCapture,
  DWORD FrameNumber
);

Parameters

hCapture
[in] Handle to a capture. To obtain the capture handle, call the GetFrameCaptureHandle function.
FrameNumber
[in] Number (zero-based) of the frame. The number of the first frame in a capture is zero.

Return Values

If the function is successful, the return value is a handle to the frame.

If the function is unsuccessful (that is, if hCapture is invalid, or the frame number is out of range), the return value is NULL.

Remarks

Use the GetFrame function to obtain the frame handle needed when locating instances of a property. The functions used to locate property instances are FindPropertyInstance which locates the first instance, and FindPropertyInstanceRestart which locates the next instance.

Experts and parsers can call the GetFrame function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

FindPropertyInstance, FindPropertyInstanceRestart.


GetFrameCaptureHandle

The GetFrameCaptureHandle function returns a handle to the capture based on a given frame.

HCAPTURE WINAPI GetFrameCaptureHandle(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to a frame.

Return Values

If the function is successful, the return value is a handle to the capture.

If the function is unsuccessful, the return value is 0.

Remarks

Experts and parsers can call the.GetFrameCaptureHandle function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameDstAddressOffset

The GetFrameDstAddressOffset function returns the offset to the destination address of a given frame.

DWORD WINAPI GetFrameDstAddressOffset(
  HFRAME hFrame,
  DWORD AddressType,
  LPDWORD AddressLength
);

Parameters

hFrame
[in] Handle to the frame.
AddressType
[in] Type of the destination address. Specify one of the following values:

ADDRESS_TYPE_ETHERNET
ADDRESS_TYPE_IP
ADDRESS_TYPE_IPX
ADDRESS_TYPE_TOKENRING
ADDRESS_TYPE_FDDI
ADDRESS_TYPE_XNS
ADDRESS_TYPE_VINES_IP
ADDRESS_TYPE_ATM.

AddressLength
[in] Length of the destination address, in bytes.

Return Values

If the function is successful, the return value is the offset (measured in bytes) to the requested address type.

If the function is unsuccessful, the return value is minus one (-1).

Remarks

If the AddressType parameter is set to ADDRESS_TYPE_ETHERNET, the return value of the GetFrameDstAddressOffset function is always zero. The offset of an Ethernet address is always zero.

Experts and parsers can call the GetFrameDstAddressOffset function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameFromFrameHandle

The GetFrameFromFrameHandle function returns a pointer to a frame from a frame handle.

ULPFRAME WINAPI GetFrameFromFrameHandle(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to the frame.

Return Values

If the function is successful, the return value is a pointer to the frame.

If the function is unsuccessful, the return value is 0.

Remarks

The GetFrameFromFrameHandle function retrieves data that cannot be retrieved by the other helper functions that Network Monitor provides. Use the following functions whenever possible.

GetFrameDstAddressOffset
GetFrameSrcAddressOffset
GetFrameCaptureHandle
GetFrameDestAddress
GetFrameSourceAddress
GetFrameMacHeaderLength
GetFrameLength
GetFrameStoredLength
GetFrameMacType
GetFrameMacHeaderLength
GetFrameNumber
GetFrameTimeStamp

Experts and parsers can call the GetFrameFromFrameHandle function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameLength

The GetFrameLength function returns the length of the frame.

DWORD WINAPI GetFrameLength(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to a frame.

Return Values

If the function is successful, the return value is the length of the frame — in bytes.

If the function is unsuccessful, the return value is zero.

Remarks

Experts and parsers can call the GetFrameLength function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameMacHeaderLength

The GetFrameMacHeaderLength function returns the length, in bytes, of the MAC header of the frame.

DWORD WINAPI GetFrameMacHeaderLength(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to the frame.

Return Values

If the function is successful, the return value is the length — in bytes — of the MAC header.

If the function is not successful, or an unknown MAC type is encountered, the return value is zero.

Remarks

Experts and parsers can call the GetFrameMacHeaderLength function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameMacType

The GetFrameMacType function returns the MAC type of the frame.

DWORD WINAPI GetFrameMacType(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to the frame.

Return Values

The function returns the MAC type of the frame, which can have one of the following values.

  • MAC_TYPE_UNKNOWN
  • MAC_TYPE_ETHERNET
  • MAC_TYPE_TOKENRING
  • MAC_TYPE_FDDI

Remarks

Experts and parsers can call the GetFrameMacType function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameNumber

The GetFrameNumber function returns the number of a frame.

DWORD WINAPI GetFrameNumber(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to the frame.

Return Values

If the function is successful, the return value is a zero-based frame number.

If the function is not successful, the return value is minus one (-1).

Remarks

Experts and parsers can call the GetFrameNumber function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameRecognizeData

The GetFrameRecognizeData function returns a table of RECOGNIZEDATA structures. Each of these structures contains a protocol identifier and an offset that points to the start of the specified protocol in the data.

LPRECOGNIZEDATATABLE WINAPI GetFrameRecognizeData(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to a frame.

Return Values

If the function is successful, the return value is a pointer to a RECOGNIZEDATATABLE structure.

If the function is not successful, the return value is zero.

Remarks

Experts and parsers can call the GetFrameRecognizeData function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameSrcAddressOffset

The GetFrameSrcAddressOffset function returns the offset of the frame's source address.

DWORD WINAPI GetFrameSrcAddressOffset(
  HFRAME hFrame,
  DWORD AddressType,
  LPDWORD AddressLength
);

Parameters

hFrame
Handle to the frame.
AddressType
Source address type. The parameter value can be one of the following:
  • ADDRESS_TYPE_ETHERNET
  • ADDRESS_TYPE_IP
  • ADDRESS_TYPE_IPX
  • ADDRESS_TYPE_TOKENRING
  • ADDRESS_TYPE_FDDI
  • ADDRESS_TYPE_XNS
  • ADDRESS_TYPE_VINES_IP
  • ADDRESS_TYPE_ATM
AddressLength
Pointer to a DWORD, which on return, contains the length of the address, in bytes.

Return Values

If the function is successful, the return value is the offset to the source address.

If the function is unsuccessful, the return value is minus one (-1).

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameStoredLength

The GetFrameStoredLength function returns the length of the frame.

DWORD WINAPI GetFrameStoredLength(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to the frame.

Return Values

If the function is successful, the return value is the length of the frame as stored.

If the function is unsuccessful, the return value is zero.

Remarks

Experts and parsers can call the GetFrameStoredLength function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

GetFrameLength


GetFrameTimeStamp

The GetFrameTimeStamp function returns the time stamp of a given frame.

__int64 WINAPI GetFrameTimeStamp(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to the frame.

Return Values

If the function is successful, the return value is the time stamp of the frame — in microseconds.

If the function is unsuccessful, the return value is minus one (-1).

Remarks

The GetFrameTimeStamp function returns a time stamp that shows the elapsed time between the start of the capture process, and the recording of the frame.

Experts and parsers can call the GetFrameTimeStamp function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetPreviousProtocolOffsetByName

The GetPreviousProtocolOffsetByName function returns the previous instance of a given protocol.

DWORD WINAPI GetPreviousProtocolOffsetByName(
  HFRAME hFrame,
  DWORD dwStartOffset,
  LPSTR szProtocolName,
  DWORD *pdwPreviousOffset
);

Parameters

hFrame
[in] Handle to the frame.
dwStartOffset
[in] Offset in the frame.
szProtocolName
[in] Name of the protocol you want to search for.
pdwPreviousOffset
[out] Pointer to a DWORD that contains the offset to the previous protocol (if the function succeeds).

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is NMERR_PROTOCOL_NOT_FOUND.

Remarks

Experts and parsers can call the GetPreviousProtocolOffsetByName.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetProperty

The GetProperty function returns a handle to a given property.

HPROPERTY WINAPI GetProperty(
  HPROTOCOL hProtocol,
  LPSTR PropertyName
);

Parameters

hProtocol
[in] Handle to the protocol.
PropertyName
[in] Name of the property (for example, Checksum).

Return Values

If the function is successful, the return value is the handle to the property.

If the function is unsuccessful, the return value is NULL.

Remarks

The GetProperty function can be used to obtain the property handle needed to locate instances of the property. The functions used to locate property instances are FindPropertyInstance (which locates the first instance) and FindPropertyInstanceRestart (which locates the next instance).

Experts and parsers can call the GetProperty function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

FindPropertyInstance, FindPropertyInstanceRestart


GetPropertyInfo

The GetPropertyInfo function returns a pointer to the property information of a given protocol.

LPPROPERTYINFO WINAPI GetPropertyInfo(
  HPROPERTY hProperty
);

Parameters

hProperty
[in] Handle to a property.

Return Values

If the function is successful, the return value is a pointer to the property.

If the function is unsuccessful, the return value is NULL.

Remarks

Experts and parsers can call the GetPropertyInfo function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetPropertyText

The GetPropertyText function returns a pointer to the property text.

LPSTR WINAPI GetPropertyText(
  HFRAME hFrame,
  LPPROPERTYINST lpPI,
  LPSTR szBuffer,
  DWORD BufferSize
);

Parameters

hFrame
[in] Handle to the frame.
lpPI
[in] Pointer to a property instance.
szBuffer
[in] Pointer to the property text string.
BufferSize
[in] Size of the text string buffer.

Return Values

If the function is successful, the return value is a pointer to the property text.

If the function is unsuccessful, the return value is NULL.

Remarks

Experts and parsers can call the GetPropertyText function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetProtocolFromName

The GetProtocolFromName function returns a handle to a protocol of a given name.

HPROTOCOL WINAPI GetProtocolFromName(
  LPSTR ProtocolName
);

Parameters

ProtocolName
[in] Protocol name (for example, IP).

Return Values

If the function is successful, the return value is a protocol handle.

If the function is unsuccessful, the return value is NULL.

Remarks

Experts and parsers can call the GetProtocolFromName function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetProtocolInfo

The GetProtocolInfo function returns a pointer to a protocol information value.

LPPROTOCOLINFO WINAPI GetProtocolInfo(
  HPROTOCOL hProtocol
);

Parameters

hProtocol
[in] Handle to a protocol.

Return Values

If the function is successful, the return value is a pointer to the protocol information value.

If the function is unsuccessful, the return value is NULL.

Remarks

Experts and parsers can call the GetProtocolInfo function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetProtocolStartOffsetHandle

The GetProtocolStartOffsetHandle function returns the frame offset of a given protocol.

DWORD WINAPI GetProtocolStartOffsetHandle(
  HFRAME hFrame,
  HPROTOCOL hProtocol
);

Parameters

hFrame
[in] Handle to a frame.
hProtocol
[in] Handle to a protocol.

Return Values

If the function is successful, the return value is the offset of the frame — measured in bytes.

If the function is unsuccessful, the return value is one (1).

Remarks

Experts and parsers can call the GetProtocolStartOffsetHandle function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


MacTypeToAddressType

The MacTypeToAddressType function converts a given MAC type to an address type.

DWORD WINAPI MacTypeToAddressType(
  DWORD MacType
);

Parameters

MacType
[in] MAC type to be converted. Specify one of the following values:

MAC_TYPE_ETHERNET
MAC_TYPE_TOKENRING
MAC_TYPE_FDDI

Return Values

If the function is successful, the return value is one of the following address types.

ADDRESS_TYPE_ETHERNET
ADDRESS_TYPE_TOKENRING
ADDRESS_TYPE_FDDI

If the function is unsuccessful, the MAC type is unknown, the return value is -1.

Remarks

Experts and parsers can call the MacTypeToAddressType function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ModifyFrame

The ModifyFrame function alters an existing frame with new data.

HFRAME WINAPI ModifyFrame(
  HCAPTURE hCapture,
  DWORD FrameNumber,
  LPBYTE FrameData,
  DWORD FrameLength,
  __int64 TimeStamp
);

Parameters

hCapture
[in] Handle to the capture. For information about obtaining the capture handle, see the Remarks section of this ModifyFrame topic.
FrameNumber
[in] Frame index number.
FrameData
[in] Pointer to an array of bytes that contain the new frame data.
FrameLength
[in] Length of the new data, in bytes.
TimeStamp
[out] Time stamp indicating when the frame was modified.

Return Values

If the function is successful, the return value is a handle to a new frame.

If the function is unsuccessful, the return value is NULL.

Remarks

If the call is successful, the ModifyFrame function destroys the original frame.

Experts and parsers can call the ModifyFrame function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


Expert Functions, Structures, and Enumerations

This Expert Functions, Structures, and Enumerations section contains information about the functions, structures, and enumerations that only experts can use. Topics in this section include the following:

  • Expert DLL Export Functions

    These topics describe the functions that must be exported by expert DLLs.

  • Expert Functions

    These topics describe the helper functions that are called by experts.

  • Expert Structures

    These topics describe the structures that are used by expert functions.

  • Expert Enumerations

    These topics describe the enumerations used by expert structures and functions.


Expert DLL Export Functions

The following functions are the entry points for expert DLLs and for calls from the operating system and Network Monitor.

Function | Description
DllMain Expert | Indicates that the expert DLL has been loaded or unloaded. When a process loads or unloads the DLL, the operating system calls the DllMain function.
Register Expert | Determines basic information about the expert within the DLL. Network Monitor calls the Register function.
Configure | Configures the expert within the DLL. Network Monitor calls the Configure function.
Run | Starts the expert within the DLL. Network Monitor calls the Run function.

Network Monitor also provides structures, enumerations, and helper functions that the expert can call.

For information about | See
Helper functions that can be called by experts and parsers | Expert and Parser Common Functions
Helper functions that are called only by experts | Expert Functions
Structures that are used by expert functions | Expert Structures
Enumerations used by expert structures and functions | Expert Enumerations


DllMain Expert

The expert implements the DllMain function. The operating system calls DllMain to obtain a handle to an instance of the expert.

BOOL WINAPI DllMain(
  HINSTANCE hInstance,
  ULONG ulReason,
  LPVOID Reserved
);

Parameters

hInstance
[out] Handle to an instance of the expert.

If the expert uses the Network Monitor user interface, the hInstance value must be stored in a global variable. This approach is necessary only when the value of ulReason is DLL_PROCESS_ATTACH.

ulReason
[in] Indicator of why the function was called. For a list of all possible flags set by the operating system, see DLLMain.

A value of DLL_PROCESS_ATTACH, (which applies when the DLL is first loaded) indicates that the expert should save the hInstance value in a global variable. With any other value, all calls to the DllMain function can be ignored.

Reserved
Parameter that is not in use.

Return Values

If the function is successful, the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

The operating system calls the DllMain expert function when a process loads or unloads the expert DLL. The DllMain expert function must be exported only if the expert has a user interface for viewing either configuration or results, and then only to return the proper hInstance value.

The DllMain expert function is based on the dynamic link library DllMain function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.


Register Expert

The expert must implement the Register expert function. Network Monitor calls the Register expert function to obtain information about the expert.

BOOL WINAPI Register(
  OUT PEXPERTENUMINFO pExpertInfo
);

Parameters

pExpertInfo
[in] Pointer to an EXPERTENUMINFO structure that Network Monitor allocates. The expert fills-in the structure with all requested information.

Return Values

If the function is successful, the return value is TRUE, and the function returns the requested information.

If the function is unsuccessful, the return value is FALSE.

Remarks

The Version member of the EXPERTENUMINFO structure must be zero.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.


Configure

The expert must implement the Configure function. Network Monitor calls the Configure function to configure the expert within the expert DLL.

When the call is received, the expert displays a dialog box that allows the user to change any configurable item.

BOOL WINAPI Configure(
  HEXPERTKEY hExpertKey,
  PEXPERTCONFIG *ppConfig,
  PEXPERTSTARTUPINFO pExpertStartupInfo,
  DWORD StartupFlags,
  HWND hWnd
);

Parameters

hExpertKey
[in] Unique expert identifier.

The unique identifier is passed back on all expert-specific Network Monitor functions. Note that the identifier may not be the same expert key as the one passed to the Run function. Do not store the expert key from the Configure call.

ppConfig
[in, out] Pointer to a pointer to an EXPERTCONFIG structure upon entry.

After a successful exit, the referenced EXPERTCONFIG structure contains the new configuration information.

pExpertStartupInfo
[in] Pointer to the capture element that had focus when the expert started.
StartupFlags
[in] Flags that indicate how the expert should use the pExpertStartupInfo parameter. The only flag defined is EXPERT_STARTUP_FLAG_USE_STARTUP_DATA_OVER_CONFIG_DATA. The flag indicates that the expert will use the pExpertStartupInfo parameter rather than the ppConfig parameter that passed in. Typically, you set the flag when you start the expert from a context menu.
hWnd
[in] Handle to the parent window. Use the handle to open a dialog box.

Return Values

If the function is successful (that is, if a current configuration exists), the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

Network Monitor calls the Configure function with the current configuration of the expert, if one exists. The expert displays a dialog box, with which you can change any configurable item.

When ppConfig is passed-in and Network Monitor does not have a configuration stored for the specified expert, the *ppConfig parameter value can be NULL. In this case, the Configure function assumes hard-coded default values (or, uses the startup information) to open the dialog box.

The *ppConfig can also be NULL iwhen the Configure function returns, and a NULL was passed-in. This situation occurs when Network Monitor does not have a stored default, and the user presses Cancel.

The beginning of the EXPERTCONFIG data structure includes a Private section that stores the structure size information. The size of the EXPERTCONFIG structure should include the reserved DWORD length that appears at the beginning of the structure. For example, if your configuration data needs 20 bytes of storage space, you must allocate 24 bytes to store the data. If a NULL *ppConfig value is passed-in, the Configure function calls the ExpertAllocMemory function to allocate a new configuration that is the correct size. If the configuration passed-in is not big enough to hold the expert data, the expert should call the ExpertReallocMemory function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.


Run

The expert must implement the Run function. Network Monitor calls the Run function to start the expert within the expert DLL.

BOOL WINAPI Run(
  HEXPERTKEY hExpertKey,
  PEXPERTCONFIG pConfig,
  PEXPERTSTARTUPINFO pExpertStartupInfo,
  DWORD StartupFlags,
  HWND hWndParent
);

Parameters

hExpertKey
[in] Unique identifier of the expert that is passed back to all expert-specific Network Monitor functions.

Note The hExpertKey identifier may pass an expert key that is different from the expert key that the Configure function passes.

pConfig
[in] Pointer to the existing configuration. The pConfig parameter may be NULL which means that the expert can run with hard-coded defaults, or startup information that the pExpertStartupInfo parameter references.
pExpertStartupInfo
[in] Pointer to the capture element that has focus when the expert starts.
StartupFlags
[in] Indicator for how the expert should use the pExpertStartupInfo parameter.

The only flag defined is:

EXPERT_STARTUP_FLAG_USE_STARTUP_DATA_OVER_CONFIG_DATA.
This flag indicates that the expert uses the pExpertStartupInfo parameter, and does not use the pConfig parameter. Typically, you can set this flag when the expert can start from a right-mouse click. If the flag is not set, the following two things can occur: either the expert does not start from a right-mouse click, or the expert starts from a right-mouse click, and then the user configures it.
hWndParent
[in] The hWnd parameter of the parent (usually the Network Monitor user interface).

Return Values

If the function is successful (that is, if the expert starts), the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

When running, the expert loops through the frames in the capture file and either generates a report or creates events that show problems.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.


Expert Functions

The following helper functions can only be called by experts that export the Run or Configure function.

Function | Description
ExpertGetFrame | Retrieves a given frame from the capture.
ExpertIndicateStatus | Indicates the percentage of completion of the expert's analysis of capture.
ExpertGetStartupInfo | Retrieves the startup information for the expert.
ExpertMemorySize | Retrieves the size of memory allocated by a call to the ExpertAllocMemory function.
ExpertSubmitEvent | Indicates a problem and retrieves information about the problem if one exists.
ExpertAllocMemory | Allocates memory for the expert.
ExpertReallocMemory | Changes the size of the memory allocated by the ExpertAllocMemory function.
ExpertFreeMemory | Frees memory allocated by the expert.

For information about export functions, helper functions that can be called by experts and parsers, structures, and enumerations, see the following topics:

For information about | See
Functions that are exported by experts | Expert DLL Export Functions
Structures that are used by expert functions | Expert Structures
Enumerations used by expert structures and functions | Expert Enumerations
Common helper functions that can be called by experts and parsers | Expert and Parser Common Functions


ExpertGetFrame

The ExpertGetFrame function returns the requested frame from a loaded capture.

DWORD WINAPI ExpertGetFrame(
  HEXPERTKEY hExpertKey,
  DWORD Direction,
  DWORD RequestFlags,
  DWORD RequestedFrameNumber,
  HFILTER hFilter,
  LPEXPERTFRAMEDESCRIPTOR pEFrameDescriptor
);

Parameters

hExpertKey
[in] Unique expert identifier. Network Monitor passes the hExpertKey identifier to the expert when it calls the Run function.
Direction
[in] Value that identifies how Network Monitor searches for the frame.
GET_SPECIFIED_FRAME
Return the requested frame.
GET_FRAME_NEXT_FORWARD
Return the next frame.
GET_FRAME_NEXT_BACKWARD
Return the previous frame.
RequestFlags
[in] Flags that specify how Network Monitor should handle the request. Specify one or more of the following flags.
FLAGS_DEFER_TO_UI_FILTER
Before applying the display filter parameter of the expert which is specified in hFilter, apply the display filter that Network Monitor is using when the expert starts.
FLAGS_ATTACH_PROPERTIES
The properties that all protocol parsers find with claimed sections of this frame are attached to the frame. If the flag is not set, the lpPropertyTable field of the EXPERTFRAMEDESCRIPTOR structure (returned by pEFrameDescriptor) will be set to NULL.
RequestedFrameNumber
[in] Number of the requested frame.
hFilter
[in] Handle to the expert display filter. If the expert does not have a display filter, set the parameter to NULL.
pEFrameDescriptor
[out] On return, the EXPERTFRAMEDESCRIPTOR structure that describes the frame. The expert must allocate and free the memory that this structure uses.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value indicates the reason for the failure. If the return value is NMERR_EXPERT_TERMINATE, the expert must immediately clean up and return; the user has aborted the expert run.

Remarks

If you set FLAGS_ATTACH_PROPERTIES, the call is more expensive than if you do not set the flag. If the flag is not set, a pointer points to the raw frame and to general information about the frame. If this flag is set, Network Monitor attaches all properties to the frame by calling every parser that claims a portion of the frame. This can be a very slow process.

Experts should not set the FLAGS_ATTACH_PROPERTIES flag unless the experts require the properties that parsers attach to the frame. If possible, experts should call the ExpertGetFrame function without the flag, and then extract the required information directly from the frame.

If the expert calls ExpertGetFrame without the FLAGS_ATTACH_PROPERTIES flag and requires the properties associated with that frame (an event, for example), the expert calls ExpertGetFrame with the same parameters except for the following:

Direction = EXPERT_GET_SPECIFIED_FRAME;
RequestFlags &= (~EXPERT_DEFER_TO_UI_FILTER) |
EXPERT_ATTACH_PROPERTIES;
RequestedFrameNumber= (The actual frame number you want);
hFilter = NULL;
pEFrameDescriptor = (The same one as last time).

Using the preceding code ensures that the expert gets the required frame without having to call filter code again.

You can set the hFilter parameter as an LPVOID. If it exists, the returned frame passes this filter. If the expert does not have a display filter to pass to the function (if hFilter is NULL ), then the frame returned is not filtered.

The ExpertGetFrame function can only be called by experts that implement the Run or Configure export function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ExpertIndicateStatus

The ExpertIndicateStatus function indicates the percentage of completion of the expert's analysis of the capture file.

DWORD WINAPI ExpertIndicateStatus(
  HEXPERTKEY hExpertKey,
  EXPERTSTATUSENUMERATION Status,
  DWORD SubStatus,
  const char *szText,
  long PercentDone
);

Parameters

hExpertKey
[in] Unique expert identifier. Network Monitor passes hExpertKey to the expert when it calls the Run function.
Status
[in] Current status of the analysis. Specify one of the following EXPERTSTATUSENUMERATION enumeration values.
EXPERTSTATUS_INACTIVE
The expert never started.
EXPERTSTATUS_STARTING
The expert is starting.
EXPERTSTATUS_RUNNING
The expert is running normally.
EXPERTSTATUS_PROBLEM
A problem specified in the SubStatus parameter stopped the expert.
EXPERTSTATUS_ABORTED
Network Monitor stopped the expert.
EXPERTSTATUS_DONE
The expert finished the analysis successfully.
SubStatus
[in] Extension or clarification of information provided by the Status parameter.
szText
[in] Optional text status indicator.

The parameter value may be NULL.

PercentDone
[out] Percentage of the capture data that the expert has processed.

When the expert successfully completes analysis of a capture file, the system sets the percentage to 100. Any number greater than 99 will be ignored.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is NMERR_EXPERT_TERMINATE; the expert must immediately clean up and return without completing the capture.

Remarks

The ExpertIndicateStatus function can only be called by experts that implement the Run or Configure export function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ExpertGetStartupInfo

The ExpertGetStartupInfo function retrieves the startup configuration information for the expert.

DWORD WINAPI ExpertGetStartupInfo(
   HEXPERTKEY hExpertKey,
   PEXPERTSTARTUPINFO pExpertStartupInfo
);

Parameters

hExpertKey
[in] Unique expert identifier. Network Monitor passes hExpertKey to the expert when it calls the Run function.
pExpertStartupInfo
[out] Pointer to an EXPERTSTARTUPINFO structure that contains startup information.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is NMERR.

Remarks

The ExpertGetStartupInfo function is used if the expert must determine the startup information that is used.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ExpertMemorySize

The ExpertMemorySize function returns the amount of memory allocated by the ExpertAllocMemory function.

SIZE_T WINAPI ExpertMemorySize(
  HEXPERTKEY hExpertKey,
  LPVOID pOriginalMemory
);

Parameters

hExpertKey
[in] Unique expert identifier. Network Monitor passes hExpertKey to the expert when it calls the Run function.
pOriginalMemory
[in] Pointer to the memory address of the expert allocated by ExpertAllocMemory.

Return Values

The function returns the amount of allocated memory — in bytes.

Remarks

For information on the SIZE_T data type that ExpertMemorySize returns, see Data Types.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ExpertSubmitEvent

The ExpertSubmitEvent function indicates that an event condition exists and provides a data structure that describes the condition.

DWORD WINAPI ExpertSubmitEvent(
  HEXPERTKEY hExpertKey,
  PNMEVENTDATA pExpertEvent
);

Parameters

hExpertKey
[in] Unique identifier of the expert. Network Monitor passes hExpertKey to the expert when it calls the Run function.
pExpertEvent
[in] A pointer to an NMEVENTDATA structure that describes the event condition.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value indicates the reason for the failure. If the return value is NMERR_EXPERT_TERMINATE, the expert immediately cleans up and returns.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ExpertAllocMemory

The ExpertAllocMemory function allocates memory for the expert.

LPVOID WINAPI ExpertAllocMemory(
  HEXPERTKEY hExpertKey,
  SIZE_T nBytes,
  LPDWORD pError
);

Parameters

hExpertKey
Unique expert identifier. Network Monitor passes hExpertKey to the expert when it calls the Run function.
nBytes
[in] Allocated memory, measured in bytes. For information on the SIZE_T data type, see Data Types.
pError
[out] Error indicator. If the function fails, the nBytes parameter contains the error code. If the error code is NMERR_EXPERT_TERMINATE, the expert must clean-up and return immediately.

Return Values

If the function is successful, the return value is a pointer to the allocated memory.

If the function is unsuccessful, the return value is NULL, and pError provides an error code that indicates the reason for the failure.

Remarks

It is important to note that an expert should use the Network Monitor memory allocation functions (including ExpertReallocMemory) for memory management. If your expert fails during run time, using these functions will allow Network Monitor to free the memory it has allocated.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ExpertReallocMemory

The ExpertReallocMemory function increases or decreases the amount of memory allocated by Network Monitor.

LPVOID WINAPI ExpertReallocMemory(
  HEXPERTKEY hExpertKey,
  LPVOID pOriginalMemory,
  SIZE_T nBytes,
  LPDWORD pError
);

Parameters

hExpertKey
[in] Unique identifier passed to the expert at Run or Configure.
pOriginalMemory
[in] Pointer to the memory allocated by Network Monitor. The pOriginalMemory pointer can be returned by a previous call to ExpertAllocMemory or ExpertReallocMemory.
nBytes
[in] Size of reallocated memory. For information on the SIZE_T data type see Data Types.
pError
[out] On return, an error code if the function fails. If the error code is NMERR_EXPERT_TERMINATE, the expert must clean up and return immediately.

Return Values

If the function is successful, the return value is a pointer to the allocated memory.

If the function is unsuccessful, the return value is NULL, and pError (if it is a non-NULL value) indicates the reason for the failure.

Remarks

It is important to note that an expert should use the Network Monitor memory allocation functions for memory management. If your expert fails during run time, using these functions will allow Network Monitor to free the memory it has allocated.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ExpertFreeMemory

The ExpertFreeMemory function frees memory acquired by calls to the ExpertAllocMemory and ExpertReallocMemory functions.

SIZE_T WINAPI ExpertFreeMemory(
  HEXPERTKEY hExpertKey,
  LPVOID pMemory
);

Parameters

hExpertKey
Unique expert identifier. Network Monitor passes hExpertKey to the expert when it calls the Run function.
pMemory
[in] Pointer to the memory that Network Monitor allocates. The pMemory pointer can be returned by a previous call to ExpertAllocMemory or ExpertReallocMemory.

Return Values

If the function is successful. the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value indicates the reason for the failure. If the return value is NMERR_EXPERT_TERMINATE, the expert immediately cleans up and returns.

Remarks

It is important to note that an expert should use the Network Monitor memory allocation functions for memory management. If your expert fails during run time, using these functions will allow Network Monitor to free the memory it has allocated.

For information on the SIZE_T data type that ExpertFreeMemory returns, see Data Types.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


Expert Structures

Expert helper functions provided by Network Monitor and common helper functions use the structures described in the following table.

Structure | Description
CONFIGUREDEXPERT | Associates an expert DLL with its configuration.
EXPERTCONFIG | Provides raw configuration data.
EXPERTENUMINFO | Provides information about the expert DLL. Network Monitor uses the information.
EXPERTFRAMEDESCRIPTOR | Provides information about a frame.
EXPERTSTARTUPINFO | Provides startup information about the expert.
EXPERTSTATUS | Provides the current status of a running expert.
FILTEROBJECT | Defines the display filter characteristics for an expert.
GROUPINFO | Associates a group name and handle.
NMEVENTDATA | Provides information about a line displayed in the expert viewer.
JTYPE | Represents a string that contains a justification.
NMCOLUMNINFO | Provides information that defines a column in the Event Viewer.
NMCOLUMNVARIANT | Provides a container for all possible data inserted into a column on one line in the Event Viewer.
NMCOLUMNTYPE | The entry point in the variant that indicates which element of the union to use, and how to format it.

Network Monitor also provides export functions (helper functions that the expert can call) and enumerations.

For information about | See
Export Functions that provide entry points to your expert DLL. | Expert DLL Export Functions
Helper functions that can be called by experts and parsers. | Expert and Parser Common Functions
Helper functions that are called only by experts. | Expert Functions
Enumerations used by expert structures and functions. | Expert Enumerations


CONFIGUREDEXPERT

The CONFIGUREDEXPERT structure associates an expert with its configuration data.

typedef struct
{
  HEXPERT hExpert;
  DWORD StartupFlags;
  PEXPERTCONFIG pConfig;
} CONFIGUREDEXPERT;
typedef CONFIGUREDEXPERT * PCONFIGUREDEXPERT;

Members

hExpert
Handle to an expert.
StartupFlags
Startup flag values of the expert.
pConfig
Pointer to an EXPERTCONFIG structure.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


EXPERTCONFIG

The EXPERTCONFIG structure contains the configuration data of the expert. The expert overlays the RawConfigData member with an expert-specific structure in order to make sense of it.

typedef struct
{
  DWORD    RawConfigLength;
  BYTE     RawConfigData[0];
} EXPERTCONFIG;
typedef EXPERTCONFIG* PEXPERTCONFIG;

Members

RawConfigLength
Total length of the structure, including the four bytes used for the member. Network Monitor uses the value when the structure is saved-to and read-from a disk drive.
RawConfigData
Configuration data. The expert must add the configuration data. For example, suppose that you had a data structure that looked like this.
typedef struct
{
    DWORD       RawConfigLength;   // Overlay of structure
    DWORD       PickNumEvents;
    DWORD       NumEventsSpecific;
    DWORD       PickSpeedThroughCapture;
    DWORD       PickStartup;
    DWORD       PickAttachProperties;
} TESTEXPERTCONFIG;
typedef TESTEXPERTCONFIG* LPTESTEXPERTCONFIG;

Note that RawConfigLength ensures that the overlay works correctly. When you use the data, your code might look like this:

BOOL WINAPI Configure(
    HEXPERTKEY ExpertKey,
    PEXPERTCONFIG * ppConfig,
    PEXPERTSTARTUPINFO pStartupInfo,
    DWORD StartupFlags,
    HWND hWnd
)
{
    LPTESTEXPERTCONFIG  lpConfig;

    //...
    lpConfig = (LPTESTEXPERTCONFIG)(*ppConfig);
    //...
}

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


EXPERTENUMINFO

The EXPERTENUMINFO structure provides information about the expert. Network Monitor allocates memory for the structure, and passes it to the expert when it calls the Register Expert function. When the expert receives the structure, it must then fill-in all the information that Network Monitor requests.

typedef struct
{
  char  szName[EXPERTSTRINGLENGTH];
  char  szVendor[EXPERTSTRINGLENGTH];
  char  szDescription[EXPERTSTRINGLENGTH];
  DWORD  Version;
  DWORD  Flags;
  HEXPERT  hExpert;
  char  szDllName[MAX_PATH];  // Private
  HINSTANCE  hModule;  // Private
  PEXPERTREGISTERPROC  pRegisterProc;  // Private
  PEXPERTCONFIGPROC  pConfigProc;  // Private
  PEXPERTRUNPROC  pRunProc;  // Private
} EXPERTENUMINFO;
typedef EXPERTENUMINFO * PEXPERTENUMINFO;

Members

szName
Name of the expert.
szVendor
Name of the vendor that creates the expert.
szDescription
Description of the expert. The value of the szDescription member may be NULL. If the name is too long, it is truncated in the default viewer configuration.
Version
The value must be zero.
Flags
The following flags describe the expert.
EXPERT_ENUM_FLAG_CONFIGURABLE
The expert supports calls to the Configure method.
EXPERT_ENUM_FLAG_VIEWER_PRIVATE
The expert requires a private (non-shared) Event Viewer.
EXPERT_ENUM_FLAG_NO_VIEWER
The expert does not send event notifications.
EXPERT_ENUM_FLAG_ADD_ME_TO_RMC_IN_SUMMARY
When the focus is in the summary pane, the expert appears on the context menu.
EXPERT_ENUM_FLAG_ADD_ME_TO_RMC_IN_DETAIL
When the focus is in the detail pane, the expert appears on the context menu.
hExpert
Handle to the expert. When the EXPERTENUMINFO structure is used to register an expert, the parameter is ignored.
szDllName[MAX_PATH]
Private member; do not use.
hModule
Private member; do not use.
pRegisterProc
Private member; do not use.
pConfigProc
Private member; do not use.
pRunProc
Private member; do not use.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


EXPERTFRAMEDESCRIPTOR

The EXPERTFRAMEDESCRIPTOR structure contains information about a frame. When the expert calls the ExpertGetFrame function successfully, Network Monitor passes the EXPERTFRAMEDESCRIPTOR structure back to the expert.

typedef struct
{
  DWORD  FrameNumber;
  HFRAME  hFrame;
  ULPFRAME  pFrame;
  LPRECOGNIZEDATATABLE  lpRecognizeDataTable;
  LPPROPERTYTABLE  lpPropertyTable;
} EXPERTFRAMEDESCRIPTOR;
typedef EXPERTFRAMEDESCRIPTOR *LPEXPERTFRAMEDESCRIPTOR;

Members

FrameNumber
Number of a specified frame.
hFrame
Handle to a frame.
pFrame
Pointer to a raw frame.
lpRecognizeDataTable
Table that indicates where each parser identifies the start of the data.
lpPropertyTable
Table of frame properties that the parser identifies.
  • If the expert specifies FLAGS_ATTACH_PROPERTIES when calling ExpertGetFrame, then the szPropertyText member in each PROPERTYINST structure is NULL.
  • If the expert does not specify FLAGS_ATTACH_PROPERTIES when calling the ExpertGetFrame function, then the lpPropertyTable member is NULL on return.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


EXPERTSTARTUPINFO

The EXPERTSTARTUPINFO structure contains information that describes an expert when it starts up.

typedef struct _EXPERTSTARTUPINFO
{
  DWORD  Flags;
  HCAPTURE   hCapture;
  char  szCaptureFile[MAX_PATH];
  DWORD  dwFrameNumber;
  HPROTOCOL  hProtocol;
  LPPROPERTYINST  lpPropertyInst;
  struct
  {
    BYTE    BitNumber;
    BOOL    bOn;
  } sBitfield;
} EXPERTSTARTUPINFO;
typedef struct _EXPERTSTARTUPINFO *PEXPERTSTARTUPINFO;

Members

Flags
Flags that describe the expert.
hCapture
Handle to a capture.
szCaptureFile[MAX_PATH]
Name of the capture file.
dwFrameNumber
Frame number.
hProtocol
Handle to the protocol.
lpPropertyInst
Pointer to a PROPERTYINST structure.
BitNumber
Used only if the DataQualifier member of the PROPERTYINST structure is set to PROP_QUAL_FLAGS.
bOn
Used only if the DataQualifier member of the PROPERTYINST structure is set to PROP_QUAL_FLAGS.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


EXPERTSTATUS

The EXPERTSTATUS structure indicates the current status of a running expert.

typedef struct
{
  EXPERTSTATUSENUMERATION   Status;
  DWORD   SubStatus;
  DWORD   PercentDone;
  DWORD   Frame;
  char    szStatusText[EXPERTSTRINGLENGTH];
} EXPERTSTATUS;
typedef EXPERTSTATUS * PEXPERTSTATUS;

Members

Status
Current expert status value defined by the EXPERTSTATUSENUMERATION enumeration.
SubStatus
Sub-status value.
PercentDone
Percentage completion of the expert's analysis of network data.
Frame
Frame number.
szStatusText[EXPERTSTRINGLENGTH]
Text that describes the expert's status.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


FILTEROBJECT

The FILTEROBJECT structure defines a single object of a display filter. The FilterAddObject function uses FILTEROBJECT to build a display filter.

typedef struct _FILTEROBJECT{
  FILTERACTIONTYPE  Action;
  HPROPERTY  hProperty;
  union{
    VALUETYPE  Value;
    HPROTOCOL  hProtocol;
    LPVOID   lpArray;
    LPPROTOCOLTABLETYPE lpProtocolTable;
    LPADDRESS  lpAddress;
    ULPLARGEINT  lpLargeInt;
    ULPTIME  lpTime;
    LPOBJECT_IDENTIFIER lpOID;
  };
  union
  {
    WORD  ByteCount;
    WORD  ByteOffset;
  };
  struct _FILTEROBJECT *pNext;
} FILTEROBJECT;

typedef FILTEROBJECT * LPFILTEROBJECT;

Members

Action
Flag that specifies the FILTEROBJECT action. A flag can specify a property, value, or operator.

The following table lists Action member property flags.
Property Action | Meaning
FILTERACTION_PROPERTY | Contains this property.
FILTERACTION_PROPERTYEXIST | Indicates that a filter action property is already defined.

The following table lists Action member value flags.
Value Action | Meaning
FILTERACTION_VALUE | Contains this value.
FILTERACTION_STRING | Contains this string.
FILTERACTION_ARRAY | Contains this array.
FILTERACTION_CONTAINSNC | Indicates that a property contains a case-insensitive substring.
FILTERACTION_CONTAINS | Indicates that a property contains a case sensitive substring.
FILTERACTION_ADDRESS | Contains the MAC address.
FILTERACTION_ADDRESSANY | Matches any MAC address.
FILTERACTION_FROM | Indicates the From MAC address.
FILTERACTION_TO | Indicates the To MAC address.
FILTERACTION_FROMTO | Indicates a From/To pairing of MAC addresses.
FILTERACTION_LARGEINT | Contains a large integer.
FILTERACTION_TIME | Contains a SYSTEMTIME structure.
FILTERACTION_ADDR_ETHER | Contains an Ethernet MAC address.
FILTERACTION_ADDR_TOKEN | Contains a token ring MAC address.
FILTERACTION_ADDR_FDDI | Contains a FDDI MAC address.
FILTERACTION_ADDR_IPX | Contains an IPX MAC address.
FILTERACTION_ADDR_IP | Contains an IP MAC address.
FILTERACTION_OID | Contains an Object Identifier (OID).

The following table lists Action member operator flags.
Operator Action | Meaning
FILTERACTION_INVALID | Indicates an invalid filter action.
FILTERACTION_AND | Indicates a logical AND statement.
FILTERACTION_OR | Indicates a logical OR statement.
FILTERACTION_XOR | Indicates a logical exclusive OR (XOR) statement.
FILTERACTION_NOT | Indicates a logical NOT statement.
FILTERACTION_EQUALNC | Filter action is equal and case insensitive.
FILTERACTION_EQUAL | Filter action is equal and case sensitive.
FILTERACTION_NOTEQUALNC | Logical NOT statement is equal and case insensitive.
FILTERACTION_NOTEQUAL | Logical NOT statement is equal and is case sensitive.
FILTERACTION_GREATERNC | Filter action is greater than (>) and case insensitive.
FILTERACTION_GREATER | Filter action is greater than (>) and case sensitive.
FILTERACTION_LESSNC | Filter action is less than (<) and case insensitive.
FILTERACTION_LESS | Filter action is less than (<) and case sensitive.
FILTERACTION_GREATEREQUALNC | Filter action is greater than or equal to (>=) and case insensitive.
FILTERACTION_GREATEREQUAL | Filter action is greater than or equal to (>=) and case sensitive.
FILTERACTION_LESSEQUALNC | Filter action is less than or equal to (<=) and case insensitive.
FILTERACTION_LESSEQUAL | Filter action is less than or equal to (<=) and is case sensitive.
FILTERACTION_PLUS | Add operator (+).
FILTERACTION_MINUS | Subtract operator (-).
FILTERACTION_AREBITSON | Indicates BIT-wise operation.
FILTERACTION_AREBITSOFF | Indicates non-BIT-wise operation.
FILTERACTION_PROTOCOLSEXIST | Indicates that the selected protocols exist.
FILTERACTION_PROTOCOLEXIST | Indicates that the selected protocol exists.
FILTERACTION_ARRAYEQUAL | Indicates that array contents are equal. The flag must be used with a FILTERACTION_ARRAY structure.
FILTERACTION_DEREFPROPERTY | Describes a pattern match at an offset (in bytes), from the protocol.
FILTERACTION_OID_CONTAINS | Evaluates a substring within an object identifier. The action must be used with the FILTERACTION_OID structure.
FILTERACTION_OID_BEGINS_WITH | Evaluates a substring that begins an object identifier. The flag must be used with FILTERACTION_OID.
FILTERACTION_OID_ENDS_WITH | Evaluates a substring that ends an object identifier. The flag must be used with FILTERACTION_OID.
FILTERACTION_ADDR_VINES | Contains a Vines MAC address.
FILTERACTION_EXPRESSION | Contains an action expression.
FILTERACTION_BOOL | Contains a BOOL data type.
FILTER_DIRECTION_NEXT | Controls sequential direction (Next frame) within a capture file.
FILTER_DIRECTION_PREV | Controls sequential direction (Previous frame) within a capture file.

hProperty
Handle to a property key.
Value
Value of an object.
hProtocol
Handle to display filter protocol.
lpArray
Pointer to an array.
lpProtocolTable
Pointer to a protocol list designed to test the existence of protocol in a frame.
lpAddress
Pointer to the kernel type address. For example, MAC or IP.
lpLargeInt
Double DWORD used in Windows NT/Windows 2000 applications.
lpTime
Pointer to a SYSTEMTIME structure.
lpOID
Pointer to the OBJECT_IDENTIFIER (OID) structure.
ByteCount
Number of bytes in the frame.
ByteOffset
Offset byte value of the FILTEROBJECT structure used to compare arrays.
pNext
Reserved.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Filter.h.


GROUPINFO

The GROUPINFO structure associates a group name and its handle.

typedef struct {
  char  szGroupName[EXPERTGROUPNAMELENGTH+1];
  HGROUP  hGroup;
} GROUPINFO;
typedef GROUPINFO * PGROUPINFO;

Members

szGroupName[EXPERTGROUPNAMELENGTH+1]
Incremented value of an array in the GROUPNAME structure.
hGroup
Handle to a group.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


NMEVENTDATA

The NMEVENTDATA structure contains information about an event condition that is passed to Network Monitor to insert a line in the expert viewer. You can also use the NMEVENTDATA structure to insert a line in a monitor expert viewer.

typedef struct
{
  BYTE     Version;
  DWORD    EventIdent;
  DWORD    Flags;
  DWORD    Severity;
  BYTE     NumColumns;
  LPSTR    szSourceName;
  LPSTR    szEventName;
  LPSTR    szDescription;
  LPSTR    szMachine;
  JTYPE    Justification;
  LPSTR    szUrl;
  SYSTEMTIME SysTime;
  NMCOLUMNINFO Column[0];
} NMEVENTDATA;
typedef NMEVENTDATA* PNMEVENTDATA;

Members

Version
Version number of the NMEVENDATA structure. The version number must be zero. Future versions of Network Monitor may support a higher version number.
EventIdent
Identifier of the event. EventIdent is unique to each expert, and references an event reference page.
Flags
A set of flags that describes who sends the event data, and how the event is displayed.
EVENT_FLAG_EXPERT
The event came from an expert.
NMEVENTFLAG_DO_NOT_DISPLAY_SEVERITY
Do not display the severity level for the event.
NMEVENTFLAG_DO_NOT_DISPLAY_SOURCE
Do not display the source name for the event.
NMEVENTFLAG_DO_NOT_DISPLAY_EVENT_NAME
Do not display the event name for the event.
NMEVENTFLAG_DO_NOT_DISPLAY_DESCRIPTION
Do not display the description for the event.
NMEVENTFLAG_DO_NOT_DISPLAY_MACHINE
Do not display the machine name for the event.
NMEVENTFLAG_DO_NOT_DISPLAY_TIME
Do not display the time for the event
NMEVENTFLAG_DO_NOT_DISPLAY_FIXED_COLUMNS
Do not display the Severity, Source, Event Name, Description, Machine, or Time columns. This is not a single flag, but it is a union of the previous six flags.
Severity
Severity level of the event. The severity level can have one of the following values:

NMEVENT_SEVERITY_INFORMATIONAL
NMEVENT_SEVERITY_WARNING
NMEVENT_SEVERITY_STRONG_WARNING
NMEVENT_SEVERITY_ERROR
NMEVENT_SEVERITY_SEVERE_ERROR
NMEVENT_SEVERITY_CRITICAL_ERROR

NumColumns
Number of columns designated in the current structure.
szSourceName
Name of the expert that is displayed.
szEventName
Name of the event that is displayed.
szDescription
Description of the event that is displayed.
szMachine
Name of the machine that generates the monitor event. The szMachine member is usually used only by monitors; normally, experts leave the entry value NULL.
Justification
Information displayed in the second window of the Event Viewer. The Justification member may be NULL. If it is NULL, the second window is not be visible.
szUrl
Reserved; this member must be NULL.
SysTime
Time at which the event condition occurs. The time is measured relative to the beginning of the capture.
Column[0]
Table of column structures that appears in the top pane of the Event Viewer.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Event.h.


JTYPE

The JTYPE structure is a string that contains the justification.

typedef LPBYTE JTYPE

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Event.h.


NMCOLUMNINFO

The NMCOLUMNINFO structure defines one column in the top pane of the Event Viewer.

typedef struct
{
  LPSTR  szColumnName;
  NMCOLUMNVARIANT   VariantData;
} EVENTCOLUMNINFO;

Members

szColumnName
Displayable name of a specific column. If the name is too long, it will not be completely visible in the default Event Viewer configuration.
VariantData
The data inserted into the column.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Event.h.


NMCOLUMNVARIANT

The NMCOLUMNVARIANT structure provides a line in the top pane of the Event Viewer that serves as a container for all possible data inserted into a column.

typedef struct
{
  NMCOLUMNTYPE Type;
  union
  {
      BYTE    Uint8Val;
      char    Sint8Val;
      WORD    Uint16Val;
      short   Sint16Val;
      DWORD   Uint32Val;
      LONG    Sint32Val;
      DOUBLE  Float64Val;
      DWORD   FrameVal;
      BOOL    YesNoVal;
      BOOL    OnOffVal;
      BOOL    TrueFalseVal;
      BYTE     MACAddrVal[MAC_ADDRESS_SIZE];
      IPX_ADDRESS IPXAddrVal;
      DWORD   IPAddrVal;
      DOUBLE  VarTimeVal;
      LPSTR   pStringVal;
  } Value;
} NMCOLUMNVARIANT;

Members

Uint8Val
8-bit unsigned integer value.
Sint8Val
8-bit signed integer value.
Uint16Val
16-bit unsigned integer value.
Sint16Val
16-bit signed integer value.
Uint32Val
32-bit unsigned integer value.
Sint32Val
32-bit signed integer value.
Float64Val
64-bit float value.
FrameVal
Frame number.
YesNoVal
Displays Yes or No.
OnOffVal
Displays On or Off.
TrueFalseVal
Displays True or False.
MACAddrVal [MAC_ADDRESS_SIZE]
MAC address.
IPXAddrVal
IPX address.
IPAddrVal
IP address.
VarTimeVal
Variant time. Use VariantTimetoSystemTime to convert to system time.
pStringVal
Pointer to a string.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Event.h.


NMCOLUMNTYPE

The NMCOLUMNTYPE enumeration is used to specify the members of the NMCOLUMNVARIANT structure.

typedef enum
{
  NMCOLUMNTYPE_UINT8 = 0,
  NMCOLUMNTYPE_SINT8,
  NMCOLUMNTYPE_UINT16,
  NMCOLUMNTYPE_SINT16,
  NMCOLUMNTYPE_UINT32,
  NMCOLUMNTYPE_SINT32,
  NMCOLUMNTYPE_FLOAT64,
  NMCOLUMNTYPE_FRAME,
  NMCOLUMNTYPE_YESNO,
  NMCOLUMNTYPE_ONOFF,
  NMCOLUMNTYPE_TRUEFALSE,
  NMCOLUMNTYPE_MACADDR,
  NMCOLUMNTYPE_IPXADDR,
  NMCOLUMNTYPE_IPADDR,
  NMCOLUMNTYPE_VARTIME,
  NMCOLUMNTYPE_STRING
} NMCOLUMNTYPE;

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Event.h.


PROTOCOLTABLE

The PROTOCOLTABLE structure contains a list of protocols.

typedef struct_PROTOCOLTABLE
{
  DWORD nProtocols;
  HPROTOCOL hProtocol[1];
} PROTOCOLTABLE;

Members

nProtocols
Number of protocols that are enabled.
hProtocol
Array of handles to enabled protocols.


Expert Enumerations

The expert structures use this enumeration.

Enumeration | Description
EXPERTSTATUSENUMERATION | Provides status values.

Network Monitor also provides export functions, helper functions that the expert can call, structures, and enumerations.

For information about | See
Functions that experts export. | Expert DLL Export Functions
Helper functions that experts and parsers can call. | Expert and Parser Common Functions
Helper functions that are called only by experts | Expert Functions
Structures that expert functions use. | Expert Structures


EXPERTSTATUSENUMERATION

The EXPERTSTATUSENUMERATION enumeration contains status values. It is used by the Status member of EXPERTSTATUS structure and the Status parameter in ExpertIndicateStatus.

typedef enum
{
  EXPERTSTATUS_INACTIVE = 0,
  EXPERTSTATUS_STARTING,
  EXPERTSTATUS_RUNNING,
  EXPERTSTATUS_PROBLEM,
  EXPERTSTATUS_ABORTED,
  EXPERTSTATUS_DONE,
} EXPERT_STATUS_ENUMERATION;

Members

EXPERTSTATUS_INACTIVE
The expert never started.
EXPERTSTATUS_STARTING
The expert is starting.
EXPERTSTATUS_RUNNING
The expert is running normally.
EXPERTSTATUS_PROBLEM
A problem specified in SubStatus stopped the expert.
EXPERTSTATUS_ABORTED
Network Monitor stopped the expert.
EXPERTSTATUS_DONE
The expert finished successfully.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Expert.h.


Parser Functions and Structures

This section contains information about parser-specific functions, structures, and enumerations that you can use to develop a parser. This section includes the following:

  • Parser DLL Export Functions

    These topics describe the functions that must be exported by parser DLLs.

  • Parser Functions

    These topics describe the helper functions that are called by parsers.

  • Structures used by parser functions

    These topics describe the structures that are used by parser functions.


Parser DLL Export Functions

The following functions are the entry points for parser DLLs. The functions are the entry points for calls from the operating system and Network Monitor.

Function | Description
DllMain Parser | Indicates to the parser DLL that it is loaded or unloaded. The operating system calls the DllMain Parser function when a process loads or unloads the DLL.
AttachProperties | Notifies the parser to attach any properties that exist in a frame.
Deregister | Notifies the parser to clean up.
FormatProperties | Notifies the parser to take all of the property instances in and build the szPropertyText member of each PROPERTYINST structure.
RecognizeFrame | Determines whether the parser can interpret the raw frame data with the specified protocol.
Register Parser | Determines basic information about the parser within the DLL. Network Monitor calls the Register Parser function.
ParserAutoInstallInfo | Installs a parser automatically.

Network Monitor provides structures and helper functions that the parser can call.

For information about | See
Helper functions that experts and parsers can call. | Expert and Parser Common Functions
Helper functions that only parsers can call. | Parser Functions
Structures that parser functions use. | Parser Structures


DllMain Parser

The DllMain export function for the parser identifies the existence of the parser, and releases resources that Network Monitor uses for the parser. DllMain must be implemented in all parser DLLs.

BOOL WINAPI DllMain(
  HANDLE hInstance,
  ULONG Command,
  LPVOID Reserved
);

Parameters

hInstance
[in] Handle to an instance of the parser.
Command
[in] Indicator to determine why the function is called. For a list of all possible flags, see DllMain. The parser implementation must process the following values.
DLL_PROCESS_ATTACH
When DllMain is called for the first time, the DLL must call CreateProtocol to provide information to Network Monitor.
DLL_PROCESS_DETACH
When DllMain is called for the last time, the DLL must call DestroyProtocol to release the resources that the DLL uses.
Reserved
Not used now.

Return Values

The parser DLL always returns TRUE.

Remarks

The operating system calls DllMain to load and unload the parser DLL. This function is based on the dynamic-link library DllMain function.

You can also use the implementation of DllMain to store an instance of a parser for use in the future. For example, you can store a parser DLL instance, and then use it for a system call in the future.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement DllMain — includes an example. | Implementing DllMain

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.

See Also

CreateProtocol, DestroyProtocol, DllMain


AttachProperties

The AttachProperties export function maps the properties to a location within a piece of recognized data. AttachProperties must be implemented for each parser that the parser DLL supports.

DWORD AttachProperties(
  HFRAME hFrame,
  LPBYTE lpFrame,
  LPBYTE lpProtocol,
  DWORD MacType,
  DWORD BytesLeft,
  HPROTOCOL hPreviousProtocol,
  DWORD nPreviousProtocolOffset,
  DWORD lpInstData
);

Parameters

hFrame
[in] Handle of the frame that is being parsed.
lpFrame
[in] Pointer to the first byte in a frame.
lpProtocol
[in] Pointer to the start of the recognized data.
MacType
[in] MAC value of the first protocol in a frame. The MacType can be one of the following:
MacType value | Meaning
MAC_TYPE_ETHERNET | 802.3
MAC_TYPE_TOKENRING | 802.5
MAC_TYPE_FDDI | ANSI X3T9.5

BytesLeft
[in] The remaining number of bytes in a frame — starting at the beginning of the recognized data.
hPreviousProtocol
[in] Handle of the previous protocol.
nPreviousProtocolOffset
[in] Offset of the previous protocol — starting at the beginning of the frame.
lpInstData
[in] Pointer to the instance data that the previous protocol provides.

Return Values

If the function is successful, the return value is a pointer to the first byte after the recognized data in a frame.

–or–

NULL if the recognized data is the last piece of data in a frame.

If the function is unsuccessful, the return value is a pointer to the recognized data. The lpProtocol parameter passes the pointer to the parser DLL.

Remarks

Network Monitor calls the AttachProperties function for each parser that recognizes a piece of data in a frame. Note that the parser determines which properties exist in the recognized data, and where each property is located.

During the implementation of AttachProperties, call AttachPropertyInstance to use the data as it exists in the capture. You can also call AttachPropertyInstanceEx function to modify the property data. However, it is advised that you use the data as it exists in the capture.

The AttachPropertyInstanceEx and AttachPropertyInstance functions are called only for the properties that exist in the recognized data. Note that Network Monitor has a property database for the parser that contains a description of all the properties that the parser supports.

Instance data is information that is passed from one parser to another. In the lpInstData parameter of the AttachProperties and RecognizeFrame functions, Network Monitor provides a pointer to the instance data of the previous protocol. You can set the instance data for your parser during your implementation of RecognizeFrame.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
What entry points are included in the parser DLL. | Parser DLL Architecture
How to recognize data. | Implementing RecognizeFrame
How to create a property database. | Implementing Register
How to implement AttachProperties — includes an example. | Implementing AttachProperties

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.

See Also

AttachPropertyInstance, AttachPropertyInstanceEx, RecognizeFrame


Deregister

The Deregister export function frees the resources used to create the protocol property database. The parser DLL must implement Deregister.

VOID Deregister(
  HPROTOCOL hProtocol
);

Parameters

hProtocol
[in] Handle of the protocol for a specific database.

Return Values

None.

Remarks

Network Monitor calls Deregister after passing all the capture information to the parser DLL. The parser DLL must implement a Deregister function for each protocol that the parser supports.

When implementing Deregister, the parser DLL must call the DestroyPropertyDatabase function to release the property database resources.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement Deregister — includes an example. | Implementing Deregister

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.

See Also

DestroyPropertyDatabase


FormatProperties

The FormatProperties export function formats the data that is displayed in the details pane of the Network Monitor UI. If you want to display data in the details pane, you must implement the FormatProperties export function in all parser DLLs.

DWORD FormatProperties(
  HFRAME hFrame,
  LPBYTE lpFrame,
  LPBYTE lpProtocol,
  DWORD nPropertyInsts,
  LPPROPERTYINST lpPropInst
);

Parameters

hFrame
[in] Handle to the frame that is being parsed.
lpFrame
[in] Pointer to the first byte of a frame.
lpProtocol
[in] Pointer to the beginning of the protocol data in a frame.
nPropertyInsts
[in] Number of PROPERTYINST structures provided by lpPropInst.
lpPropInst
[in] Pointer to an array of PROPERTYINST structures.

Return Values

If the function is successful, the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

Network Monitor calls the FormatProperties function to display data in the details pane of the Network Monitor UI. Typically, FormatProperties is called to format the summary line for a protocol, and then to format all the property instances of the protocol within a frame. However, Network Monitor does not guarantee the number of times it calls FormatProperties for a specific parser.

During the implementation of the FormatProperties function, the parser indirectly calls the FormatPropertyInstance function to use the generic formatter that Network Monitor provides, or it can call a custom formatter procedure that is defined by the parser. One of the formatters must be called for each PROPERTYINST structure passed to the parser DLL in the lpPropInst parameter.

For Information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement FormatProperties — includes an example. | Implementing FormatProperties
How the generic formatter formats different types of data. | Generic Formatter Output

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.

See Also

FormatPropertyInstance, PROPERTYINFO, PROPERTYINST


RecognizeFrame

The RecognizeFrame export function indicates whether a piece of data is recognized as the protocol that the parser detects. The RecognizeFrame export function must be implemented for each parser that the parser DLL supports.

LPBYTE RecognizeFrame(
  HFRAME hFrame,
  LPBYTE lpFrame,
  LPBYTE lpProtocol,
  DWORD MacType,
  DWORD BytesLeft,
  HPROTOCOL hPreviousProtocol,
  DWORD nPreviousProtocolOffset,
  LPDWORD ProtocolStatusCode,
  LPHPROTOCOL phNextProtocol,
  LPDWORD lpInstData
);

Parameters

hFrame
[in] Handle to the frame that contains the data.
lpFrame
[in] Pointer to the first byte of a frame. The pointer provides a way to view data that other parsers recognize.
lpProtocol
[in] Pointer to the start of the unclaimed data. Typically, the unclaimed data is located in the middle of a frame because a previous parser has claimed data before this parser. The parser must test the unclaimed data first.
MacType
[in] MAC value of the first protocol in a frame. Typically, the MacType value is used when the parser must identify the first protocol in a frame. The MacType value can be one of the following:
MacType value | Meaning
MAC_TYPE_ETHERNET | 802.3
MAC_TYPE_TOKENRING | 802.5
MAC_TYPE_FDDI | ANSI X3T9.5

BytesLeft
[in] The remaining number of bytes from a location in a frame to the end of the frame.
hPreviousProtocol
[in] Handle of the previous protocol.
nPreviousProtocolOffset
[in] Offset of the previous protocol — beginning of the frame.
ProtocolStatusCode
[out] Protocol status indicator. The parser DLL must set one of the following status codes.
PROTOCOL_STATUS_RECOGNIZED
The parser recognizes the data but does not know which protocol follows. After setting the code, return a pointer to the remaining unclaimed data that follow the recognized protocol. Network Monitor uses the follow set of the protocol to continue parsing.
PROTOCOL_STATUS_NOT_RECOGNIZED
The parser does not recognize the data. After setting this code, return the pointer to the beginning of the data — using the pointer that the lpProtocol parameter passes to the parser DLL. Network Monitor uses the follow set of the previous protocol to continue parsing.
PROTOCOL_STATUS_CLAIMED
The parser recognizes the data and claims the remaining data. After setting the code, return NULL for Network Monitor to terminate parsing a frame.
PROTOCOL_STATUS_NEXT_PROTOCOL
The parser recognizes the data and knows which protocol follows. After setting the code, set the phNextProtocol parameter, and return a pointer to the remaining unclaimed data that follow the recognized protocol. Network Monitor continues parsing the frame.
phNextProtocol
[out] Pointer to the handle of the next protocol. This parameter is set when a protocol identifies the protocol that follows a protocol. To obtain the handle of the next protocol, call the GetProtocolFromTable function.
lpInstData
[in, out] On input, a pointer to the instance data from the previous protocol.

On output, a pointer to the instance data for the current protocol.

Return Values

If the function is successful, the return value is a pointer to the first byte after the recognized parser data. If the parser claims all the remaining data, the return value is NULL.

If the function is unsuccessful, the return value is an initial pointer that the lpProtocol parameter passes-in.

Remarks

The RecognizeFrame function determines whether the parser recognizes the raw data — starting at the lpProtocol pointer.

  • If the protocol recognizes the data, the RecognizeFrame function returns a pointer to the remaining data, or returns NULL if the current protocol is the last protocol in a frame.
  • If the protocol does not recognize the data, the RecognizeFrame function returns the pointer passed to the parser DLL in the lpProtocol parameter.

Note RecognizeFrame can be called before the Register function is called to register the protocol properties. For that reason, the implementation of the RecognizeFrame function does not rely on any properties or structures that are created or initialized during the implementation of the protocol Register function.

Handoff Set and Follow Set

A parser can use a handoff set or follow set to identify for Network Monitor the protocol that follows recognized data.

  • If information is available in recognized data, the parser uses its handoff set to obtain a handle to the next protocol, and then passes that handle to Network Monitor.
  • If information is not available, the parser does not pass a handle, and Network Monitor uses the parser follow set to determine which protocol follows.

Passing information between protocols

Use the lpInstData parameter to pass information between protocols. On input, you can retrieve the information from the previous protocol. On output, you can pass information to the next protocol.

For Information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement RecognizeFrame — includes an example. | Implementing RecognizeFrame
How to specify a handoff set and follow set. | Specifying a Handoff Set Specifying a Follow Set

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.

See Also

GetProtocolFromTable


Register Parser

The Register export function must be implemented in all parser DLLs. The implementation of Register creates and fills-in a property database for a protocol. Network Monitor uses the database to determine which properties the protocol supports.

VOID Register(
  HPROTOCOL hProtocol
);

Parameters

hProtocol
[in] The handle of the protocol that Network Monitor provides when calling Register. The hProtocol handle is needed when calling export helper functions.

Return Values

None.

Remarks

Network Monitor starts calling the Register function as soon as a capture is loaded. Network Monitor calls the Register function for each protocol it can identify. The CreateProtocol function passes a pointer to the Register function.

The implementation of Register includes calls to the following functions.

  • A call to the CreatePropertyDatabase and AddProperty functions to create a database of all the properties that the protocol supports.
  • A call to the CreateHandoffTable function is required if the protocol uses a handoff set.

If the parser DLL contains multiple parsers, and the parser can detect more than one protocol, you must implement a Register function for each protocol.

For Information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement Register — includes an example. | Implementing Register

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.

See Also

AddProperty, CreateHandoffTable, CreatePropertyDatabase, CreateProtocol


ParserAutoInstallInfo

The ParserAutoInstallInfo export function identifies the parser, or parsers that are located in a DLL. ParserAutoInstallInfo should be implemented in all parser DLLs.

PPF_PARSERDLLINFO WINAPI ParserAutoInstallInfo();

Parameters

The ParserAutoInstallInfo function does not have parameters.

Return Values

If the function is successful, the return value is a PF_PARSERDLLINFO structure that describes the parsers in the DLL.

If the function is unsuccessful, the return value is FALSE.

Remarks

When Network Monitor loads for the first time, it calls ParserAutoInstallInfo (if it exists) to automatically install each parser, and then enumerate all the parser DLLs in the parser subdirectory.

The information returned in the PF_PARSERDLLINFO structure includes the following:

  • The number of parsers in the DLL (typically one).
  • The name and a brief description of the protocol that each parser detects.
  • An optional Help file for each protocol.
  • The protocols that precede each protocol.
  • The protocols that follow each protocol.

Each parser DLL should contain one parser. However, Network Monitor allows you to create a DLL that contains more than one parser. For example, tcpip.dll is a Network Monitor DLL with more than one parser.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement ParserAutoInstallInfo — includes an example. | Implementing ParserAutoInstallInfo

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NmExport.h.

See Also

PF_PARSERDLLINFO


Parser Functions

The following helper functions are called by parsers.

Function | Description
AddressToString | Converts an address to a string.
LookupByteSetString | Retrieves the string corresponding to the specified value of a labeled set.
SetCCInstPtr | Captures a context instance pointer.
StringToAddress | Converts a string to an address.
VarLenSmallIntToDword | Converts a variable-length, small integer to a DWORD.
LookupDwordSetString | Retrieves the string corresponding to the specified value of a labeled set.
LookupWordSetString | Retrieves the string corresponding to the given value from a labeled set.
BERGetHeader | Decodes a choice header.
BERGetInteger | Decodes a BER-encoded integer.
BERGetString | Decodes a BER-encoded string.
CCHeapAlloc | Allocates memory on a capture-by-capture basis.
CCHeapFree | Releases the memory allocated by the CCHeapAlloc function.
CCHeapReAlloc | Reallocates memory allocated by the CCHeapAlloc function.
CCHeapSize | Retrieves the size of the memory allocated by the CCHeapAlloc function.
GetCCInstPtr | Retrieves the pointer to the instance data added to the capture context.
CreateProtocol | Informs the Network Monitor API that a specific protocol parser exists.
DestroyProtocol | Destroys the protocol created by the CreateProtocol function.
BuildINIPath | Retrieves a fully qualified path to the initialization (INI) file that corresponds to information you enter.
CreateHandoffTable | Creates a handoff table based on information in an given INI file.
DestroyHandoffTable | Destroys a handoff table created with the CreateHandoffTable function.
GetProtocolFromTable | Retrieves the protocol of a given handoff table.
AddProperty | Adds a PROPERTYINFO structure to the property database.
AttachPropertyInstance | Attaches a property instance to a frame.
AttachPropertyInstanceEx | Attaches a property instance to a frame.
CreatePropertyDatabase | Creates a property database that describes properties that the parser uses to describe its data.
DestroyPropertyDatabase | Destroys a property database created by calls to the CreatePropertyDatabase and AddProperty functions.
FindNextFrame | Finds the next frame in the current capture context that matches a given filter.
FindPreviousFrame | Finds the previous frame in the current capture context that matches a given filter.
FormatPropertyInstance | Formats the property instance in a generic manner.
GetFrameDestAddress | Retrieves the destination address of a frame.
GetFrameSourceAddress | Retrieves the source address of a frame.
GetProtocolStartOffset | Retrieves the offset to a given protocol in the frame.
ParserTemporaryLockFrame | Locks a frame when it enters a parser and unlocks the frame when it exits.

For information about export functions (helper functions that can be called by experts and parsers), structures, and enumerations, see the following topics.

For information about | See
Functions that parsers export. | Parser DLL Export Functions
Structures that parser functions use. | Parser Structures
Common helper functions that parsers and experts call. | Expert and Parser Common Functions


AddressToString

The AddressToString function converts an address into a string.

LPSTR WINAPI AddressToString(
  LPSTR string,
  BYTE *lpAddress
);

Parameters

string
[out] Sting that the address is converted to.
lpAddress
[in] The address that is printed out.

Return Values

The return value is a pointer to the converted string.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


LookupByteSetString

The LookupByteSetString function returns the string corresponding to the specified value of a labeled set.

LPBYTE WINAPI LookupByteSetString(
  LPSET lpSet,
  BYTE Value
);

Parameters

lpSet
Pointer to a labeled set, from which you can extract the value's label.
Value
Value of a labeled set.

Return Values

If the function is successful, the return value is a string corresponding to the value provided.

If the function is unsuccessful, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


SetCCInstPtr

The SetCCInstPtr function captures a context instance pointer.

VOID WINAPI SetCCInstPtr(
  LPVOID lpCurCaptureInst
);

Parameters

lpCurCaptureInst
Pointer to the instance data added to the capture.

Return Values

None.

Remarks

Use this function to store a pointer to a block that was allocated with the CCHeapAlloc function. Each parser can set a single instance of data on a capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use NMAPI.lib.

See Also

GetCCInstPtr, CCHeapAlloc, CCHeapFree, CCHeapReAlloc, CCHeapSize


StringToAddress

The StringToAddress function converts a string to an address.

LPBYTE WINAPI StringToAddress(
  BYTE *lpAddress,
  LPSTR string
);

Parameters

lpAddress
[out] Pointer to the address the string is converted to.
string
[in] String that is converted to an address.

Return Values

The return value is a pointer to the converted string.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


VarLenSmallIntToDword

The VarLenSmallIntToDword function converts a variable-length, small integer to a DWORD.

LPDWORD WINAPI VarLenSmallIntToDword(
  LPBYTE pValue,
  WORD ValueLen,
  BOOL fIsByteswapped,
  LPDWORD lpDword
);

Parameters

pValue
Pointer to the variable-length, small integer.
ValueLen
Length (in bytes) of the variable-length, small integer .
fIsByteswapped
Flag that indicates whether the variable length small integer is byte-swapped.
lpDword
The DWORD that the integer is converted to.

Return Values

The return value is a pointer to the DWORD.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


LookupDwordSetString

The LookupDwordSetString function returns the string corresponding to the specified value of a labeled set.

LPBYTE WINAPI LookupDwordSetString(
  LPSET lpSet,
  DWORD Value
);

Parameters

lpSet
Labeled set, from which you can extract the value's label.
Value
Value of a labeled set.

Return Values

If the function is successful, the return value is the string that corresponds to the specified value.

If the function is unsuccessful, the specified value is not in the set, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


LookupWordSetString

The LookupWordSetString function returns the string corresponding to the requested value from a labeled set.

LPBYTE WINAPI LookupWordSetString(
  LPSET lpSet,
  WORD Value
);

Parameters

lpSet
Labeled set from which you extract the value's label.
Value
Value of a labeled set.

Return Values

If the function is successful, the return value is a string that corresponds to the requested value.

If the function is unsuccessful, the specified value is not in the set, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


BERGetHeader

The BERGetHeader function decodes a choice header.

BOOL BERGetHeader(
  LPBYTE pCurrentPointer,
  LPBYTE pTag,
  LPDWORD pHeaderLength,
  LPDWORD pDataLength,
  LPBYTE *ppNext
);

Parameters

pCurrentPointer
Pointer to the choice header.
pTag
Pointer to the returned tag.
pHeaderLength
Pointer to the returned header length.
pDataLength
Pointer to the returned data length.
ppNext
Pointer to the header contents.

Return Values

If the function is successful (that is, a valid BER choice header is found) the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


BERGetInteger

The BERGetInteger function decodes a BER-encoded integer.

BOOL BERGetInteger(
  LPBYTE pCurrentPointer,
  LPBYTE *ppValuePointer,
  LPDWORD pHeaderLength,
  LPDWORD pDataLength,
  LPBYTE *ppNext
);

Parameters

pCurrentPointer
Pointer to the integer that is decoded.
ppValuePointer
Pointer to the pointer to returned value.
pHeaderLength
Pointer to the returned header length.
pDataLength
Pointer to the data length.
ppNext
Pointer to the pointer to the next BER entry.

Return Values

If the BERGetInteger function is successful (that is, if a valid BER encoded integer is found and converted), the return value is TRUE

If function is unsuccessful, the return value is FALSE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


BERGetString

The BERGetString function decodes a BER-encoded string.

BOOL BERGetString(
  LPBYTE pCurrentPointer,
  LPBYTE *ppValuePointer,
  LPDWORD pHeaderLength,
  LPDWORD pDataLength,
  LPBYTE *ppNext
);

Parameters

pCurrentPointer
Pointer to the string that is decoded.
ppValuePointer
Pointer to the pointer of the decoded string.
pHeaderLength
Pointer to the returned header length.
pDataLength
Pointer to the string length.
ppNext
Pointer to the pointer of the next BER entry.

Return Values

If the function is successful (that is, if a valid BER-encoded string is decoded), the return value is TRUE.

If function is unsuccessful, the return value is FALSE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use Parser.lib.


CCHeapAlloc

The CCHeapAlloc function allocates memory on a capture-by-capture basis.

LPVOID WINAPI CCHeapAlloc(
  DWORD dwBytes,
  BOOL bZeroInit
);

Parameters

dwBytes
Requested length of memory allocated.
bZeroInit
Indicator of whether allocated memory was initialized. If the parameter value is TRUE, the allocated memory initializes to zero.

Return Values

If the function is successful, the return value is a pointer to the allocated memory.

If the function is unsuccessful, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use NMAPI.lib.

See Also

SetCCInstPtr, GetCCInstPtr, CCHeapFree, CCHeapReAlloc, CCHeapSize


CCHeapFree

The CCHeapFree function releases the memory allocated by the CCHeapAlloc function.

BOOL WINAPI CCHeapFree(
  LPVOID lpMem
);

Parameters

lpMem
Pointer to the memory that this function releases.

Return Values

If the CCHeapFree function is successful, the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use NMAPI.lib.

See Also

SetCCInstPtr, GetCCInstPtr, CCHeapAlloc, CCHeapReAlloc, CCHeapSize


CCHeapReAlloc

The CCHeapReAlloc function reallocates memory allocated by the CCHeapAlloc function.

LPVOID WINAPI CCHeapReAlloc(
  LPVOID lpMem,
  DWORD dwBytes,
  BOOL bZeroInit
);

Parameters

lpMem
Pointer to the original allocated memory.
dwBytes
Size of the reallocated memory, measured in bytes.
bZeroInit
Indicator of whether reallocated memory was initialized. If the parameter value is TRUE, the newly reallocated memory initializes to zero.

Return Values

If the function is successful, the return value is a pointer to the reallocated memory.

If the function is unsuccessful, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use NMAPI.lib.

See Also

SetCCInstPtr, GetCCInstPtr, CCHeapAlloc, CCHeapFree, CCHeapSize


CCHeapSize

The CCHeapSize function returns the size of the memory allocated by the CCHeapAlloc function.

DWORD WINAPI CCHeapSize(
  LPVOID lpMem
);

Parameters

lpMem
Pointer to the allocated memory.

Return Values

If the function is successful, the return value is the size of the requested memory block — measured in bytes.

If the function is unsuccessful, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use NMAPI.lib.

See Also

SetCCInstPtr, GetCCInstPtr, CCHeapAlloc, CCHeapFree, CCHeapReAlloc


GetCCInstPtr

The GetCCInstPtr function returns the pointer to the instance data added to the capture context.

LPVOID WINAPI GetCCInstPtr(VOID);

Parameters

This function has no parameters.

Return Values

If the function is successful, the return value is a pointer to the instance data of a specific capture.

If the function is unsuccessful, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use NMAPI.lib.

See Also

SetCCInstPtr, CCHeapAlloc, CCHeapFree, CCHeapReAlloc, CCHeapSize


CreateProtocol

The CreateProtocol function notifies Network Monitor that a specific protocol parser exists.

HPROTOCOL WINAPI CreateProtocol(
  LPSTR ProtocolName,
  LPENTRYPOINTS lpEntryPoints,
  DWORD cbEntryPoints
);

Parameters

ProtocolName
[in] Name of the protocol the parser will detect.
lpEntryPoints
[in] An ENTRYPOINTS structure that contains the remaining parser DLL entry points. See Remarks for a list of the export functions that each entry point references. Entry points must be provided in the order that the ENTRYPOINTS structure specifies.
cbEntryPoints
[in] The size of the ENTRYPOINTS structure. Network Monitor provides an ENTRYPOINTS_SIZE macro that you can use to specify the size of the structure.

Return Values

If the function is successful, the return value is a handle to the protocol.

If the function is unsuccessful, the return value is NULL.

Remarks

The parser DLL calls CreateProtocol during its implementation of DllMain. The CreateProtocol function is called when the operating system loads the parser DLL for the first time.

The entry points referenced in the lpEntryPoints parameter include pointers to the following export functions that must be provided in the order presented here.

  • Register
  • Deregister
  • RecognizeFrame
  • AttachProperties
  • FormatProperties
For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
How to implement DllMain — includes an example of calling CreateProtocol within DllMain. | Implementing DllMain

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

DllMain


DestroyProtocol

The DestroyProtocol function destroys the protocol that the CreateProtocol function creates.

VOID WINAPI DestroyProtocol(
  HPROTOCOL hProtocol
);

Parameters

hProtocol
[in] Handle to the protocol to be destroyed.

Return Values

None.

Remarks

The parser DLL calls the DestroyProtocol function during its implementation of DllMain. DestroyProtocol is called when the operating system is going to unload the DLL.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
How to implement DllMain — includes an example. | Implementing DllMain

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

DllMain


BuildINIPath

The BuildINIPath function returns a fully qualified path to an INI file that corresponds to information you enter.

LPSTR BuildINIPath(
  char *FullPath,
  char *IniFileName
);

Parameters

FullPath
Buffer that receives the fully qualified INI file name.
IniFileName
Name of the INI file (the full file name minus the filename extension).

Return Values

If the function is successful, the return value is a pointer to the fully qualified INI file name.

If the function is unsuccessful, the return value is NULL.

Remarks

The path that this function returns is a fully qualified path to an INI file that corresponds to information you enter. For example, if you enter XNS or TCP, the function generates a path to Xns.ini or Tcp.ini, respectively.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Inilib.h.
Library: Use Parser.lib.


CreateHandoffTable

The CreateHandoffTable function creates a handoff table that includes the handoff set information stored in the INI file of the parser.

DWORD WINAPI CreateHandoffTable(
  LPSTR secName,
  LPSTR iniFile,
  LPHANDOFFTABLE *hTable,
  DWORD nMaxProtocolEntries,
  DWORD base
);

Parameters

secName
[in] String that indicates the section of the INI file where the handoff set information is located.
iniFile
[in] String that includes the name of the parser INI file.
hTable
[out] Handle to the created handoff table.
nMaxProtocolEntries
[in] Number that specifies the maximum number of entries that the handoff table can process.
base
[in] Numerical base of handoff set numbers stored in the INI file.

Return Values

If the function is successful, the return value is the number of entries in the handoff table.

If the function is unsuccessful, the return value is zero.

Remarks

The handoff table is used to obtain a handle to one of the protocols included in the table. To obtain a handle from one of these protocols, call GetProtocolFromTable.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Inilib.h.
Library: Use NMAPI.lib.

See Also

GetProtocolFromTable


DestroyHandoffTable

The DestroyHandoffTable function destroys a handoff table created with CreateHandoffTable.

VOID WINAPI DestroyHandoffTable(
  LPHANDOFFTABLE hTable
);

Parameters

hTable
Handle to the destroyed handoff table.

Return Values

None.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Inilib.h.
Library: Use NMAPI.lib.


GetProtocolFromTable

The GetProtocolFromTable function returns a handle to a protocol — based on a given handoff table and value.

HPROTOCOL WINAPI GetProtocolFromTable(
  LPHANDOFFTABLE hTable,
  DWORD ItemToFind,
  LPDWORD lpInstData
);

Parameters

hTable
[in] Handle to a handoff table.
ItemToFind
[in] Value used to locate the protocol in a handoff table. The value must be available in the protocol data.
lpInstData
[out] If available in the handoff table, instance data for the next protocol.

Return Values

If the function is successful, the return value is a protocol handle.

If the function is unsuccessful, the return value is NULL.

Remarks

When implementing the RecognizeFrame export function, the GetProtocolFromTable function is used to obtain a handle to the next protocol. The GetProtocolFromTable function is called to retrieve a handle from the next protocol — if the protocol identifies which protocol follows.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Inilib.h.
Library: Use NMAPI.lib.

See Also

RecognizeFrame


AddProperty

The AddProperty function adds one property to the parser property database.

HPROPERTY WINAPI AddProperty(
  HPROTOCOL hProtocol,
  LPPROPERTYINFO PropertyInfo
);

Parameters

hProtocol
[in] Handle of the protocol that is associated with the database. When Network Monitor calls the Register function, Network Monitor passes the protocol handle to the parser DLL.
PropertyInfo
[in] Pointer to a PROPERTYINFO structure that defines the property.

Return Values

If the function is successful, the return value is a pointer to the property that is added.

If the function is unsuccessful, the return value is NULL.

Remarks

The AddProperty function should be called only when implementing the Register function. The parser uses AddProperty to add a property to the property database of the protocol. Properties are added to the database one property at a time.

AddProperty must be called after calling CreatePropertyDatabase. If AddProperty is called before the property database is created, Network Monitor returns the NMERR_NO_PROPERTY_DATABASE error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

CreatePropertyDatabase, PROPERTYINFO, Register


AttachPropertyInstance

The AttachPropertyInstance function maps an existing property to a specific location in the recognized data.

BOOL WINAPI AttachPropertyInstance(
  HFRAME hFrame,
  HPROPERTY hProperty,
  DWORD Length,
  ULPVOID lpData,
  DWORD HelpID,
  DWORD IndentLevel,
  DWORD IFlags
);

Parameters

hFrame
[in] Handle to the frame that is being parsed. Use the handle passed to the parser DLL in the hFrame parameter of the AttachProperties function.
hProperty
[in] Handle to a PROPERTYINFO structure that defines the property. When you implement the Register export function you specify the PROPERTYINFO structure that defines the property.
Length
[in] Length of the data for this instance of the property.
lpData
[in] Pointer to the location in the recognized data where the property value is located. Use the pointer passed to the parser DLL in the lpProtocol parameter of the AttachProperties function.
HelpID
[in] Identifier (from 0 to 2047) used to set context-sensitive Help for the property.

The identifier number is relative to the Help file associated with the protocol property database.

IndentLevel
[in] Indentation level (from 0 to 15) used to display a property hierarchically.

Network Monitor uses levels 0 through 9. Level 15 is a special value that allows a parser to attach a hidden property that is not visible.

IFlags
[in] A BIT field value that indicates the order of the BITs within a property. Previous parsers that set fError to 0 or 1, should now set fError to IFLAG_ERROR. Set this parameter to one of the following values.
Flag | Meaning
IFLAG_ERROR | Data in the frame has an error.
IFLAG_SWAPPED | At attach time, WORD byte is a non-Intel format.
IFLAG_UNICODE | At attach time, STRING is Unicode.

Return Values

If the function is successful, the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

The AttachPropertyInstance function is called during the implementation of the AttachProperties export function. When a property is attached to the data, Network Monitor creates a PROPERTYINST structure that defines the instance of the attached property.

During the implementation of AttachProperties, call AttachPropertyInstance to use the data as it exists in the capture. You can also call AttachPropertyInstanceEx function to modify the property data. However, it is advised that you use the data as it exists in the capture.

For Information on | See
What parsers are, and how they work with Network Monitor. | Parsers
How to call AttachPropertyInstance. | Implementing AttachProperties

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

AttachProperties, AttachPropertyInstanceEx, PROPERTYINST


AttachPropertyInstanceEx

The AttachPropertyInstanceEx function maps an existing property to a specific location in the recognized data, and modifies the value of the property data.

BOOL WINAPI AttachPropertyInstanceEx(
  HFRAME hFrame,
  HPROPERTY hProperty,
  DWORD Length,
  ULPVOID lpData,
  DWORD LengthEx,
  ULPVOID lpDataEx,
  DWORD HelpID,
  DWORD IndentLevel,
  DWORD IFlags
);

Parameters

hFrame
[in] Handle to the frame that is being parsed. Use the handle passed to the parser DLL in the hFrame parameter of the AttachProperties function.
hProperty
[in] Handle to a PROPERTYINFO structure that defines the property. When you implement the Register export function you specify the PROPERTYINFO structure that defines the property.
Length
[in] Length of the data for this instance of the property.
lpData
[in] Pointer to the location in the recognized data where the property value is located. Use the pointer passed to the parser DLL in the lpProtocol parameter of the AttachProperties function.
LengthEx
[in] Length of the extended data — length in bytes.
lpDataEx
[in] Pointer to the extended data, which is typically a stack variable that contains the extend data.
HelpID
[in] Identifier (from 0 to 2047) used to set context-sensitive Help for a property.

The HelpID number is relative to the Help file associated with the protocol property database.

IndentLevel
[in] Indentation level (from 0 to 15) used to display a property hierarchically.

Network Monitor uses levels 0 through 9. Level 15 is a special value that allows the parser to attach a hidden property that is not visible.

IFlags
[in] A BIT field value that indicates the order of the BITs within a property. Previous parsers that set fError to 0 or 1, should now set fError to IFLAG_ERROR. Set this parameter to one of the following values.
Flag | Meaning
IFLAG_ERROR | Data in the frame has an error.
IFLAG_SWAPPED | At attach time, WORD byte is a non-Intel format.
IFLAG_UNICODE | At attach time, STRING is Unicode.

Return Values

If the function is successful, the return value is TRUE.

If the function is unsuccessful, the return value is FALSE.

Remarks

The AttachPropertyInstanceEx function is called during the implementation of the AttachProperties export function. When a property is attached to the data using AttachPropertyInstanceEx, Network Monitor creates a PROPERTYINST structure that defines the instance of the attached property and a PROPERTYINSTEX structure that defines the extended data.

If AttachPropertyInstanceEx is called and no extended data is provided, the lpDataEx parameter is NULL or the LengthEx parameter is 0, the AttachPropertyInstanceEx call is functionally equivalent to an AttachPropertyInstance call.

During the implementation of AttachProperties, call AttachPropertyInstance to use the data as it exists in the capture. You can also call AttachPropertyInstanceEx function to modify the property data. However, it is advised that you use the data as it exists in the capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


CreatePropertyDatabase

The CreatePropertyDatabase function creates a property database that stores the properties of a protocol.

DWORD WINAPI CreatePropertyDatabase(
  HPROTOCOL hProtocol,
  DWORD nProperties
);

Parameters

hProtocol
[in] Handle of the protocol that is associated with the database. When Network Monitor calls the Register function, Network Monitor passes the protocol handle to the parser DLL.
nProperties
[in] Number of properties stored in the database. Set this parameter to the number of properties that the protocol supports.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is an error code.

Error Codes

Code | Meaning
NMERR_INTERNAL_ERROR | An internal error has occurred.
NMERR_INVALID_HPOTOCOL | The handle to the protocol specified in hProtocol is invalid.
NMERR_OUT_OF_MEMORY | Network Monitor does not have enough memory to create the database.

Remarks

The CreatePropertyDatabase function should be called only when implementing the Register function. The parser uses CreatePropertyDatabase to create a property database that describes the properties of a protocol. Network Monitor uses the database to interpret the information within the protocol.

The CreatePropertyDatabase function allocates the structures that Network Monitor needs to maintain a property database.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

Register


DestroyPropertyDatabase

The DestroyPropertyDatabase function releases the resources used to create the protocol property database.

DWORD WINAPI DestroyPropertyDatabase(
  HPROTOCOL hProtocol
);

Parameters

hProtocol
[in] Handle to the property database to be destroyed. The handle is passed to the parser DLL when Network Monitor calls the Deregister function.

Return Values

  • If the function is successful, the return value is NMERR_SUCCESS.
  • If the function is unsuccessful, the return value is an error code.

Error Codes

Code | Meaning
NMERR_INTERNAL_ERROR | An internal error occurred.
NMERR_INVALID_HPROTOCOL | Invalid handle in hProtocol.

Remarks

The DestroyPropertyDatabase function should be called only when implementing the Deregister export function for the protocol. For parser DLLs that support multiple protocols, the DestroyPropertyDatabase function is called for each implementation of Deregister.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement Deregister — includes an example. | Implementing Deregister

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

Deregister


FindNextFrame

The FindNextFrame function finds the next frame in the current capture context that matches the filter.

HFRAME WINAPI FindNextFrame(
  HFRAME hCurrentFrame,
  LPSTR ProtocolName,
  LPADDRESS DestinationAddress,
  LPADDRESS SourceAddress,
  LPWORD ProtocolOffset,
  DWORD OriginalFrameNumber,
  DWORD HighestFrame
);

Parameters

hCurrentFrame
Handle to the frame.
ProtocolName
Protocol name, such as TCP.
DestinationAddress
Destination address.
SourceAddress
Source address.
ProtocolOffset
Pointer to a WORD that will receive the protocol offset.
OriginalFrameNumber
Starting point of the search. By default, this function searches forward 1,000 frames from the OriginalFrameNumber starting point. You can change the search-forward distance by adding this line to the Nmapi.ini file, which is located in the \Network Monitor directory.

MAXLOOKBACK=<new lookforward distance>

HighestFrame
Highest frame number in the capture that will be searched.

Return Values

If the function is successful, the return value is a handle to the next frame.

If the function is not successful, the return value is NULL.

Remarks

The capture filter is defined primarily by the ProtocolName parameter, which is the only required filter input; you can add DestinationAddress and SourceAddress information to increase the capture speed.

The ProtocolOffset pointer is returned to the calling parser, which adds the WORD to the pointer returned by locking the frame (with ParserTemporaryLockFrame) to get the LPBYTE of the protocol that is being searched for. On return, the HFRAME that passed the filter is given to the parser. If the parser finds that this frame is not the one that is being sought, the parser can hand the HFRAME back to the FindNextFrame function to get the next frame. The source and destination addresses are not required and can be passed in as NULL.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


FindPreviousFrame

The FindPreviousFrame function finds the previous frame in the current capture context that matches the filter.

HFRAME WINAPI FindPreviousFrame(
  HFRAME hCurrentFrame,
  LPSTR ProtocolName,
  LPADDRESS DestinationAddress,
  LPADDRESS SourceAddress,
  LPWORD ProtocolOffset,
  DWORD OriginalFrameNumber,
  DWORD LowestFrame
);

Parameters

hCurrentFrame
Handle to the frame.
ProtocolName
Protocol name, such as TCP.
DestinationAddress
Destination address of the frame that is searched for.
SourceAddress
Source address of the frame that is searched for.
ProtocolOffset
Pointer to a WORD that receives the protocol offset.
OriginalFrameNumber
Starting point of the search. By default, this function searches backward 1,000 frames from OriginalFrameNumber starting point. You can change the search-back distance by adding this line to the Nmapi.ini file, which is located in the \Network Monitor directory.

MAXLOOKBACK=<new lookback distance>

LowestFrame
Lowest frame number in the capture that is searched.

Return Values

If the function is successful, the return value is a handle to the previous frame.

If the function is not successful, the return value is NULL..

Remarks

The capture filter is defined primarily by ProtocolName, which is the only required filter input; you can add DestinationAddress and SourceAddress information to increase the capture speed.

ProtocolOffset is returned to the calling parser, which adds this DWORD to the pointer returned by locking the frame (with ParserTemporaryLockFrame ) to get the LPBYTE of the protocol that is being searched for. On return, the HFRAME that passed the filter is given to the parser. If the parser finds that the frame is not the one that is being sought, the parser can hand this HFRAME back to the FindPreviousFrame function to retrieve the next frame. The source and destination addresses, which are not required, can be passed in as NULL. When used, these addresses can be of type ADDRESS_TYPE_IP, and so on, not just MAC types.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


FormatPropertyInstance

The FormatPropertyInstance function formats the property instance data using the generic formatter that Network Monitor provides.

DWORD WINAPI FormatPropertyInstance(
  LPPROPERTYINST lpPropertyInst,
);

Parameters

lpPropertyInst
[in, out] Pointer to a PROPERTYINST structure that contains the instance data.

On input, the generic formatter takes the instance data from one of the PROPERTYINST union members and converts that data to a pre-defined formatted string.

On output, the generic formatter sets the szPropertyText member of the PROPERTYINST structure to a pointer to the formatted string.

Return Values

If the function is successful, the return value is NMERROR_SUCCESS.

If the function is unsuccessful, the return value is NMERROR.

Remarks

The parser DLL indirectly calls the FormatPropertyInstance function when the generic formatter is needed to format data for display in the details pane of the Network Monitor UI. To call FormatPropertyInstance you must specify it in the InstanceData member of the PROPERTYINFO structure when you define the property.

Note The parser does not know which function is called when it wants to format an instance of a property. The function can be FormatPropertyInstance or a custom format function that is defined by the parser. The parser calls whatever format function is specified by the InstanceData member of the PROPERTYINFO structure for the property.

For more information | See
How to implement FormatProperties — includes an example. | Implementing FormatProperties
How the generic formatter formats different types of data. | Generic Formatter Output

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.

See Also

PROPERTYINFO, PROPERTYINST


GetFrameDestAddress

The GetFrameDestAddress function retrieves the destination address of a frame.

DWORD WINAPI GetFrameDestAddress(
  HFRAME hFrame,
  LPADDRESS lpAddress,
  DWORD AddressType,
  DWORD Flags
);

Parameters

hFrame
Handle of the frame to get a pointer to.
lpAddress
Return buffer that stores the frame destination address.
AddressType
Type of address, such as ADDRESS_TYPE_ETHERNET or ADDRESS_TYPE_IP.
Flags
Flags used to modify returned destination address information.
Flag | Meaning
ADDRESSTYPE_FLAGS_NORMALIZE | Cancels out the routing and group BITs.
ADDRESSTYPE_FLAGS_BIT_REVERSE | Converts token ring network addresses back to normal.

Return Values

If the function is successful, the lpAddress value is valid, and the return value is BHERR_SUCCESS.

If the function is unsuccessful, the return value is an error code.

Error Codes

Code | Meaning
BHERR_PROTOCOL_NOT_FOUND | The specified protocol in the AddressType parameter is invalid for the frame.
BHERR_INVALID_HFRAME | The hFrame value is invalid.

Remarks

The ADDRESS_TYPE_FIND_HIGHEST address type is allowed. When this address type is used, the function searches for the IPX, XNS, IP, or VINES IP address before returning the ETHERNET, TOKENRING, or FDDI address. This approach is useful for protocols and in environments where two NICs can be multiplexed under a single server address.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetFrameSourceAddress

The GetFrameSourceAddress function retrieves the source address of a frame.

DWORD WINAPI GetFrameSourceAddress(
  HFRAME hFrame,
  LPADDRESS lpAddress,
  DWORD AddressType,
  DWORD Flags
);

Parameters

hFrame
Handle to the frame to get a pointer to.
lpAddress
Return buffer that stores the frame source address.
AddressType
Type of address you are looking for, such as ADDRESS_TYPE_ETHERNET or ADDRESS_TYPE_IP.
Flags
Flags that specify:
  • ADDRESSTYPE_FLAGS_NORMALIZE, which cancels out the routing and group BITs.
  • ADDRESSTYPE_FLAGS_BIT_REVERSE, which converts token ring network addresses back to normal.

Return Values

If the function is successful, the lpAddress value is valid, and the return value is BHERR_SUCCESS.

If the function is unsuccessful, the return value is an error code.

Error Codes

Code | Meaning
BHERR_PROTOCOL_NOT_FOUND | The protocol specified by the AddressType parameter is invalid for the frame.
BHERR_INVALID_HFRAME | The hFrame parameter value is invalid.

Remarks

An address type of ADDRESS_TYPE_FIND_HIGHEST is allowed. When this address type is used, the function searches for the IPX, XNS, IP, or VINES IP address before returning the ETHERNET, TOKENRING, or FDDI address. This approach is useful for protocols and environments in which two NICs can be multiplexed under a single server address.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


GetProtocolStartOffset

The GetProtocolStartOffset function returns the offset of a specified protocol in the frame.

DWORD WINAPI GetProtocolStartOffset(
  HFRAME hFrame,
  LPSTR ProtocolName
);

Parameters

hFrame
Handle to the frame.
ProtocolName
Protocol name, such as TCP.

Return Values

If the function is successful, the return value is a DWORD offset to the beginning of the protocol being searched for — a return value of zero indicates the protocol is the first protocol in the frame.

If the function is unsuccessful, the protocol is not in the frame, the return value is -1.

Remarks

When given the handle to a frame, this function returns the offset to a specified protocol in the frame. For example, to determine whether the frame is a DNS frame, the DNS parser requires the port address of the TCP protocol. The DNS parser would call this function with TCP as the ProtocolName value. If the frame is recognized by the TCP protocol, the WORD offset from the beginning of the frame to the beginning of the TCP frame is returned. If there is no TCP protocol, the return value is zero.

This function finds the beginning of a protocol in a frame.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Netmon.h.
Library: Use NMAPI.lib.


ParserTemporaryLockFrame

The ParserTemporaryLockFrame function locks a frame when it enters a parser and unlocks the frame when the function exits the parser.

LPBYTE WINAPI ParserTemporaryLockFrame(
  HFRAME hFrame
);

Parameters

hFrame
[in] Handle to the frame that the parser points to.

Return Values

If the function is successful, the return value is a pointer to the first byte of data in the frame.

If the function is unsuccessful, the return value is NULL.

Remarks

Parsers should not call the LockFrame function. If a parser takes a lock and then generates a fault or returns without unlocking the frame, the parser leaves the system in a state where it cannot change protocols or cut or copy frames. Parsers should use the ParserTemporaryLockFrame function, which grants a lock only during the context of the function entry into the parser. On exit from the parser, the lock for that frame is released. As a result, the pointer will be valid only after the parser returns from the call to the AttachProperties or RecognizeFrame function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.
Library: Use NMAPI.lib.


Parser Structures

This section describes structures you can use to develop parsers. These structures are used by functions you can use to develop parsers and functions you can use to develop either parsers or experts.

Structure | Description
MACFRAME | Defines the most commonly used initial protocols.
ENTRYPOINTS | Specifies pointers to the entry points for the Parser DLL.
PF_FOLLOWENTRY | Specifies the protocol that follows the current protocol.
PF_FOLLOWSET | Specifies the set of protocols that follows the current protocol.
PF_HANDOFFENTRY | Specifies either the protocol that hands off to the current protocol or the protocol that the current protocol hands off to.
PF_HANDOFFSET | Specifies the set of protocols that hand off to the current protocol or the set of protocols the current protocol hands off to.
PF_PARSERDLLINFO | Specifies the number of parsers in the parser DLL and information about each parser.
PF_PARSERINFO | Specifies information about a specific parser.
LABELED_BIT | Specifies handles, BIT fields, or flags.
LABELED_BYTE | Specifies a BYTE label pair.
LABELED_DWORD | Specifies a DWORD label pair.
LABELED_WORD | Specifies a WORD label pair.
PROPERTYINFO | Specifies the properties that the protocol parser requires to describe frames.
PROPERTYINST | Specifies an instance of a property in a frame.
PROPERTYINSTEX | Specifies a free-form, extended property instance.
PROTOCOLINFO | Specifies a protocol.
RANGE | Specifies a range for a number.
SET | Specifies a table of values for a property.

For information about functions used to develop parser DLLs, see the following topics.

For information about | See
Functions that the parser DLLs export. | Parser DLL Export Functions
Functions that you can use to develop parser DLLs. | Parser Functions
Functions that you can use to develop parser and expert DLLs. | Expert and Parser Common Functions


MACFRAME

The MACFRAME structure is a union of the most common initial protocols.

typedef union _MACFRAME
{
  LPBYTE  MacHeader;
  LPETHERNET  Ethernet;
  LPTOKENRING Tokenring;
  LPFDDI Fddi;
} MACFRAME;

typedef MACFRAME *LPMACFRAME;

Members

MacHeader
Generic pointer to a frame.
Ethernet
Ethernet pointer to a frame.
Tokenring
Token ring pointer to a frame.
Fddi
FDDI pointer to a frame.

Remarks

This structure is most frequently used as an overlay. To make the properties of the first protocol accessible, cast the frame as the same type as the protocol.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.


ENTRYPOINTS

The ENTRYPOINTS structure defines the entry points to the export functions that Network Monitor uses to operate the parser.

typedef struct __ENTRYPOINTS

{
  REGISTER Register;
  DEREGISTER Deregister
  RECOGNIZEFRAME RecognizeFrame;
  ATTACHPROPERTIES AttachProperties;
  FORMATPROPERTIES FormatProperties;
} ENTRYPOINTS;

typedef ENTRYPOINTS *LPENTRYPOINTS;

Members

Register
Pointer to the implementation of the Register export function.
Deregister
Pointer to the implementation of the Deregister export function.
RecognizeFrame
Pointer to the implementation of the RecognizeFrame export function.
AttachProperties
Pointer to the implementation of the AttachProperties export function.
FormatProperties
Pointer to the implementation of the FormatProperties export function.

Remarks

The CreateProtocol function uses the ENTRYPOINTS structure to provide pointers to Network Monitor. The pointers must be specified in the order identified in the previous Members section. For example, Register, Deregister, and so on.

The FormatProperties function does not need to be implemented if Network Monitor will never display the protocol data. For example, FormatProperties does not need to be implemented if an export application uses the output from the parser, and Network Monitor does not display the output.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
How to implement DllMain — includes an example. | Implementing DllMain

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

AttachProperties, CreateProtocol, Deregister, FormatProperties, RecognizeFrame, Register


PF_FOLLOWENTRY

The PF_FOLLOWENTRY structure defines a protocol that Network Monitor adds to the follow set of a parser.

typedef struct _PF_FOLLOWENTRY
{
  char szProtocol[MAX_PROTOCOL_NAME_LEN];

} PF_FOLLOWENTRY;
typedef PF_FOLLOWENTRY* PPF_FOLLOWENTRY;

Members

szProtocol[MAX_PROTOCOL_NAME_LEN]
The name of the protocol.

Remarks

The PF_FOLLOWSET structure uses an array of PF_FOLLOWENTRY structures.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.

See Also

PF_FOLLOWSET


PF_FOLLOWSET

The PF_FOLLOWSET structure defines the protocols that may precede or follow a protocol.

typedef struct _PF_FOLLOWSET
{
  DWORD           nEntries;
  PF_FOLLOWENTRY  Entry[0];

} PF_FOLLOWSET;
typedef PF_FOLLOWSET* PPF_FOLLOWSET;

Members

nEntries
Number of protocols in the list.
Entry[0]
Array of PF_FOLLOWENTRY structures that describe each protocol.

Remarks

The PF_PARSERINFO structure uses the PF_FOLLOWSET structure to list the protocols that may precede or follow the protocol that the parser detects.

Network Monitor uses the information in the PF_FOLLOWSET structure to update the follow sets of specific parsers. The PF_FOLLOWSET structure must be allocated using HeapAlloc.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.

See Also

PF_FOLLOWENTRY, PF_PARSERINFO


PF_HANDOFFENTRY

The PF_HANDOFFENTRY structure defines a protocol that Network Monitor adds to the handoff set of a parser.

typedef struct _PF_HANDOFFENTRY
{
  char  szIniFile[MAX_PATH];
  char  szIniSection[MAX_PATH];
  char  szProtocol[MAX_PROTOCOL_NAME_LEN];
  DWORD dwHandOffValue;
  PF_HANDOFFVALUEFORMATBASE ValueFormatBase;

} PF_HANDOFFENTRY;
typedef PF_HANDOFFENTRY* PPF_HANDOFFENTRY;

Members

szIniFile[MAX_PATH]
Name of the INI file associated with the protocol.
szIniSection[MAX_PATH]
Section label within the INI file.
szProtocol[MAX_PROTOCOL_NAME_LEN]
Name of the protocol.
dwHandOffValue
Value associated with the protocol.
ValueFormatBase
Numeric base of the protocol value that is specified in dwHandOffValue. The ValueFormatBase function must be set to one of the following:
HANDOFF_VALUE_FORMAT_BASE_UNKNOWN
HANDOFF_VALUE_FORMAT_BASE_DECIMAL
HANDOFF_VALUE_FORMAT_BASE_HEX

Remarks

An array of the PF_HANDOFFENTRY structures is used in the PF_HANDOFFSET structure.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.

See Also

PF_HANDOFFSET


PF_HANDOFFSET

The PF_HANDOFFSET structure defines the protocols that hand off to the parser, or the protocols that the parser hands off to.

typedef struct _PF_HANDOFFSET
{
  DWORD  nEntries;
  PF_HANDOFFENTRY  Entry[0];
} PF_HANDOFFSET;
typedef PF_HANDOFFSET* PPF_HANDOFFSET;

Members

nEntries
Number of protocols.
Entry[0]
An array of PF_HANDOFFENTRY structures that define each protocol.

Remarks

The PF_PARSERINFO structure uses the PF_HANDOFFSET structure to list the following:

  • Which protocols hand off to the parser.
  • Which protocols the parser hands off to.

The PF_HANDOFFSET structure must be allocated using HeapAlloc.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.

See Also

PF_PARSERINFO, PF_HANDOFFENTRY


PF_PARSERDLLINFO

The PF_PARSERDLLINFO structure defines the parsers located in the parser DLL.

typedef struct _PF_PARSERDLLINFO
{
  DWORD nParsers;
  PF_PARSERINFO ParserInfo[0];
} PF_PARSERDLLINFO;
typedef PF_PARSERDLLINFO* PPF_PARSERDLLINFO;

Members

nParsers
Number of parsers in the parser DLL.
ParserInfo[0]
Array of PF_PARSERINFO structures that describe each parser in the parser DLL.

Remarks

The PF_PARSERDLLINFO structure is returned by the ParserAutoInstallInfo export function that is implemented in the parser DLL. The ParserAutoInstallInfo function identifies the number of parsers in the DLL, and uses an array of PF_PARSERINFO structures to describe each parser.

The PF_PARSERDLLINFO structure must be allocated using HeapAlloc.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
Which entry points are included in the parser DLL. | Parser DLL Architecture
How to implement ParserAutoInstallInfo — includes an example. | Implementing ParserAutoIstallInfo

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.

See Also

PF_PARSERINFO, ParserAutoInstallInfo


PF_PARSERINFO

The PF_PARSERINFO structure defines one parser at a time. In the PF_PARSERINFO structure, a parser is defined by the information about the protocol that the parser detects.

typedef struct _PF_PARSERINFO
{
  char szProtocolName[MAX_PROTOCOL_NAME_LEN];
  char szComment[MAX_PROTOCOL_COMMENT_LEN];
  char szHelpFile[MAX_PATH];
  PF_FOLLOWSET pWhoCanPrecedeMe;
  PF_FOLLOWSET pWhoCanFollowMe;
  PF_HANDOFFSET pWhoHandsOffToMe;
  PF_HANDOFFSET pWhoDoIHandOffTo;
} PF_PARSERINFO;
typedef PF_PARSERINFO* PPF_PARSERINFO;

Members

szProtocolName[MAX_PROTOCOL_NAME_LEN]
Name of the protocol that the parser detects.
szComment[MAX_PROTOCOL_COMMENT_LEN]
Brief description of the protocol.
szHelpFile[MAX_PATH]
Name of the protocol Help file, if any.
pWhoCanPrecedeMe
Pointer to a PF_FOLLOWSET structure that lists the protocols that can precede the protocol the PF_PARSERINFO structure describes. Network Monitor adds the parser protocol to the follow set of all the protocols in the set.
pWhoCanFollowMe
Pointer to a PF_FOLLOWSET structure that lists the protocol that can follow the protocol the PF_PARSERINFO structure describes. Network Monitor adds the protocols of the set to the follow set of the parser protocol.
pWhoHandsOffToMe
Pointer to a PF_HANDOFFSET structure that hands-off to the protocol that the PF_PARSERINFO structure describes. Network Monitor adds the parser protocol to the handoff sets of all the protocols in the set.
pWhoDoIHandOffTo
Pointer to a PF_HANDOFFSET structure that lists the protocols that the parser protocol hands off to. Network Monitor adds the protocols of this set to the handoff set of the parser protocol.

Remarks

The PF_PARSERINFO structure is used in the PF_PARSERDLLINFO structure to provide a description of a parser. Network Monitor uses the parser description to update the Parser.ini file, and the INI files of the parsers that precede and follow the protocol described in the PF_PARSERINFO structure.

A follow set specifies the protocols that follow a protocol. Network Monitor uses a follow set when the parser cannot identify the next protocol from the data in a protocol instance. A follow set is stored in the Parser.ini file. When the parser is installed for the first time, Network Monitor updates the follow set of the parser protocols that are listed in pWhoCanPrecedeMe and pWhoCanFollowMe.

A handoff set specifies the protocols that follow a protocol. The parser uses a handoff set only when the parser can identify the next protocol from the data in a protocol instance. A handoff set is stored in the INI files of each parser. When the parser is installed for the first time, Network Monitor updates the handoff set of the parser protocols that are listed in pWhoHandsOffToMe and pWhoDoIHandOffTo.

For information on | See
What parsers are, and how they work with Network Monitor. | Parsers
What follow sets contain. | Specifying a Follow Set
What handoff sets contain. | Specifying a Handoff Set
What entry points are included in the parser DLL. | Parser DLL Architecture
How to implement ParserAutoInstallInfo — includes an example. | Implementing ParserAutoInstallInfo

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Parser.h.

See Also

ParserAutoInstallInfo, PF_FOLLOWSET, PF_HANDOFFSET, PF_PARSERDLLINFO


LABELED_BIT

The LABELED_BIT structure defines a label BIT pair.

typedef struct _LABELED_BIT
{
  BYTE BitNumber;
  LPSTR LabelOff;
  LPSTR LabelOn;
} LABELED_BIT;

typedef LABELED_BIT *LPLABELED_BIT;

Members

BitNumber
BIT number of the label BIT pair. Values range from 0 to 255. Set the Bitnumber member to the BIT used in the comparison of the property value.
LabelOff
String or label that is displayed when the BIT specified in BitNumber equals zero. For example, a possible label is "Bit OFF".
LabelOn
String or label that is displayed when the BIT specified in BitNumber equals 1. For example, a possible label is "Bit ON".

Remarks

An array of LABELED_BIT structures is used to define a set of label BIT pairs. A pointer to the array is specified in the lpLabeledBit member of the SET structure. The pairs are used when you want to display a label based on the setting of each BIT. Typically, this type of set is used to indicate the ON or OFF value of BITs.

When a BIT set is specified, Network Monitor displays only the BITs included in the array of SET structures. BITs that are not in the SET structure are not displayed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

SET


LABELED_BYTE

The LABELED_BYTE structure defines a labeled BIT pair. The Label of the labeled BIT pair is displayed when a specific byte property value is detected.

typedef struct _LABELED_BYTE
{
  BYTE Value;
  LPSTR Label;
} LABELED_BYTE;

typedef LABELED_BYTE  *LPLABELED_BYTE;

Members

Value
BYTE value of the property that you want to detect.
Label
Textual description or label that is displayed when the value specified in the Value member is detected.

Remarks

The lpLabeledByteTable member of the SET structure points to an array of SET structures that define one or more Label members of the BYTE value pairs. These pairs are used when you want to display a label in place of a specific BYTE value that is found in the protocol packet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

SET


LABELED_DWORD

The LABELED_DWORD structure defines a label that is displayed when a specific DWORD property value is detected.

typedef struct _LABELED_DWORD
{
  DWORD Value;
  LPSTR Label;
} LABELED_DWORD;

typedef LABELED_DWORD *LPLABELED_DWORD;

Members

Value
DWORD value of the property that you want to detect.
Label
Textual description or label that is displayed when the DWORD value specified in the Value member is detected.

Remarks

The lpLabeledDwordTable member of the SET structure points to an array of SET structures that define one or more Label members of the DWORD value pairs. The pairs are used when you want to display a label in place of a specific DWORD value that is found in the protocol packet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

SET


LABELED_LARGEINT

The LABELED_LARGEINT structure defines a label that is displayed when a specific LARGEINT property value is detected.

typedef struct _LABELED_LARGEINT
{
  LARGE_INTEGER Value;
  LPSTR Label;
} LABELED_LARGEINT;

typedef LABELED_LARGEINT  *LPLABELED_LARGEINT;

Members

Value
LARGEINT value of the property that you want to detect.
Label
Textual description or label that is displayed when the LARGEINT value specified in the Value member is detected.

Remarks

The lpLabeledLargeIntTable member of the SET structure points to an array of SET structures that define one or more Label members of the LARGEINT value pairs. The pairs are used when you want to display a label in place of a specific LARGEINT value that is found in a protocol packet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

SET


LABELED_SYSTEMTIME

The LABELED_SYSTEMTIME structure defines a label that is displayed when a specific SYSTEMTIME property value is detected.

typedef struct _LABELED_SYSTEMTIME
{
  SYSTEMTIME Value;
  LPSTR Label;
} LABELED_SYSTEMTIME;

typedef LABELED_SYSTEMTIME  *LPLABELED_SYSTEMTIME;

Members

Value
SYSTEMTIME value of a property that you want to detect.
Label
Textual description or label that is displayed when the SYSTEMTIME value specified in the Value member is detected.

Remarks

The lpLabeledSystemTimeTable member of the SET structure points to an array of SET structures that define one or more label value pairs. The pairs are used when you want to display a label in place of a specific LARGEINT value that is found in the protocol packet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

SET


LABELED_WORD

The LABELED_WORD structure defines a label that is displayed when a specific WORD property value is detected.

typedef struct _LABELED_WORD {
  WORD Value;
  LPSTR Label;
} LABELED_WORD;

typedef LABELED_WORD  *LPLABELED_WORD;

Members

Value
WORD value of the property that you want to detect.
Label
Textual description or label that is displayed when the WORD value specified in the Value member is detected.

Remarks

The lpLabeledWordTable member of the SET structure points to an array of SET structures to define one or more label value pairs. These pairs are used when you want to display a label in place of a specific WORD value that is found in a protocol packet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

SET


LARGEINT

The LARGEINT structure defines a LARGEINT value.

typedef struct _LARGEINT
{
  ULONG LowLong;
  LONG HighLong;
} LARGEINT;

typedef LARGE_INTEGER *LPLARGEINT;

Members

LowLong
Specifies the low-order 32 bits.
HighLong
Specifies the high-order 32 bits.

Remarks

The lpLargeIntTable member of the SET structure points to an array of SET structures that define one or more LARGEINT values. When this type of SET structure is specified, Network Monitor displays one of the following labels with each LARGEINT value that it finds in the protocol packet.

  • Matches set value. The LARGEINT value is included in the set.
  • Unknown set value. The LARGEINT value is not included in the set.

The SET structure is based on the LARGE_INTEGER structure specified in winnt.h.

See Also

SET


PROPERTYINFO

The PROPERTYINFO data structure defines one property of the protocol.

typedef struct _PROPERTYINFO
{
  HPROPERTY hProperty;
  DWORD Version;
  LPSTR Label;
  LPSTR Comment;
  BYTE DataType;
  BYTE DataQualifier;

  union
  {
      LPVOID lpExtendedInfo;
      LPRANGE lpRange;
      LPSET lpSet;
      DWORD Bitmask;
      DWORD Value;
  };

  WORD FormatStringSize;
  LPVOID InstanceData;
} PROPERTYINFO;

typedef PROPERTYINFO *LPPROPERTYINFO;

Members

hProperty
Set this field to zero. On output, Network Monitor returns a handle to the property after the property is added to the property database.
Version
Reserved. Must be set to zero.
Label
Name of the property.
Comment
Description of the property. The description appears on the Network Monitor status bar.
DataType
Data type of the property. This member can have one of the following values.
PROP_TYPE_VOID
Property type is unknown. There is no implied length or format.
PROP_TYPE_SUMMARY
Summarizing property type. Indicates the first property instance that the parser attaches to a frame. PROP_TYPE_SUMMARY can serve as a placeholder for groups of properties. This value indicates that the property is not defined in the protocol RFC.
PROP_TYPE_BYTE
Numeric data with a size of one byte (8-bit entity).
PROP_TYPE_WORD
Numeric data with a size of two bytes (16-bit entity).
PROP_TYPE_DWORD
Numeric data with a size of four bytes (32-bit entity).
PROP_TYPE_LARGEINT
Numeric data with a size of eight bytes (64-bit entity).
PROP_TYPE_ADDR
MAC address (6-byte entity).
PROP_TYPE_TIME
SYSTEMTIME structure.
PROP_TYPE_STRING
ASCII text data. This data type is not NULL-terminated.

For Unicode data, when ASCII text data is specified, the IFLAG_UNICODE flag must also be set when the attach property instance function is called.

PROP_TYPE_IP_ADDRESS
IP Address. (4-byte entity).
PROP_TYPE_IPX_ADDRESS
IPX Address. (10-byte entity).
PROP_TYPE_BYTESWAPPED_WORD
Obsolete. For byte-swapped WORD data, set DataType to PROP_TYPE_WORD and set the IFLAG_SWAPPED flag when calling an Attach property instance function.
PROP_TYPE_BYTESWAPPED_DWORD
Obsolete. For byte-swapped DWORD data, set DataType to PROP_TYPE_DWORD and set the IFLAG_SWAPPED flag when calling an Attach property instance function.
PROP_TYPE_TYPED_STRING
Obsolete. For variable-type string data, set DataType to PROP_TYPE_STRING and set the IFLAG_UNICODE flag when calling an Attach property instance function.
PROP_TYPE_RAW_DATA
Raw data of unknown length and format.
PROP_TYPE_COMMENT
Same as PROP_TYPE_VOID.
PROP_TYPE_SRCFRIENDLYNAME
Address of source-friendly name. Network Monitor does not provide built-in formatting support for this data type.
PROP_TYPE_DSTFRIENDLYNAME
Address of destination friendly name. Network Monitor does not provide built-in formatting support for this data type.
PROP_TYPE_TOKENRING_ADDRESS
Token-ring address. Network Monitor does not provide built-in formatting support for this data type.
PROP_TYPE_FDDI_ADDRESS
FDDI address. Network Monitor does not provide built-in formatting support for this data type.
PROP_TYPE_ETHERNET_ADDRESS
Ethernet address. Network Monitor does not provide built-in formatting support for this data type.
PROP_TYPE_OBJECT_IDENTIFIER
BER-encoded SNMP object identifier.
PROP_TYPE_VINES_IP_ADDRESS
Vines IP address (6-byte entity).
PROP_TYPE_VAR_LEN_SMALL_INT
Numeric value without a pre-determined length, but no more than 8 bytes long. The length of the attached data determines the length of the value.
DataQualifier
The data qualifier of a property. This member provides precise information about the data type.

DataQualifier can have one of the following values.

PROP_QUAL_NONE
The property data type is the only specification of the property.

When this value is set, the union member of the structure is set to NULL, and then ignored.

PROP_QUAL_RANGE
The numeric value is expected to be within a given range. Define the range in the lpRange member.
PROP_QUAL_SET
The value of a property is compared to a set of values that are specified in the lpSet member of the structure's union. The value of a property can be a BYTE, WORD, DWORD, LARGEINT or TIME.
PROP_QUAL_BITFIELD
Obsolete.
PROP_QUAL_LABELED_SET
The value of a property is compared to a value in a set of value label pairs. The value label pairs are specified in the lpSet member of the structure's union.

At display time, if the value of the property matches a value in the set, then both a value, and the associated label are displayed.

PROP_QUAL_LABELED_BITFIELD
Obsolete. Use PROP_QUAL_FLAGS instead.
PROP_QUAL_CONST
The value of a property is compared to a constant that is specified in the Value member of the union.

At display time, if the property values and constant do not match, a formatted error message appears with the value set as Normal.

PROP_QUAL_FLAGS
The value of the property is compared to specific BITs identified in the lpSet member of the union.
PROP_QUAL_ARRAY
The value of a property specifies an array of values. The length of attached data determines the length of an array.

When the PROP_QUAL_ARRAY value is set, the union member of the PROPERTYINFO data structure is set to NULL and ignored.

lpExtendedInfo
Reserved (member of union).
lpRange
Pointer to a RANGE structure that defines a range of values. This member must be set if the DataQualifier member of this structure is set to PROP_QUAL_RANGE (member of union).
lpSet
Pointer to a SET structure that specifies a set of values or labels. This member must be set if the DataQualifier member of the structure is set to PROP_QUAL_SET, PROP_QUAL_LABELED_SET, or PROP_QUAL_FLAGS (member of union).
Bitmask
Obsolete (member of union).
Value
Constant value used when the DataQualifier is set to PROP_QUAL_CONST (member of union).
FormatStringSize
Maximum size used only for the property description.
InstanceData
Specify the format function that is called to format the displayed data for the property. To use the generic formatter, specify the FormatPropertyInstance function.

Remarks

The PROPERTYINFO structure is used in calls to the AddProperty function. The AddProperty function adds a single property definition to the parser property database.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

AddProperty, RANGE, SET


PROPERTYINST

The PROPERTYINST structure defines an instance of a property in a piece of recognized data. Network Monitor allocates and fills in a PROPERTYINST structure when a property is attached to the capture.

typedef struct _PROPERTYINST
{
  LPPROPERTYINFO lpPropertyInfo;
  LPSTR szPropertyText;

  union
  {
      LPVOID lpData;
      LPBYTE lpByte;
      ULPWORD lpWord;
      ULPDWORD lpDword;

      ULPLARGEINT lpLargeInt;
      ULPSYSTEMTIME lpSysTime;
      LPPROPERTYINSTEX lpPropertyInstEx;
  };

  WORD DataLength;
  WORD Level   : 4;
  WORD HelpID  : 12;
} PROPERTYINST;

Members

lpPropertyInfo
Pointer to the PROPERTYINFO structure that defines the property.
szPropertyText
Pointer to a string that is displayed in the details pane of the Network Monitor UI.
lpData
Pointer to the start of the data for the property. The parser determines where the property data starts.
lpByte
Pointer to the BYTE data.
lpWord
Pointer to the WORD data.
lpDword
Pointer to the DWORD data.
lpLargeInt
Pointer to the LARGEINT data.
lpSysTime
Pointer to the SYSTEMTIME data.
lpPropertyInstEx
Pointer to a PROPERTYINSTEX structure. The lpPropertyInstEx member is used only when you call AttachPropertyInstanceEx.

If lpPropertyInstEx is used, you must set the DataLength member to 0xFFFF.

DataLength
Data length for this instance of the property. If the lpPropertyInstEx member points to a PROPERTYINSTEX structure, you must set the DataLength to 0xFFFF.
fError
Error condition flag.
Level
Level information.
HelpID
Help file context identifier.

Remarks

The PROPERTYINST structure defines an instance of an attached property. The parser accesses the PROPERTYINST structure through several helper functions. For example, when the FormatPropertyInstance function is called to format the data of a property, it modifies the szPropertyText member of the PROPERTYINST structure.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

AttachPropertyInstance, AttachPropertyInstanceEx


PROPERTYINSTEX

The PROPERTYINSTEX structure defines a freeform, extended property instance.

typedef struct _PROPERTYINSTEX
{
  WORD Length;
  WORD LengthEx;
  ULPVOID lpData;
  union
  {
    BYTE Byte[];
    WORD Word[];
    DWORD Dword[];
    LARGE_INTEGER LargeInt [];
    SYSTEMTIME SysTime[];
    TYPED_STRING TypedString;
  };
} PROPERTYINSTEX;

Members

Length
Length of the data in Bytes.
LengthEx
Length of the extended data.
lpData
Pointer to the extended data.
Byte
Pointer to the BYTE data.
Word
Pointer to the WORD data.
Dword
Pointer to the DWORD data.
Largeint
Pointer to the LARGEINT data.
SysTime
Pointer to the SYSTEMTIME data.
TypedString
A typed string that may have extended data.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.


PROTOCOLINFO

The PROTOCOLINFO structure describes a protocol.

typedef struct _PROTOCOL INFO

{
  DWORD ProtocolID;
  LPPROPERTYDATABASE PropertyDatabase;
  BYTE ProtocolName[16];
  BYTE HelpFile[16];
  BYTE Comment[128];
} PROTOCOLINFO;

typedef PROTOCOLINFO *LPPROTOCOLINFO;

Members

ProtocolID
System-assigned protocol identifier of the specified run session.
PropertyDatabase
Property database of the specified protocol.
ProtocolName
Abbreviated protocol name.
HelpFile
Optional Help file name associated with the protocol.
Comment
A comment describing the protocol.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.


RANGE

The RANGE structure defines a range of valid property values.

typedef struct range
{
  DWORD MinValue;
  DWORD MaxValue;
} RANGE;

typedef RANGE *LPRANGE;

Members

MinValue
Lowest possible value in a range.
MaxValue
Highest possible value in a range.

Remarks

The RANGE structure is used to specify a valid range of numbers for a protocol property. If the DataQualifier member of the PROPERTYINFO structure is set to PROP_QUAL_RANGE, the lpRange member of the PROPERTYINFO structure must provide a pointer to a RANGE structure.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Bhtypes.h.

See Also

PROPERTYINFO


SET

The SET structure defines a set of values.

typedef struct _SET
{
  DWORD nEntries;

  union
  {
      //... set of labeled values
      LPBYTE                lpByteTable;
      LPWORD                lpWordTable;
      LPDWORD               lpDwordTable;
      LPLARGEINT            lpLargeIntTable;
      LPSYSTEMTIME          lpSystemTimeTable;
      LPLABELED_BYTE        lpLabeledByteTable;
      LPLABELED_WORD        lpLabeledWordTable;
      LPLABELED_DWORD       lpLabeledDwordTable;
      LPLABELED_LARGEINT    lpLabeledLargeIntTable;
      LPLABELED_SYSTEMTIME  lpLabeledSystemTimeTable;
      LPLABELED_BIT         lpLabeledBit;
      LPVOID                lpVoidTable;

  };
} SET;

typedef SET *LPSET;

Members

nEntries
Total number of entries in a set.
lpByteTable
Pointer to an array of BYTE values.
lpWordTable
Pointer to an array of WORD values.
lpDwordTable
Pointer to an array of DWORD values.
lpLargeIntTable
Pointer to an array of LARGEINT structures.
lpSystemTimeTable
Pointer to an array of SYSTEMTIME values.
lpLabeledByteTable
Pointer to an array of LABELED_BYTE structures. Each LABELED_BYTE structure defines a value and label. Network Monitor displays a label if it finds a corresponding value in the protocol packet.
lpLabeledWordTable
Pointer to an array of LABELED_WORD structures that define a set of WORD values and labels.
lpLabeledDwordTable
Pointer to an array of LABELED_DWORD structures that define a set of DWORD values and labels.
lpLabeledLargeIntTable
Pointer to an array of LABELED_LARGEINT structures that define a set of LARGEINT values and labels.
lpLabeledSystemTimeTable
Pointer to an array of LABELED_SYSTEMTIME structures that define a set of SYSTEM values and labels.
lpLabeledBit
Pointer to an array of LABELED_BIT structures that define a set of labeled BIT pairs. Each BIT can specify two labels — one label for each state (0 or 1) of the BIT.
lpVoidTable
Pointer to an array of values.

Remarks

The SET structure is used to define a set of comparison data that Network Monitor can use to interpret the value of a property in a protocol packet. When a set of comparison data is required, a pointer to the SET structure is specified in the lpSet member of the PROPERTYINFO structure.

The parser DLL can provide a value set and a label set. The member of the UNION that you select in a SET structure points to an array of structures that define each member of a set.

  • Value set

    A value set is used when you want Network Monitor to include an in-set or not-in-set indicator with the value found in the protocol packet. For example, if a DWORD set is specified, Network Monitor displays a label for each DWORD value found in the protocol packet, indicating that the DWORD is or is not specified in the set.

    A value set can be based on BYTE, WORD, DWORD, LARGEINT, and SYSTEMTIME data types.

  • Label set

    A label set is used when you want Network Monitor to display a user-defined label instead of the property values specified in a set.

    A label set can be based on BYTE, WORD, DWORD, LARGEINT, SYSTEMTIME and BIT label pairs.

See Also

LABELED_BIT, PROPERTYINFO


NPP Interfaces

Network packet providers (NPPs) provide COM interfaces that are called by monitors, NPP applications, and Network Monitor. When you call CreateNPPInterface, remember that each NPP is represented as a single in-process COM object. Applications can instantiate any number of NPP objects. However, each instantiated object must use one—and only one—of the five NPP interfaces.

Note also that different NPP interfaces provide network data in various forms. For example, Network Monitor uses the IDelaydC interface to capture network traffic and save it to a capture file; while monitors use the IRTC interface to capture real time network traffic. The following table describes Network Monitor NPP interfaces.

Interface | Description
IDelaydC | Captures network traffic that is stored in a capture file. This interface is used by Network Monitor and NPP applications.
IESP | Captures network traffic that is stored in a capture file and provides enhanced statistics in a special ESP file format. This interface is used by NPP applications
IRTC | Captures real time network traffic and triggers events when they occur. This interface is used by monitors and NPP applications.
IStats | Retrieves statistics as raw data rather than frames. This interface is used by NPP applications such as Perfmon.


IDelaydC

The IDelaydC interface provides the methods used to connect to the network, capture network traffic to a capture file, retrieve statistics, and disconnect from the network.

This interface captures frames from the network data stream and then copies the frames to a capture file. This interface is used by Network Monitor and NPP applications. To receive the network data, the targeted NIC must support promiscuous mode.

Methods in Vtable Order

IDelaydC methods | Description
Connect | Connects the NPP to the network.
Disconnect | Disconnects the NPP from the network.
QueryStatus | Retrieves the status of the NPP.
Configure | Submits configuration information used for a capture.
Start | Starts a capture and creates the capture file.
Pause | Temporarily stops the current capture.
Resume | Resumes a paused capture.
Stop | Stops the current capture and closes the capture file.
GetTotalStatistics | Extracts time, buffer, driver, and other network statistics from the currently running capture.
GetConversationStatistics | Retrieves session and station information for the current capture.
GetControlState | Retrieves the state of the capture, which indicates if the capture is running or paused.
QueryStations | Retrieves a list of all computers that use Network Monitor to capture data on a subnet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.


IDelaydC::Configure

The Configure method submits configuration information used for a capture.

HRESULT STDMETHODCALLTYPE Configure(
  HBLOB hConfigurationBlob,
  HBLOB hErrorBlob
);

Parameters

hConfigurationBlob
[in] Handle to the BLOB that contains the configuration information.
hErrorBlob
[out] Handle to an error BLOB that contains additional error information. For information about the contents of an error BLOB, see the Remarks section in this topic .

Remarks

You must apply this method to restart an NPP that has been started, stopped, but not disconnected.

The error BLOB returned by hErrorBlob contains entries that Network Monitor could not understand or find in the configuration BLOB specified in hConfigurationBlob. The returned error BLOB contains error information that the application can use for troubleshooting. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry Network Monitor could not find is included in the returned error BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::Start, IDelaydC::Stop


IDelaydC::Connect

The Connect method connects the NPP to the network by using a specified network interface card and provides configuration information about the connection.

HRESULT STDMETHODCALLTYPE Connect(
  HBLOB  hInputBlob,
  LPVOID StatusCallbackProc,
  LPVOID UserContext,
  HBLOB hErrorBlob
);

Parameters

hInputBlob
[in] Handle to the BLOB that specifies the NIC that you are connecting to and the configuration information about that connection.
StatusCallbackProc
[in] Address of the user's callback function, which is used to receive status updates such as triggers. If no callback function is used, set this parameter and the UserContext parameter to NULL.
UserContext
[in] Value passed when the user's callback function is called. The value of this parameter is typically either HWND or a 'this' pointer. If a callback function is not specified, set this parameter and the StatusCallbackProc parameter to NULL.
hErrorBlob
[out] Handle to an error BLOB that contains additional error information.

Return Values

If this method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

Error codes returned by the Connect method include those errors returned by the internal IDelaydC::Configure call.

NMERR_ALREADY_CONNECTED
This instance of the NPP COM object is already connected to the network.
NMERR_BLOB_CONVERSION_ERROR
The configuration BLOB is corrupt. This error is generated by the IDelaydC::Configure call.
NMERR_BLOB_ENTRY_DOES_NOT_EXIST
The input BLOB specified by hInputBlob is missing an entry needed to perform this operation. This error may be generated by the IDelaydC::Connect or IDelaydC::Configure call. Look at the error BLOB returned by hErrorBlob to determine which entry was not found.
NMERR_BLOB_NOT_INITIALIZED
The CreateBlob function has not been called. This error is generated by the IDelaydC::Configure call.
NMERR_BLOB_STRING_INVALID
The string is not null-terminated. This error is generated by the IDelaydC::Configure call.
NMERR_ILLEGAL_TRIGGER
The trigger portion of the input BLOB is corrupt. This error is generated by the IDelaydC::Configure call.
NMERR_INVALID_BLOB
The object specified in hInputBlob is not a BLOB. This error is generated by the IDelaydC::Configure call.
NMERR_NO_DEFAULT_CAPTURE_DIRECTORY
The default capture directory was not set in the registry. Use the following path to set the capture directory.
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\nm\Parameters\CapturePath
NMERR_OUT_OF_MEMORY
No memory was available to perform this operation. This error is generated by the IDelaydC::Configure call.
NMERR_TIMEOUT
The request has timed out. This error is generated by the IDelaydC::Configure call.
NMERR_UPLEVEL_BLOB
The version number of the BLOB specified in hInputBlob is incorrect. This error is generated by the IDelaydC::Configure call.

Remarks

When the Connect method is called, the NPP automatically calls IDelaydC::Configure by using the BLOB provided by hInputBlob. Note that any error codes returned by the call to IDelaydC::Configure are passed back and returned by the IDelaydC::Connect call.

This method must be called before you can start capturing frames. Note that when you connect to the network by using this method, you must continue to use the IDelaydC interface methods to capture frames.

The input BLOB specified by the hInputBlob parameter can be obtained by calling GetNPPBlobFromUI, GetNPPBlobTable, and SelectNPPBlobFromTable.

The error BLOB returned in hErrorBlob contains error information that the developer or the application can use for troubleshooting. The error BLOB returned by hErrorBlob contains entries that Network Monitor could not understand or find in the input BLOB specified in hInputBlob. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry Network Monitor could not find is included in the returned error BLOB.

For information about | See
Obtaining the input BLOB that represents a NIC | Selecting a Network Interface Card

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Configure, IDelaydC::Disconnect, IDelaydC::Start


IDelaydC::Disconnect

The Disconnect method disconnects the NPP from the network.

HRESULT STDMETHODCALLTYPE Disconnect(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURING
The NPP is capturing data. You cannot disconnect the NPP from the network during a capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.

Remarks

This method cannot be called when the NPP is capturing data. You must call the IDelaydC::Stop method before calling Disconnect.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::Stop


IDelaydC::GetControlState

The GetControlState method retrieves the state of the capture, which indicates if the capture is running or paused.

HRESULT STDMETHODCALLTYPE GetControlState(
  BOOL *IsRunnning,
  BOOL *IsPaused
);

Parameters

IsRunnning
[out] Indicator that the current capture is running, including if the capture is paused.
IsPaused
[out] Indicator that the current capture is paused.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IDelaydC::Connect to connect the NPP to the network.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.

Remarks

This method can be called any time the NPP is connected to the network by using the IDelaydC interface. You can use this method to find out if a capture is running, if the capture is paused, or if the capture has been stopped but the NPP is not disconnected.

The methods used to start, pause, and, stop the capture are listed in the See Also list below.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::Pause, IDelaydC::Start, IDelaydC::Stop


IDelaydC::GetConversationStatistics

The GetConversationStatistics method retrieves session and station information about the current capture.

HRESULT STDMETHODCALLTYPE GetConversationStatistics(
  DWORD *nSessions,
  /* [size_is] */ LPSESSIONSTATS lpSessionStats,
  DWORD *nStations,
  /* [size_is] */ LPSTATIONSTATS lpStationStats,
  BOOL fClearAfterReading
);

Parameters

nSessions
[out] Number of sessions recorded for the current capture.
lpSessionStats
[out] Pointer to a SESSIONSTATS structure.
nStations
[out] Number of stations recorded for the current capture.
lpStationStats
[out] Pointer to a STATIONSTATS structure.
fClearAfterReading
[in] Flag used to tell Network Monitor to clear out the internal storage of the SESSIONSTATS and STATIONSTATS structures after it retrieves the current information.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IDelaydC::Connect to connect the NPP to the network.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IDelaydC::Start to start the capture.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.
NMERR_NO_CONVERSATION_STATS
The configuration for this connection is set to not save conversation statistics. To save conversation statistics, stop the capture, set NoConversationStats = YES in the configuration BLOB, and then restart the capture.

Remarks

This method can only be called only while data capture is in progress; when the current capture is paused, calls to this method will not succeed. To start a capture, call the IDelaydC::Start method.

To retrieve other types of statistics, call IDelaydC::GetTotalStatistics.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::GetTotalStatistics, IDelaydC::Start, SESSIONSTATS, STATIONSTATS


IDelaydC::GetTotalStatistics

The GetTotalStatistics method retrieves the total statistics for the current capture.

HRESULT STDMETHODCALLTYPE GetTotalStatistics(
  LPSTATISTICS lpStats,
  BOOL fClearAfterReading
);

Parameters

lpStats
[out] Pointer to a STATISTICS structure that provides the total statistics for the capture. It is the caller's responsibility to allocate and free the memory used by the STATISTICS structure.
fClearAfterReading
[in] Flag used to tell Network Monitor how to handle the internal storage of the total statistics. A setting of TRUE tells Network Monitor to clear out the internal storage of the total statistics after the current information is retrieved.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IDelaydC::Connect to connect to the network.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IDelaydC::Start to start capturing data.

Remarks

This method returns data only while a capture is in progress; when the capture is paused, calls to this method will not succeed.

Network Monitor also stores conversation statistics, which can be retrieved by calling the IDelaydC::GetConversationStatistics method.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::GetConversationStatistics, IDelaydC::Start, STATISTICS


IDelaydC::Pause

The Pause method pauses the current capture.

HRESULT STDMETHODCALLTYPE Pause(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture is already in a paused state.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IDelaydC::Start to start the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IDelaydC::Connect to connect the NPP to the network.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.

Remarks

While the capture is in a paused state, new data is not added to the current capture file until the IDelaydC::Resume method is called to restart the capture. When Pause and Resume are used to stop and restart the capture, all captured information is put in the same capture file.

When using IDelaydC::Pause and IDelaydC::Resume to control the capture, Network Monitor continues to add conversation statistics whenever the capture is running.

To restart the capture, call IDelaydC::Resume.

To stop the capture, call IDelaydC::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::Resume, IDelaydC::Start, IDelaydC::Stop


IDelaydC::QueryStations

The QueryStations method provides a list of all computers that are currently using Network Monitor to capture data.

HRESULT STDMETHODCALLTYPE QueryStations(
  QUERYTABLE *lpQueryTable
);

Parameters

lpQueryTable
[in, out] Pointer to a QUERYTABLE structure. On input, this structure must contain the maximum number of computers you want Network Monitor to return and an array of STATIONQUERY structures.

On output, this structure returns the number of computers that are capturing data and a STATIONQUERY structure for each computer found. Note that this list might include computers using versions of Network Monitor that predate version 2.0.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_OUT_OF_MEMORY
No memory was available to process this query.

Remarks

This method can be called at any time after CreateNPPInterface is called. A call to this method is a synchronous call, which may take several seconds to complete as Network Monitor waits for remote computers to respond to the query. Only computers on the local subnet can be queried.

It is your responsibility to allocate the memory for the QUERYTABLE structure and free that memory after the table is no longer needed. This requirement includes the memory needed for the STATIONQUERY array used in QUERYTABLE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

QUERYTABLE, STATIONQUERY


IDelaydC::QueryStatus

The QueryStatus method retrieves the status of the NPP.

HRESULT STDMETHODCALLTYPE QueryStatus(
  NETWORKSTATUS *pNetworkStatus
);

Parameters

pNetworkStatus
[out] Pointer to a returned NETWORKSTATUS structure that indicates the current state (capturing, paused, stopped, and so on) of the NPP. It is your responsibility to allocate and free the memory associated with the NETWORKSTATUS structure.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_INVALID_PARAMETER
The pNetworkStatus parameter is not pointing to a valid NETWORKSTATUS structure. Allocate memory for this structure and call the IDelaydC::QueryStatus method again.

Remarks

This method can be called at any time after CreateNPPInterface is called. It can be called to see if the NPP is connected to the network, to find out the status of the current capture, and to see if any triggers are pending.

Before calling this method, you must allocate the memory needed for the NETWORKSTATUS structure and free that memory when the structure is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

CreateNPPInterface, NETWORKSTATUS


IDelaydC::Resume

The Resume method restarts a paused capture.

HRESULT STDMETHODCALLTYPE Resume(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_NOT_PAUSED
The capture is not paused. Call IDelaydC::Pause to pause the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IDelaydC::Connect to connect the NPP to the network.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.

Remarks

While the capture is paused, new data is not added to the current capture file until the IDelaydC::Resume method is called to restart the capture. When Pause and Resume are used to stop and restart the capture, all captured information is put in the same capture file.

When using Pause and Resume to control the capture, Network Monitor continues to add conversation statistics to the existing statistics for the current capture.

To stop the capture, call IDelaydC::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::Pause, IDelaydC::Stop


IDelaydC::Start

The Start method starts a capture.

HRESULT STDMETHODCALLTYPE Start(
  char *pFileName
);

Parameters

pFileName
[out] Pointer to the name of the capture file used to store the network data. Be sure to cache this file name if it is needed for future reference.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture is in a paused state and must be stopped before it can be restarted. Call IDelaydC::Stop to stop the capture. For more information, see the Remarks section in this topic.
NMERR_CAPTURING
The capture is already started.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IDelaydC::Connect to connect to the network.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.

Remarks

The location of the capture file is specified in your Windows registry, but you can use Network Monitor to change the file's location.

To restart the capture by using IDelaydC::Start and IDelaydC::Stop, you must call the IDelaydC::Configure method to reconfigure the connection each time you call the IDelaydC::Start method to restart capturing data. When you start and stop the capture with these three methods, a new capture file is created each time the capture is started.

Note You can also start and stop the capture by using the IDelaydC::Pause and IDelaydC::Resume methods. When you use these two methods, the captured data is stored in the same capture file.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Configure, IDelaydC::Connect, IDelaydC::Pause, IDelaydC::Resume, IDelaydC::Stop


IDelaydC::Stop

The Stop method stops the current capture.

HRESULT STDMETHODCALLTYPE Stop(
   LPSTATISTICS lpStats
);

Parameters

lpStats
[out] Pointer to a STATISTICS structure that contains network statistics such as total frames and total bytes captured.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IDelaydC::Connect to connect the NPP to the network.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IDelaydC::Start to start the capture.
NMERR_NOT_DELAYED
The NPP is connected to the network but not with the IDelaydC::Connect method.

Remarks

When IDelaydC::Stop is called, Network Monitor stops capturing data and closes the capture file. (The name of the capture file was returned when IDelaydC::Start was called). You can now look at the contents of the capture file.

When you stop and start the capture, make sure you call the IDelaydC::Configure method each time you call IDelaydC::Start to restart the capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IDelaydC.h.

See Also

IDelaydC::Connect, IDelaydC::Configure, IDelaydC::Start, STATISTICS


IESP

The IESP interface provides the methods that connect the NPP to the network, capture network traffic to a capture file, retrieve statistics, and disconnect the NPP from the network. This interface is used primarily when you need to collect network conversation statistics in a proprietary ESP file format.

Methods in Vtable Order

Methods | Description
Connect | Connects the NPP to the network.
Disconnect | Disconnects the NPP from the network.
QueryStatus | Retrieves the status of the NPP.
Configure | Submits configuration information for a capture
Start | Starts the capture and creates the capture file.
Pause | Temporarily stops the current capture.
Resume | Resumes a paused capture.
Stop | Stops the current capture.
GetControlState | Retrieves the state of the capture, which indicates if the capture is running or paused.
QueryStations | Retrieves a list of all computers that are using Network Monitor to capture data on a subnet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.


IESP::Configure

The Configure method submits configuration information for a capture.

HRESULT STDMETHODCALLTYPE Configure(
  HBLOB hConfigurationBlob,
  HBLOB hErrorBlob
);

Parameters

hConfigurationBlob
[in] Handle to the BLOB that the caller configures.
hErrorBlob
[out] Handle to an error BLOB that contains additional error information. For information about the contents of an error BLOB, see the Remarks section in this topic.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network.
NMERR_NOT_ESP
The NPP is connected to the network but not with the IESP::Connect method.
NMERR_CAPTURING
The NPP reports that the capture session has started.
NMERR_ILLEGAL_TRIGGER
The trigger portion of the configuration BLOB is corrupt.
NMERR_BLOB_ENTRY_DOES_NOT_EXIST
The configuration BLOB specified by hConfigurationBlob is missing an entry needed to perform this operation. Look at the error BLOB returned by hErrorBlob to determine which entry was not found.
NMERR_BLOB_CONVERSION_ERROR
The BLOB is corrupt.
NMERR_BLOB_NOT_INITIALIZED
The CreateBlob method has not been called.
NMERR_INVALID_BLOB
The object that is pointed to is not a BLOB.
NMERR_BLOB_STRING_INVALID
The string is not null-terminated.
NMERR_UPLEVEL_BLOB
The BLOB version number is incorrect.
NMERR_OUT_OF_MEMORY
No memory was available. Shut down windows to free up resources.
NMERR_TIMEOUT
The request has timed out.

Remarks

You must apply this method to restart an NPP that has been started and stopped, but not disconnected.

The error BLOB returned by the hErrorBlob parameter contains entries that Network Monitor could not understand or find in the configuration BLOB specified in hConfigurationBlob. The returned error BLOB contains error information that the application can use for troubleshooting. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry Network Monitor could not find is included in the returned error BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.


IESP::Connect

The Connect method connects the NPP to the network by using a specified NIC and provides configuration information about the connection.

HRESULT STDMETHODCALLTYPE Connect(
  HBLOB  hInputBlob,
  DWORD StatusCallbackProc,
  DWORD UserContext,
  HBLOB hErrorBlob
);

Parameters

hInputBlob
[in] Handle to the BLOB that specifies the NIC that the NPP connects to and the configuration information for that connection.
StatusCallbackProc
[in] Address of the user's callback function, which receives status updates such as triggers. If a callback function is not used, set this parameter and the UserContext parameter to NULL.
UserContext
[in] Value passed when the user's callback function is called. The value of this parameter is typically either HWND or a 'this' pointer. If a callback function is not specified, set this parameter and the StatusCallbackProc parameter to NULL..
hErrorBlob
[out] Handle to an error BLOB that contains additional error information.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

Error codes returned by the Connect method include those errors returned by the internal IESP::Configure call.

NMERR_ALREADY_CONNECTED
This instance of the NPP COM object is already connected to the network.
NMERR_BLOB_CONVERSION_ERROR
The configuration BLOB is corrupt. This error is generated by the IESP::Configure call.
NMERR_BLOB_ENTRY_DOES_NOT_EXIST
The input BLOB specified by the hInputBlob parameter lacks an entry needed to perform this operation. This error might be generated by the IESP::Connect or IESP::Configure call. Look at the error BLOB returned by hErrorBlob to determine which entry was not found.
NMERR_BLOB_NOT_INITIALIZED
The CreateBlob function has not been called. This error is generated by the IESP::Configure call.
NMERR_BLOB_STRING_INVALID
The string is not null-terminated. This error is generated by the IESP::Configure call.
NMERR_ILLEGAL_TRIGGER
The trigger portion of the input BLOB is corrupt. This error is generated by the IESP::Configure call.
NMERR_INVALID_BLOB
The object specified in hInputBlob is not a BLOB. This error is generated by the IESP::Configure call.
NMERR_NO_DEFAULT_CAPTURE_DIRECTORY
The default capture directory was not set in the registry. Use the following path to set the capture directory.
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\nm\Parameters\CapturePath
NMERR_OUT_OF_MEMORY
The memory needed to perform this operation is unavailable. This error is generated by the IESP::Configure call.
NMERR_TIMEOUT
The request has timed out. This error is generated by the IESP::Configure call.
NMERR_UPLEVEL_BLOB
The version number of the BLOB specified in hInputBlob is incorrect. This error is generated by the IESP::Configure call.

Remarks

When the Connect method is called, Network Monitor automatically calls IESP::Configure by using the BLOB provided by the hInputBlob parameter. Note that any error codes returned by the call to IESP::Configure are passed back and returned by the IESP::Connect call.

This method must be called before you can start capturing frames. Note that when you connect to the network by using this method, you must continue to use the IESP interface to capture frames.

The input BLOB specified by hInputBlob can be obtained by calling GetNPPBlobFromUI, GetNPPBlobTable, and SelectNPPBlobFromTable.

The error BLOB returned by hErrorBlob contains entries that Network Monitor could not understand or find in the input BLOB specified in hInputBlob. The returned error BLOB contains error information that the application can use for troubleshooting. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry that Network Monitor could not find is included in the returned error BLOB.

For information about | See
Obtaining the input BLOB that represents a NIC | Selecting a Network Interface Card

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

IESP::Configure, IESP::Disconnect, IESP::Start


IESP::Disconnect

The Disconnect method disconnects the NPP from the network.

HRESULT STDMETHODCALLTYPE Disconnect(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURING
The NPP is capturing data. You cannot disconnect from the network while data capture is in progress.
NMERR_NOT_CONNECTED
The NPP is not connected to the network.
NMERR_NOT_ESP
The NPP is connected to the network but not with the IESP::Connect method.

Remarks

This method cannot be called when the NPP is capturing data. You must call the IESP::Stop method before calling IESP::Disconnect.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

IESP::Connect, IESP::Stop


IESP::GetControlState

The GetControlState method retrieves the state of the capture, which indicates if the capture is running or paused.

HRESULT STDMETHODCALLTYPE GetControlState(
  BOOL *IsRunnning,
  BOOL *IsPaused
);

Parameters

IsRunnning
[out] Indicator that the current capture is running, including if the capture is paused.
IsPaused
[out] Indicator that the current capture is paused.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IESP::Connect to connect the NPP to the network.
NMERR_NOT_ESP
The NPP is connected to the network but not with the IESP::Connect method.

Remarks

This method can be called any time the NPP is connected to the network. You can use this method to find out if a capture is running, if the capture is paused, or if the capture has been stopped but the NPP is still connected.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

IESP::Connect, IESP::Pause, IESP::Start, IESP::Stop


IESP::Pause

The Pause method pauses the current capture.

HRESULT STDMETHODCALLTYPE Pause(
  LPSTATISTICS lpStats
);

Parameters

lpStats
Obsolete.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture is already paused.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IESP::Start to start the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IESP::Connect to connect the NPP to the network.
NMERR_NOT_ESP
The NPP is connected to the network but not with the IESP::Connect method.

Remarks

While the capture is in a paused state, new data is not added to the current capture file until you call the IESP::Resume method to restart the capture. When Pause and Resume are used to stop and restart the capture, all captured information is put in the same capture file.

When you use the IESP::Pause and IESP::Resume methods to control the capture, Network Monitor continues to add conversation statistics whenever the capture is running.

To restart the capture, call IESP::Resume. To stop the capture, call IESP::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

IESP::Connect, IESP::Resume, IESP::Start, IESP::Stop


IESP::QueryStations

The QueryStations method provides a list of all computers that currently use Network Monitor to capture network data.

HRESULT STDMETHODCALLTYPE QueryStations(
  QUERYTABLE *lpQueryTable
);

Parameters

lpQueryTable
[in, out] Pointer to a QUERYTABLE structure. On input, this structure must contain the maximum number of computers you want Network Monitor to return and an array of STATIONQUERY structures.

On output, this structure returns the number of computers that are capturing data and a STATIONQUERY structure for each computer found. Note that this total may include computers using versions of Network Monitor that predate version 2.0.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_OUT_OF_MEMORY
The memory needed to process this query was unavailable.

Remarks

This method can be called at any time after the CreateNPPInterface method is called. A call to this method is a synchronous call, which may take several seconds to complete as Network Monitor waits for remote computers to respond to the query. Only computers on the local subnet can be queried.

It is your responsibility to allocate the memory for the QUERYTABLE structure and free that memory after the table is no longer needed. This requirement includes the memory needed for the STATIONQUERY array used in QUERYTABLE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

QUERYTABLE, STATIONQUERY


IESP::QueryStatus

The QueryStatus method retrieves the status of the NPP.

HRESULT STDMETHODCALLTYPE QueryStatus(
  NETWORKSTATUS *pNetworkStatus
);

Parameters

pNetworkStatus
[out] Pointer to a returned NETWORKSTATUS structure that indicates the current state (capturing, paused, stopped, and so on) of the NPP. It is the your responsibility to allocate and free the memory for the NETWORKSTATUS structure.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_INVALID_PARAMETER
The pNetworkStatus parameter is not pointing to a valid NETWORKSTATUS structure. Allocate memory for this structure and call IESP::QueryStatus again.

Remarks

This method can be called at any time after the CreateNPPInterface is called. You can call this method to see if the NPP is connected to the network, to find out the status of the current capture, and to see if any triggers are pending.

Before calling this method, you must allocate the memory needed for the NETWORKSTATUS structure and free that memory when the structure is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

CreateNPPInterface, NETWORKSTATUS


IESP::Resume

The Resume method restarts a paused capture.

HRESULT STDMETHODCALLTYPE Resume(void);

Parameters

This method has no parameters.

Return Values

If the method is successful , the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_NOT_PAUSED
The capture is not paused. Call IESP::Pause to pause the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IESP::Connect to connect to the network.
NMERR_NOT_ESP
The NPP is connected to the network, but not with the IESP::Connect method.

Remarks

While the capture is in a paused state, new data is not added to the current capture file until IESP::Resume is called to restart the capture. When Pause and Resume are used to stop and restart the capture, all captured information is put in the same capture file.

When using Pause and Resume to control the capture, Network Monitor continues to add conversation statistics to the existing statistics for the current capture.

To stop the capture, call IESP::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

IESP::Connect, IESP::Pause, IESP::Stop


IESP::Start

The Start method starts a capture.

HRESULT STDMETHODCALLTYPE Start(
  char *pFileName
);

Parameters

pFileName
[out] Pointer to the name of the capture file used to store the network data. Be sure to cache this file name if it is needed for future reference.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture is paused and must be stopped before it can be restarted. Call IESP::Stop to stop the capture.
NMERR_CAPTURING
The capture is already started.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IESP::Connect to connect the NPP to the network.
NMERR_NOT_ESP
The NPP is connected to the network but not with the IESP::Connect method.

Remarks

The location of the capture file is specified in the Windows registry, but you can use Network Monitor to change the directory location.

When you restart the capture by using the IESP::Start and IESP::Stop methods, you must call the IESP::Configure method to reconfigure the connection each time you call IESP::Start to restart capturing data. When you start and stop the capture with these three methods, a new capture file is created each time the capture is started.

Note You can also start and stop the capture by using the IESP::Pause and IESP::Resume methods. When these two methods are used, the captured data is stored in the same capture file.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

IESP::Configure, IESP::Connect, IESP::Pause, IESP::Resume, IESP::Stop,


IESP::Stop

The Stop method stops the current capture.

HRESULT STDMETHODCALLTYPE Stop(
  LPSTATISTICS lpStats
);

Parameters

lpStats
[out] Pointer to a STATISTICS structure that contains network statistics such as total frames and total bytes captured.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IESP::Connect to connect the NPP to the network.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IESP::Start to start the capture.
NMERR_NOT_ESP
The NPP is connected to the network but not with the IESP::Connect method.

Remarks

When the IESP::Stop method is called, Network Monitor stops capturing data and closes the capture file. (The name of the capture file was returned when IESP::Start was called.) You can now look at the contents of the capture file.

When you stop and restart the capture, make sure to call the IESP::Configure method each time you call IESP::Start to restart the capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Iesp.h.

See Also

IESP::Connect, IESP::Start, STATISTICS


IRTC

The IRTC interface provides the methods used to connect the NPP to the network, capture network traffic to a capture file, retrieve statistics, and disconnect the NPP from the network. IRTC gets an interface to local-only entry points, which are necessary to engage in real-time capture. This interface includes a method that hands off a callback to the NPP.

Methods in Vtable Order

IRTC Methods | Description
Connect | Connects the NPP to the network.
Disconnect | Disconnects the NPP from the network.
QueryStatus | Retrieves the status of the NPP.
Configure | Sets the trigger, pattern match, and buffer size of the capture file.
Start | Starts a capture.
Pause | Temporarily stops the current capture.
Resume | Restarts a paused capture.
Stop | Stops the current capture.
GetControlState | Retrieves the state of the capture, which indicates if the capture is running or paused.
GetTotalStatistics | Extracts time, buffer, driver, and other network statistics from the currently running capture.
GetConversationStatistics | Retrieves session and station information for the current capture.
QueryStations | Retrieves a list of all computers on a subnet that are using Network Monitor to capture network data.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.


IRTC::Configure

The Configure method submits configuration information for a data capture.

HRESULT STDMETHODCALLTYPE Configure(
  HBLOB hConfigurationBlob,
  HBLOB hErrorBlob
);

Parameters

hConfigurationBlob
[in] Handle to the BLOB that the caller configures.
hErrorBlob
[out] Handle to an error BLOB that contains additional error information.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_BLOB_NOT_INITIALIZED
The CreateBlob method has not been called.
NMERR_INVALID_BLOB
The object pointed to is not a BLOB.
NMERR_UPLEVEL_BLOB
The BLOB version number is incorrect.
NMERR_BLOB_ENTRY_ALREADY_EXISTS
Duplicate BLOB.
NMERR_BLOB_ENTRY_DOES_NOT_EXIST
The configuration BLOB specified by hConfigurationBlob lacks an entry needed to perform this operation. Look at the error BLOB returned by hErrorBlob to determine which entry was not found.
NMERR_AMBIGUOUS_SPECIFIER
The BLOB Owner or Category information is missing.
NMERR_BLOB_OWNER_NOT_FOUND
The BLOB Owner section was not found.
NMERR_BLOB_CATEGORY_NOT_FOUND
The BLOB Category section was not found.
NMERR_UNKNOWN_CATEGORY
The BLOB Category section was found but not understood.
NMERR_UNKNOWN_TAG
The BLOB Tag section was found but not understood.
NMERR_BLOB_CONVERSION_ERROR
The BLOB is corrupt.
NMERR_ILLEGAL_TRIGGER
The trigger portion of the BLOB is corrupt.
NMERR_BLOB_STRING_INVALID
The string is not null-terminated.

Remarks

You must apply this method to restart an NPP that has been started, stopped, but not disconnected.

The error BLOB returned by hErrorBlob contains entries that Network Monitor could not understand or find in the configuration BLOB specified in hConfigurationBlob. The returned error BLOB contains error information that the application can use for troubleshooting. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry Network Monitor could not find is included in the returned error BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, Network Monitor BLOBS


IRTC::Connect

The Connect method connects the NPP to the network by using a specified NIC and provides configuration information for the connection.

HRESULT STDMETHODCALLTYPE Connect(
  HBLOB  hInputBlob,
  LPVOID StatusCallbackProc,
  LPVOID FramesCallbackProc,
  LPVOID UserContext,
  HBLOB hErrorBlob
);

Parameters

hInputBlob
[in] Handle to the BLOB that specifies the NIC that you are connecting to and the configuration information for that connection.
StatusCallbackProc
[in] Address of the user's status callback function, which receives status updates such as triggers. This parameter can be set to NULL.
FramesCallbackProc
[in] Address of the user's frame callback function, which is used to receive status updates such as triggers. This parameter can be set to NULL.
UserContext
[in] Value passed when the user's status and frame callback function is called. If both callback functions are specified, they must use the same user-context value. The value of this parameter is typically either HWND or a 'this' pointer.
hErrorBlob
[out] Handle to an error BLOB that contains additional error information. See Remarks at the bottom of this topic for information about what is in the error BLOB.

Return Values

If this method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

Error codes returned by the Connect method include those errors returned by the internal IRTC::Configure call.

NMERR_ALREADY_CONNECTED
This instance of the NPP COM object is already connected to the network.
NMERR_BLOB_CONVERSION_ERROR
The configuration BLOB is corrupt. This error is generated by the IRTC::Configure call.
NMERR_BLOB_ENTRY_DOES_NOT_EXIST
The input BLOB specified by the hInputBlob parameter lacks an entry needed to perform this operation. This error may be generated by the IRTC::Connect or IRTC::Configure call. Look at the error BLOB returned by hErrorBlob to determine which entry was not found.
NMERR_BLOB_NOT_INITIALIZED
The CreateBlob function has not been called. This error is generated by the IRTC::Configure call.
NMERR_BLOB_STRING_INVALID
The string is not null-terminated. This error is generated by the IRTC::Configure call.
NMERR_ILLEGAL_TRIGGER
The trigger portion of the input BLOB is corrupt. This error is generated by the IRTC::Configure call.
NMERR_INVALID_BLOB
The object specified in hInputBlob is not a BLOB. This error is generated by the IRTC::Configure call.
NMERR_OUT_OF_MEMORY
The memory needed to perform this operation is unavailable. This error is generated by the IRTC::Configure call.
NMERR_TIMEOUT
The request has timed out. This error is generated by the IRTC::Configure call.
NMERR_UPLEVEL_BLOB
The version number of the BLOB specified in hInputBlob is incorrect. This error is generated by the IRTC::Configure call.

Remarks

When the Connect method is called, the NPP automatically calls the IRTC::Configure method by using the BLOB provided by hInputBlob. Note that any error codes returned by the call to IRTC::Configure are passed back and returned by the IRTC::Connect call.

This method must be called before you can start capturing frames. Note that when you connect to the network using this method, you must continue to use the IRTC interface to capture frames.

When calling this function, you must specify a status or frame callback function, even if it only acts as a placeholder.

The input BLOB specified by hInputBlob can be obtained by calling the GetNPPBlobFromUI, GetNPPBlobTable, and SelectNPPBlobFromTable methods.

The error BLOB returned in hErrorBlob contains error information that the developer or the application can use for troubleshooting. The error BLOB returned by hErrorBlob contains entries that Network Monitor could not understand or find in the input BLOB specified in hInputBlob. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry Network Monitor could not find is included in the returned error BLOB.

For information about | See
Obtaining the input BLOB that represents a NIC | Selecting a Network Interface Card

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Configure, IRTC::Disconnect, IRTC::Start


IRTC::Disconnect

The Disconnect method disconnects the NPP from the network.

HRESULT STDMETHODCALLTYPE Disconnect(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURING
The NPP is capturing data. You cannot disconnect from the network while the data capture is in progress.
NMERR_NOT_CONNECTED
The NPP is not connected to the network.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.

Remarks

This method cannot be called when the NPP is capturing data. You must call the IRTC::Stop method before calling IRTC::Disconnect.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, IRTC::Stop


IRTC::GetControlState

The GetControlState method retrieves the state of the capture, which indicates if the capture is running or paused.

HRESULT STDMETHODCALLTYPE GetControlState(
  BOOL *IsRunnning,
  BOOL *IsPaused
);

Parameters

IsRunnning
[out] Indicator that the current capture is running, including if the capture is paused.
IsPaused
[out] Indicator that the current capture is paused.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IRTC::Connect to connect the NPP to the network.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.

Remarks

This method can be called any time the NPP is connected to the network. You can use this method to find out if a capture is running, if the capture is paused, or if the capture has been stopped but the NPP is still connected.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, IRTC::Pause, IRTC::Start, IRTC::Stop


IRTC::GetConversationStatistics

The GetConversationStatistics method retrieves session and station information about the current capture.

HRESULT STDMETHODCALLTYPE GetConversationStatistics(
  DWORD *nSessions,
  /* [size_is] */ LPSESSIONSTATS lpSessionStats,
  DWORD *nStations,
  /* [size_is] */ LPSTATIONSTATS lpStationStats,
  BOOL fClearAfterReading
);

Parameters

nSessions
[out] Number of sessions recorded for the current capture.
lpSessionStats
[out] Pointer to a SESSIONSTATS structure.
nStations
[out] Number of stations recorded for the current capture.
lpStationStats
[out] Pointer to a STATIONSTATS structure.
fClearAfterReading
[in] Flag used to tell Network Monitor to clear out the internal storage of the SESSIONSTATS and STATIONSTATS structures after it retrieves the current information.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IRTC::Connect to connect the NPP to the network.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IRTC::Start to start the capture.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.
NMERR_NO_CONVERSATION_STATS
The configuration for this connection is set to not save conversation statistics. To save conversation statistics, stop the capture, set NoConversationStats = YES in the configuration BLOB, then restart the capture.

Remarks

This method can only be called while you are capturing data; if you call this method while the current capture is paused, the method will not succeed. To start a capture, call the IRTC::Start method.

To retrieve other types of statistics, call the IRTC::GetTotalStatistics method.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, IRTC::GetTotalStatistics, IRTC::Start, SESSIONSTATS, STATIONSTATS


IRTC::GetTotalStatistics

The GetTotalStatistics method retrieves the total statistics for the current capture.

HRESULT STDMETHODCALLTYPE GetTotalStatistics(
  LPSTATISTICS lpStats,
  BOOL fClearAfterReading
);

Parameters

lpStats
[out] Pointer to a STATISTICS structure that provides the total statistics for the capture. It is the callers responsibility to allocate and free the memory used by the STATISTICS structure.
fClearAfterReading
[in] Flag used to tell Network Monitor how to handle the internal storage of the total statistics. A setting of TRUE tells Network Monitor to clear out the internal storage of the total statistics after the current information is retrieved.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code..

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IRTC::Connect to connect the NPP to the network.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IRTC::Start to start capturing data.

Remarks

This method returns data only while a capture is in progress, including while the capture is paused.

Network Monitor also stores conversation statistics. To retrieve conversation statistics, call the IRTC::GetConversationStatistics method.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, IRTC::GetConversationStatistics, IRTC::Start, STATISTICS


IRTC::Pause

The Pause method pauses the current capture.

HRESULT STDMETHODCALLTYPE Pause( void );

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture is already paused.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IRTC::Start to start the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IRTC::Connect to connect the NPP to the network.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.

Remarks

While the capture is in a paused state, new frames are not captured until the IRTC::Resume method is called to restart the capture.

When you use the IRTC::Pause and IRTC::Resume methods to control the capture, Network Monitor continues to add conversation statistics whenever the capture is running.

To restart the capture call IRTC::Resume. To stop the capture, call IRTC::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, IRTC::Resume, IRTC::Start, IRTC::Stop


IRTC::QueryStations

The QueryStations method provides a list of all computers that are currently using Network Monitor to capture network data.

HRESULT STDMETHODCALLTYPE QueryStations(
   QUERYTABLE *lpQueryTable
);

Parameters

lpQueryTable
[in, out] Pointer to a QUERYTABLE structure. On input, this structure must contain the maximum number of computers you want Network Monitor to return and an array of STATIONQUERY structures.

On output, this structure returns the number of computers that are capturing data and a STATIONQUERY structure for each computer found. Note that this may include computers using versions of Network Monitor that predate version 2.0.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_OUT_OF_MEMORY
The memory required to process this query is unavailable.

Remarks

This method can be called at any time after the CreateNPPInterface method is called. A call to this method is a synchronous call, which may take several seconds to complete while Network Monitor waits for remote computers to respond to the query. Only computers on the local subnet can be queried.

It is your responsibility to allocate the memory for the QUERYTABLE structure and free that memory after the table is no longer needed. This requirement includes memory needed for the STATIONQUERY array used in QUERYTABLE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

QUERYTABLE, STATIONQUERY


IRTC::QueryStatus

The QueryStatus method retrieves the status of the NPP.

HRESULT STDMETHODCALLTYPE QueryStatus(
  NETWORKSTATUS *pNetworkStatus
);

Parameters

pNetworkStatus
[out] Pointer to a returned NETWORKSTATUS structure that indicates the current state (capturing, paused, stopped, and so on) of the NPP. It is the application's responsibility to allocate and free the memory for the NETWORKSTATUS structure.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_INVALID_PARAMETER
The pNetworkStatus parameter is not pointing to a valid NETWORKSTATUS structure. Allocate memory for this structure and call IRTC::QueryStatus again.

Remarks

This method can be called at any time after the CreateNPPInterface method is called. You can call this method to see if the NPP is connected to the network, to find out the status of the current capture, and to see if any triggers are pending. Before calling this method, however, you must allocate the memory needed for the NETWORKSTATUS structure and free that memory when the structure is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

CreateNPPInterface, NETWORKSTATUS


IRTC::Resume

The Resume method restarts a paused capture.

HRESULT STDMETHODCALLTYPE Resume(void);

Parameters

This method has no parameters.

Return Values

If the method is successful the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_NOT_PAUSED
The capture is not paused. Call IRTC::Pause to pause the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IRTC::Connect to connect the NPP to the network.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.

Remarks

While the capture is in a paused state, new data is not captured until a call to the IRTC::Resume method restarts the capture.

When using the Pause and Resume methods to control the capture, Network Monitor continues to add conversation statistics to the existing statistics for the current capture.

To stop the capture, call the IRTC::Stop method.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, IRTC::Pause, IRTC::Stop


IRTC::Start

The Start method starts the capture.

HRESULT STDMETHODCALLTYPE Start(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture is in a paused state and must be stopped before it can be restarted. Call IRTC::Stop to stop the capture.
NMERR_CAPTURING
The capture is already started.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IRTC::Connect to connect the NPP to the network.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.

Remarks

When you restart the capture by using the IRTC::Start and IRTC::Stop methods, you must call the IRTC::Configure method to reconfigure the connection each time you call IRTC::Start to restart the data capture.

Note You can also start and stop the capture by using the IRTC::Pause and IRTC::Resume methods. When you use these methods, the captured data is stored in the same capture file.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Configure, IRTC::Connect, IRTC::Pause , IRTC::Resume, IRTC::Stop


IRTC::Stop

The Stop method stops the current capture.

HRESULT STDMETHODCALLTYPE Stop(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IRTC::Connect to connect the NPP to the network.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IRTC::Start to start the capture.
NMERR_NOT_REALTIME
The NPP is connected to the network but not with the IRTC::Connect method.

Remarks

When you restart the capture after calling the IRTC::Stop method, make sure to call IRTC::Configure each time you call IRTC::Start to restart the capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in IRTC.h.

See Also

IRTC::Connect, IRTC::Configure, IRTC::Start


IStats

The IStats interface provides the methods you use to connect an NPP to the network, capture network traffic, retrieve statistics, and disconnect the NPP from the network. This interface generates statistics without frames.

Methods in Vtable Order

Methods | Description
Connect | Connects the NPP to the network.
Disconnect | Disconnects the NPP from the network.
QueryStatus | Retrieves the status of the NPP.
Configure | Configures the trigger, pattern match, and buffer size of the capture file.
Start | Starts the capture.
Pause | Temporarily stops the current capture.
Resume | Restarts a paused capture.
Stop | Stops the current capture.
GetControlState | Retrieves the state of the capture, which indicates if the capture is running or paused.
GetTotalStatistics | Extracts time, buffer, driver, and other network statistics from the currently running capture.
GetConversationStatistics | Retrieves session and station information about the current capture.
QueryStations | Retrieves a list of all computers that are using Network Monitor to capture data on a subnet.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.


IStats::Configure

The Configure method submits capture configuration information.

HRESULT STDMETHODCALLTYPE Configure(
  HBLOB hConfigurationBlob,
  HBLOB hErrorBlob
);

Parameters

hConfigurationBlob
[in] Handle to the BLOB that the caller configures.
hErrorBlob
[out] Handle to an error BLOB that contains additional error information.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_BLOB_NOT_INITIALIZED
The CreateBlob method has not been called.
NMERR_INVALID_BLOB
The object that is pointed to is not a BLOB.
NMERR_UPLEVEL_BLOB
The BLOB version number is incorrect.
NMERR_BLOB_ENTRY_ALREADY_EXISTS
A BLOB entry already exists.
NMERR_BLOB_ENTRY_DOES_NOT_EXIST
The configuration BLOB specified by the hConfigurationBlob parameter lacks an entry needed to perform this operation. Look at the error BLOB returned by the hErrorBlob parameter to determine which entry was not found.
NMERR_AMBIGUOUS_SPECIFIER
The BLOB lacks owner or category information.
NMERR_BLOB_OWNER_NOT_FOUND
The Owner section of the BLOB was not found.
NMERR_BLOB_CATEGORY_NOT_FOUND
The Category section of the BLOB was not found.
NMERR_UNKNOWN_CATEGORY
Category information was found but not understood.
NMERR_UNKNOWN_TAG
Tag information was found but not understood.
NMERR_BLOB_CONVERSION_ERROR
The BLOB is corrupt.
NMERR_ILLEGAL_TRIGGER
The trigger portion of the BLOB is corrupt.

NMERR_BLOB_STRING_INVALID

The string is not null-terminated.

Remarks

You must apply this method to restart an NPP that has been started, stopped but not disconnected.

The error BLOB returned by hErrorBlob contains entries that Network Monitor could not understand or find in the configuration BLOB specified in the hConfigurationBlob parameter. The returned error BLOB contains error information that the application can use for troubleshooting. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry Network Monitor could not find is included in the returned error BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

ISTATS::Connect, Network Monitor BLOBS


IStats::Connect

The Connect method connects the NPP to the network by using a specified NIC and provides configuration information for the connection.

HRESULT STDMETHODCALLTYPE Connect(
  HBLOB  hInputBlob,
  LPVOID StatusCallbackProc,
  LPVOID UserContext,
  HBLOB hErrorBlob
);

Parameters

hInputBlob
[in] Handle to the BLOB that specifies the NIC that the NPP connects to and the configuration information for that connection.
StatusCallbackProc
[in] Address of the user's callback function, which receives status updates such as triggers. If a callback function is not used, set this parameter and the UserContext parameter to NULL.
UserContext
[in] Value passed when the user's callback function is called. The value of this parameter is typically either HWND or a 'this' pointer. If a callback function is not specified, set this parameter and the StatusCallbackProc parameter to NULL..
hErrorBlob
[out] Handle to an error BLOB that contains additional error information.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

Error codes returned by the Connect method include those errors returned by the internal IStats::Configure call.

NMERR_ALREADY_CONNECTED
This instance of the NPP COM object is already connected to the network.
NMERR_BLOB_CONVERSION_ERROR
The configuration BLOB is corrupt. This error is generated by the IStats::Configure call.
NMERR_BLOB_ENTRY_DOES_NOT_EXIST
The input BLOB specified by the hInputBlob parameter lacks an entry needed to perform this operation. This error might be generated by the IStats::Connect or IStats::Configure call. Look at the error BLOB returned by hErrorBlob to determine which entry was not found.
NMERR_BLOB_NOT_INITIALIZED
The CreateBlob function has not been called. This error is generated by the IStats::Configure call.
NMERR_BLOB_STRING_INVALID
The string is not null-terminated. This error is generated by the IStats::Configure call.
NMERR_ILLEGAL_TRIGGER
The trigger portion of the input BLOB is corrupt. This error is generated by the IStats::Configure call.
NMERR_INVALID_BLOB
The object specified in hInputBlob is not a BLOB. This error is generated by the IStats::Configure call.
NMERR_NO_DEFAULT_CAPTURE_DIRECTORY
The default capture directory was not set in the registry. To set the capture directory, use the following path.
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\nm\Parameters\CapturePath
NMERR_OUT_OF_MEMORY
The memory required to perform this operation was unavailable. This error is generated by the IStats::Configure call.
NMERR_TIMEOUT
The request has timed out. This error is generated by the IStats::Configure call.
NMERR_UPLEVEL_BLOB
The version number of the BLOB specified in hInputBlob is incorrect. This error is generated by the IStats::Configure call.

Remarks

When the Connect method is called, Network Monitor automatically calls the IStats::Configure method by using the BLOB provided by the hInputBlob parameter. Note that any error codes returned by the call to IStats::Configure are passed back and returned by the IStats::Connect call.

This method must be called before you can start capturing frames. Note that when you connect to the network by using this method, you must continue to use the IStats interface to capture frames.

The input BLOB specified by hInputBlob can be obtained by calling the GetNPPBlobFromUI, GetNPPBlobTable, and SelectNPPBlobFromTable methods.

The error BLOB returned by the hErrorBlob parameter contains entries that Network Monitor could not understand or find in the input BLOB specified in hInputBlob. The returned error BLOB contains error information that the application can use for troubleshooting. For example, if NMERR_BLOB_ENTRY_DOES_NOT_EXIST is returned, the entry that Network Monitor could not find is included in the returned error BLOB.

For information about | See
Obtaining the input BLOB that represents a network interface card | Selecting a Network Interface Card

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Configure, IStats::Disconnect, Network Monitor BLOBS


IStats::Disconnect

The Disconnect method disconnects the NPP from the network.

HRESULT STDMETHODCALLTYPE Disconnect(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURING
The NPP is currently capturing data. You cannot disconnect from the network while a data capture is in progress.
NMERR_NOT_CONNECTED
The NPP is not connected to the network.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.

Remarks

This method cannot be called when the NPP is capturing data. Call the IStats::Disconnect method first and then call IStats::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Connect, IStats::Stop


IStats::GetControlState

The GetControlState method retrieves the state of the capture, which indicates if the capture is running or paused.

HRESULT STDMETHODCALLTYPE GetControlState(
  BOOL *IsRunnning,
  BOOL *IsPaused
);

Parameters

IsRunnning
[out] Indicator that the current capture is running, including if the capture is paused.
IsPaused
[out] Indicator that the current capture is paused.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IStats::Connect to connect the NPP to the network.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.

Remarks

This method can be called any time the NPP is connected to the network. You can use this method to find out if a capture is running, if the capture is paused, or if the capture has been stopped but the NPP is not disconnected.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Connect, IStats::Pause, IStatsC::Start, IStatsC::Stop


IStats::GetConversationStatistics

The GetConversationStatistics method retrieves session and station information about the current capture.

HRESULT STDMETHODCALLTYPE GetConversationStatistics(
  DWORD *nSessions,
  /* [size_is] */ LPSESSIONSTATS lpSessionStats,
  DWORD *nStations,
  /* [size_is] */ LPSTATIONSTATS lpStationStats,
  BOOL fClearAfterReading
);

Parameters

nSessions
[out] Number of sessions recorded for the current capture.
lpSessionStats
[out] Pointer to a SESSIONSTATS structure.
nStations
[out] Number of stations recorded for the current capture.
lpStationStats
[out] Pointer to a STATIONSTATS structure.
fClearAfterReading
[in] Flag used to tell Network Monitor to clear out the internal storage of the SESSIONSTATS and STATIONSTATS structures after the current information is retrieved.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call IStats::Connect to connect the NPP to the network.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call IStats::Start to start the capture.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.
NMERR_NO_CONVERSATION_STATS
The configuration for this connection is set to not save conversation statistics. To save conversation statistics, stop the capture, set NoConversationStats = YES in the configuration BLOB, and then start the capture again.

Remarks

This method can be called only while data capture is in progress; when the current capture is paused, a call to this method will not succeed.

To start a capture, call the IStats::Start method. To retrieve other types of statistics, call IStats::GetTotalStatistics.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::GetTotalStatistics, IStats::Start, IStats::Connect, SESSIONSTATS, STATIONSTATS


IStats::GetTotalStatistics

The GetTotalStatistics method retrieves the total statistics for the current capture.

HRESULT STDMETHODCALLTYPE GetTotalStatistics(
  LPSTATISTICS lpStats,
  BOOL fClearAfterReading
);

Parameters

lpStats
[out] Pointer to a STATISTICS structure that provides the total statistics for the capture. It is the caller's responsibility to allocate and free the memory used by the STATISTICS structure.
fClearAfterReading
[in] Flag used to tell Network Monitor how to handle the internal storage of the total statistics. A setting of TRUE tells Network Monitor to clear out the internal storage of the total statistics after the current information is retrieved.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call the IStats::Connect method to connect the NPP to the network.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call the IStats::Start method to start capturing data.

Remarks

This method returns data only while a capture is in progress, including while the capture is paused.

Network Monitor also stores conversation statistics, which can be retrieved by calling the IStats::GetConversationStatistics method.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Connect, IStats::GetConversationStatistics, IStats::Start,, STATISTICS


IStats::Pause

The Pause method temporarily stops the current capture.

HRESULT STDMETHODCALLTYPE Pause(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture is already paused.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call the IStats::Start method to start the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call the IStats::Connect method to connect the NPP to the network.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.

Remarks

While the capture is paused, new frames are not captured until a call to the IStats::Resume method restarts the capture.

When you use the IStats::Pause and IStats::Resume methods to control the capture, Network Monitor continues to add conversation statistics whenever the capture is running.

To restart the capture call IStats::Resume. To stop the capture, call IStats::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Connect, IStats::Resume, IStats::Start, IStats::Stop


IStats::QueryStations

The QueryStations method provides a list of all computers who are currently capturing data using Network Monitor.

HRESULT STDMETHODCALLTYPE QueryStations(
  QUERYTABLE *lpQueryTable
);

Parameters

lpQueryTable
[in, out] Pointer to a QUERYTABLE structure. On input, this structure must contain the maximum number of computers you want Network Monitor to return and an array of STATIONQUERY structures.

On output, this structure returns the number of computers that are capturing data and a STATIONQUERY structure for each computer found. Note that this information may include computers using versions of Network Monitor that predate version 2.0.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_OUT_OF_MEMORY
The memory required to process this query was unavailable.

Remarks

This method can be called at any time after CreateNPPInterface is called. A call to this method is a synchronous call, which may take several seconds to complete as Network Monitor waits for remote computers to respond to the query. Only computers on the local subnet can be queried.

It is your responsibility to allocate the memory for the QUERYTABLE structure and free that memory after the table is no longer needed. This requirement includes the memory needed for the STATIONQUERY array used in QUERYTABLE.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

QUERYTABLE, STATIONQUERY


IStats::QueryStatus

The QueryStatus method retrieves the status of the NPP.

HRESULT STDMETHODCALLTYPE QueryStatus(
  NETWORKSTATUS *pNetworkStatus
);

Parameters

pNetworkStatus
[out] Pointer to a returned NETWORKSTATUS structure that indicates the current state (capturing, paused, stopped, and so on) of the NPP. It is the application's responsibility to allocate and free the memory for the NETWORKSTATUS structure.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_INVALID_PARAMETER
The pNetworkStatus parameter is not pointing to a valid NETWORKSTATUS structure. Allocate memory for this structure and call the IStats::QueryStatus method again.

Remarks

This method can be called at any time after the CreateNPPInterface method is called. It can be called to see if the NPP is connected to the network, to find out the status of the current capture, and to see if any triggers are pending. Before calling this method, however, you must allocate the memory needed for the NETWORKSTATUS structure and free that memory when the structure is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

CreateNPPInterface, NETWORKSTATUS


IStats::Resume

The Resume method restarts a paused capture.

HRESULT STDMETHODCALLTYPE Resume(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network.
NMERR_CAPTURE_NOT_PAUSED
The capture is not paused. Call the IStats::Pause method to temporarily stop the capture.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call the IStats::Connect method to connect the NPP to the network.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.

Remarks

While the capture is in a paused state, new data is not captured until the IStats::Resume method is called to restart the capture.

When using the Pause and Resume methods to control the capture, Network Monitor continues to add conversation statistics to the existing statistics for the current capture.

To stop the capture, call IStats::Stop.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Connect, IStats::Pause, IStats::Stop


IStats::Start

The Start method starts a capture.

HRESULT STDMETHODCALLTYPE Start(void);

Parameters

This method has no parameters.

Return Values

If the method is successful, the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_CAPTURE_PAUSED
The capture has paused and must be stopped before it can be restarted. Call the IStats::Stop method to stop the capture.
NMERR_CAPTURING
The capture has already started.
NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call the IStats::Connect method to connect the NPP to the network.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.

Remarks

When restarting the capture by using the IStats::Start and IStats::Stop methods, you must call the IStats::Configure method to reconfigure the connection each time you call IStats::Start to restart the data capture.

Note You can also start and stop the capture by using the IStats::Pause and IStats::Resume methods. When you use these methods, the captured data is stored in the same capture file.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Configure, IStats::Connect, IStats::Pause , IStats::Resume, IStats::Stop


IStats::Stop

The Stop method stops the current capture.

HRESULT STDMETHODCALLTYPE Stop(void);

Parameters

This method has no parameters.

Return Values

If the method is successful the return value is NMERR_SUCCESS.

If the method is unsuccessful, the return value is an error code.

Error Codes

NMERR_NOT_CONNECTED
The NPP is not connected to the network. Call the IStats::Connect method to connect the NPP to the network.
NMERR_NOT_CAPTURING
The NPP is not capturing data. Call the IStats::Start method to start the capture.
NMERR_NOT_STATS_ONLY
The NPP is connected to the network but not with the IStats::Connect method.

Remarks

When restarting the capture after IStats::Stop has been called, make sure you call the IStats::Configure method each time you call IStats::Start to restart the capture.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in ISTATS.h.

See Also

IStats::Connect, IStats::Configure, IStats::Start


NPP Structures

This section describes the NPP structures used by NPP methods. These structures are used to retrieve statistics, provide system status and statistical information, and indicate which computers are running Network Monitor. The following tables describes these structures.

NPP Structures | Description
SESSIONSTATS | Provides session information when conversation statistics are retrieved.
STATIONSTATS | Provides statistics about a specific station.
STATISTICS | Provides network statistics when total statistics are retrieved and when the current capture has paused or stopped.
QUERYTABLE | Indicates which computers are using Network Monitor.
STATIONQUERY | Provides information about a computer that is using Network Monitor. This structure is used by QUERYTABLE.
NETWORKSTATUS | Provides current network status in terms of system state.


SESSIONSTATS

The SESSIONSTATS structure provides statistics about a session.

typedef struct _SESSIONSTATS
{
  DWORD           NextSession;
  DWORD           StationOwner;
  DWORD           StationPartner;
  DWORD           Flags;
  DWORD           TotalPacketsSent;
} SESSIONSTATS
typedef SESSIONSTATS * LPSESSIONSTATS;

Members

NextSession
Index of the station owner's next session.
StationOwner
Index of a owner station within the associated STATIONSTATS structure array. The owner station is the station that initiated the session, the station that sent the packets of the session.
StationPartner
Index of the other station within the associated STATIONSTATS structure array. The partner station is the station that received the packets of the session.
Flags
This member is obsolete.
TotalPacketsSent
Number of packets sent in the session.

Remarks

Network Monitor stores session and station information in two associated arrays, whose elements are SESSIONSTATS and STATIONSTATS structures respectively. The members of these structures can be used to navigate between them. For example, to move to the next session for a specific station owner, use NextSession. To jump to the owner and partner station of the session in the STATIONSTATS array, use the index provided in StationOwner and StationPartner.

Note The SESSIONSTATS array contains an element for each session in the current capture. The algorithm Network Monitor uses to add elements to the SESSIONSTATS array is based on efficiently recording information while the capture is in progress. Consequently, the next session for a specific owner station is not always the next element in the array.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

IDelaydC::GetConversationStatistics, IRTC::GetConversationStatistics, IStats::GetConversationStatistics


STATIONSTATS

The STATIONSTATS structure provides statistics about a specific station described by the current capture.

typedef struct _STATIONSTATS
{
  DWORD           NextStationStats
  DWORD           SessionPartnerList;
  DWORD           Flags;
  BYTE            StationAddress[6];
  WORD            Pad;
  DWORD           TotalPacketsReceived;
  DWORD           TotalDirectedPacketsSent;
  DWORD           TotalBroadcastPacketsSent;
  DWORD           TotalMulticastPacketsSent;
  DWORD           TotalBytesReceived;
  DWORD           TotalBytesSent;
} STATIONSTATS;
typedef STATIONSTATS * LPSTATIONSTATS;

Members

NextStationStats
Index of the next station recorded in the STATIONSTATS structure array.
SessionPartnerList
Index of the station partner list.
Flags
This member is obsolete.
StationAddress
The MAC address of the station.
Pad
DWORD alignment.
TotalPacketsReceived
Total number of packets sent to the station.
TotalDirectedPacketsSent
Total number of directed packets sent by the station.
TotalBroadcastPacketsSent
Total number of broadcast-directed packets (MAC address FF FF FF FF FF FF) sent by the station.
TotalMulticastPacketsSent
Total number of multicast packets (Group bit set in destination address) sent by the station.
TotalBytesReceived
Total number of bytes sent to the station.
TotalBytesSent
Total number of bytes sent by the station.

Remarks

Network Monitor stores session and station information in two associated arrays. whose elements are SESSIONSTATS and STATIONSTATS structures respectively. The members of these structures can be used to navigate between them. For example, to move to the next station use NextStationStats. To jump to the session partner list in the SESSIONSTATS array, use the index provided in SessionPartnerList.

Note The STATIONSTATS array contains an element for each station used during the current capture. The algorithm Network Monitor uses to add elements to this array is based on the most efficient way to record information while the capture is in progress. Consequently, the next station is not always the next element in the array.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

IDelaydC::GetConversationStatistics, IRTC::GetConversationStatistics, IStats::GetConversationStatistics


STATISTICS

The STATISTICS structure provides statistics for the capture. Some of these statistics are generated by Network Monitor, while others are generated by the NIC that the NPP is connected to.

typedef struct _STATISTICS
{
  __int64         TimeElapsed;
  DWORD           TotalFramesCaptured;
  DWORD           TotalBytesCaptured;
  DWORD           TotalFramesFiltered;
  DWORD           TotalBytesFiltered;
  DWORD           TotalMulticastsFiltered;
  DWORD           TotalBroadcastsFiltered;
  DWORD           TotalFramesSeen;
  DWORD           TotalBytesSeen;
  DWORD           TotalMulticastsReceived;
  DWORD           TotalBroadcastsReceived;
  DWORD           TotalFramesDropped;
  DWORD           TotalFramesDroppedFromBuffer;
  DWORD           MacFramesReceived;
  DWORD           MacCRCErrors;
  __int64         MacBytesReceivedEx;
  DWORD           MacFramesDropped_NoBuffers;
  DWORD           MacMulticastsReceived;
  DWORD           MacBroadcastsReceived;
  DWORD           MacFramesDropped_HwError;
} STATISTICS;

typedef STATISTICS *LPSTATISTICS;

Members

TimeElapsed
Elapsed time, in microseconds.
TotalFramesCaptured
Total number of frames currently stored. This number is limited by the size of the capture file or buffer used to store the frames.
TotalBytesCaptured
Total number of bytes currently stored. This number is limited by the size of the capture file or buffer used to store the frames.
TotalFramesFiltered
Total number of frames that passed through the current capture filter. If a filter is not used, this value is the same as TotalFramesSeen.
TotalBytesFiltered
Total number of frames that passed through the current capture filter. If a filter is not used, this value is the same as TotalBytesSeen.
TotalMulticastsFiltered
This member is obsolete.
TotalBroadcastsFiltered
This member is obsolete.
TotalFramesSeen
Total number of frames handled by the NIC.
TotalBytesSeen
Total number of bytes handled by the NIC.
TotalMulticastsReceived
This member is obsolete.
TotalBroadcastsReceived
This member is obsolete.
TotalFramesDropped
Total number of frames dropped (frames that passed the filter but were not saved).
TotalFramesDroppedFromBuffer
Number of frames dropped from the capture file or buffer. When the buffer is full, older frames are removed to make room for new ones.
MacFramesReceived
Number of frames that the NIC reports having received.
MacCRCErrors
Number of CRC errors reported by the NIC.
MacBytesReceivedEx
Number of bytes that the NIC reports having received.
MacFramesDropped_NoBuffers
Number of frames that the NIC reports having dropped due to a lack of buffer space.
MacMulticastsReceived
Number of multicasts the NIC reports having received.
MacBroadcastsReceived
Number of broadcasts the NIC reports having received.
MacFramesDropped_HwError
Number of frames the NIC reports as having dropped due to hardware errors.

Remarks

This structure is used to retrieve total statistics, and to pause or stop the current capture.

Note that you cannot use the IESP interface to retrieve total statistics.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

IDelaydC::GetTotalStatistics, IRTC::GetTotalStatistics, IStats::GetTotalStatistics, IDelaydC::Pause, IESP::Pause, IRTC::Pause, IStats::Pause, IDelaydC::Stop, IESP::Stop, IRTC::Stop, IStatsC::Stop


QUERYTABLE

The QUERYTABLE structure provides a list of the computers that are currently using Network Monitor to capture network data.

typedef struct _QUERYTABLE
{
  DWORD           nStationQueries;
  STATIONQUERY    StationQuery[1];
} QUERYTABLE;
typedef QUERYTABLE *LPQUERYTABLE;

Members

nStationQueries
On input, the maximum number of computers you want Network Monitor to return.

On output, the number of STATIONQUERY structures returned by Network Monitor. Each STATIONQUERY structure represents a computer that is currently capturing data.

StationQuery
On input, an array of empty STATIONQUERY structures that contains the number of elements specified in nStationQueries.

On output, a filled STATIONQUERY structure for each computer that is capturing data. The number of filled elements is returned by nStationQueries.

Remarks

The memory for this structure and the STATIONQUERY array must be allocated by the calling application and freed after the information is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

IDelaydC::QueryStations, IESP::QueryStations, IRTC::QueryStations, IStats::QueryStations, STATIONQUERY


STATIONQUERY

The STATIONQUERY structure provides information about a specific computer using Network Monitor.

typedef struct _STATIONQUERY
{
  DWORD   Flags;
  BYTE    BCDVerMinor;
  BYTE    BCDVerMajor;
  DWORD   LicenseNumber;
  BYTE    MachineName[MACHINE_NAME_LENGTH];
  BYTE    UserName[USER_NAME_LENGTH];
  BYTE    Reserved[32];
  BYTE    AdapterAddress[6];
  WCHAR   WMachineName[MACHINE_NAME_LENGTH];
  WCHAR   WUserName[USER_NAME_LENGTH];
} STATIONQUERY;
typedef STATIONQUERY *LPSTATIONQUERY;
#define STATIONQUERY_SIZE sizeof(STATIONQUERY)

Members

Flags
Flags that Identify the current state of Network Monitor.
STATIONQUERY_FLAGS_LOADED
The driver is loaded, but the kernel is not.
STATIONQUERY_FLAGS_RUNNING
The driver is loaded but not capturing data.
STATIONQUERY_FLAGS_CAPTURING
The driver is actively engaged in a capture.
STATIONQUERY_FLAGS_TRANSMITTING
This flag is obsolete.
BCDVerMinor
Minor version number of Network Monitor installed on the computer.
BCDVerMajor
Major version number of Network Monitor installed on the computer.
LicenseNumber
Software license number.
MachineName
Computer manufacturer name, if any.
UserName
User name or system identifier.
Reserved
Reserved for future use.
AdapterAddress
NIC address.
WMachineName
Unicode computer name. This member applies to Network Monitor 2.0 or later.
WUserName
Unicode user name. This member applies to Network Monitor 2.0 or later.

Remarks

An array of these structures is used by the QUERYTABLE structure to provide a list of the computers that are currently using Network Monitor to capture data.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

QUERYTABLE


NETWORKSTATUS

The NETWORKSTATUS structure describes the current status of the NPP.

typedef struct _NETWORKSTATUS
{
  DWORD   State;
  DWORD   Flags;
} NETWORKSTATUS;

typedef NETWORKSTATUS *LPNETWORKSTATUS;
#define NETWORKSTATUS_SIZE   sizeof(NETWORKSTATUS)

Members

State
Indicates the current state of the NPP.
NETWORKSTATUS_STATE_VOID
The NPP is not connected, or it is connected and the capture is not started.
NETWORKSTATUS_STATE_CAPTURING
The NPP is capturing data.
NETWORKSTATUS_STATE_PAUSED
The NPP has paused while capturing data.
Flags
Flags that describe the current state of the NPP.
NETWORKSTATUS_FLAGS_TRIGGER_PENDING
There is a trigger pending for the NPP.

Remarks

When using this structure, you must allocate the memory for the structure before it can be used and free the memory when the structure is no longer needed.

The See Also list at the bottom of this topic lists all the methods that use this structure.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

IDelaydC::QueryStatus, IESP::QueryStatus, IRTC::QueryStatus, IStats::QueryStatus


BLOB Functions

Network Monitor includes the following BLOB functions.

Function | Description
CreateBlob | Creates an empty BLOB.
CreateNPPInterface | Creates an NPP interface with a given BLOB.
DestroyBlob | Frees all memory associated with a given BLOB.
DuplicateBlob | Copies a given BLOB.
GetBoolFromBlob | Retrieves the named Boolean value from a given BLOB.
GetClassIDFromBlob | Retrieves the named class identifier value from a given BLOB.
GetDwordFromBlob | Retrieves the named DWORD value from a given BLOB.
GetMacAddressFromBlob | Retrieves the named MAC address from a given BLOB.
GetNetworkInfoFromBlob | Retrieves network information from a given BLOB.
GetNPPAddressFilterFromBlob | Retrieves address filter information from a given BLOB.
GetNPPBlobFromUI | Displays the Select a network dialog box and returns the NPP BLOB of the selected NIC.
GetNPPBlobTable | Retrieves a table of BLOBs.
GetNPPEtypeSapFilter | Retrieves the Etype/Sap filter from a given BLOB.
GetNPPMacTypeAsNumber | Retrieves the MAC type from the NetworkInfo category of the NPP section and converts the information into a MAC type number.
GetNPPPatternFilterFromBlob | Retrieves the pattern match filter from a given BLOB.
GetNPPTriggerFromBlob | Retrieves the trigger of a given BLOB.
GetStringFromBlob | Retrieves a single string from a specific location within a given BLOB.
GetStringsFromBlob | Retrieves all of the strings within the given bounds from a given BLOB.
IsRemoteNPP | Indicates whether the given BLOB specifies a remote NPP.
MergeBlob | Merges the information in source and target BLOBs and overwrites common entries with data from the source BLOB.
RegCreateBlobKey | Stores a BLOB at the given registry key.
RegOpenBlobKey | Retrieves a BLOB stored at the given registry key.
RemoveFromBlob | Removes information from any level of a given BLOB.
SelectNPPBlobFromTable | Selects an NPP BLOB from a table.
SetBoolInBlob | Sets a Boolean value at the given location within a BLOB.
SetClassIDInBlob | Sets the named class identifier value for a BLOB.
SetDwordInBlob | Sets the named DWORD value for a BLOB.
SetMacAddressInBlob | Sets the named MAC address for a BLOB.
SetNetworkInfoInBlob | Sets the network information for a BLOB.
SetNPPAddressFilterInBlob | Sets the given address filter in the BLOB.
SetNPPEtypeSapFilter | Sets the Etype/Sap filter in a BLOB.
SetNPPPatternFilterInBlob | Sets the pattern match filter for a BLOB.
SetNPPTriggerInBlob | Sets the trigger in a BLOB.
SetStringInBlob | Sets the string at a given location within a BLOB.
WriteBlobToFile | Writes a BLOB to a given file.


CreateBlob

The CreateBlob function creates an empty BLOB.

DWORD CreateBlob(
  HBLOB *phBlob
);

Parameters

phBlob
[out] Pointer to the variable where the pointer to the new BLOB is returned.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

DestroyBlob


CreateNPPInterface

The CreateNPPInterface function uses the BLOB returned from the finder to create an NPP that the application can use.

DWORD CreateNPPInterface(
  HBLOB hBlob,
  REFIID iid,
  void **ppvObject
);

Parameters

hBlob
[in] Handle to the BLOB returned from the finder.
iid
[in] Identifier of the interface that you call from the NPP (IRTC or IDelaydC, for example).
ppvObject
[out] Pointer to the returned pointer to the requested interface.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.


DestroyBlob

The DestroyBlob function frees all memory associated with the BLOB and then destroys the BLOB.

DWORD DestroyBlob(
  HBLOB hBlob
);

Parameters

hBlob
[in] Handle to the to the BLOB that is destroyed.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

CreateBlob


DuplicateBlob

The DuplicateBlob function copies a specific BLOB.

DWORD DuplicateBlob(
  HBLOB hSrcBlob,
  HBLOB *hBlobThatWillBeCreated
);

Parameters

hSrcBlob
[in] Handle to the BLOB that is copied.
hBlobThatWillBeCreated
[out] Handle to the duplicate BLOB.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

CreateBlob, DestroyBlob


GetBoolFromBlob

The GetBoolFromBlob function retrieves a named Boolean value from a BLOB.

DWORD GetBoolFromBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  BOOL *pBool
);

Parameters

hBlob
[in] Handle to a BLOB.
pOwnerName
[in] Pointer to the BLOB owner name.
pCategoryName
[in] Pointer to the BLOB category name.
pTagName
[in] Pointer to the BLOB tag name.
pBool
[out] Pointer to the Boolean value of the BLOB.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetBoolInBlob, GetClassIDFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob, GetStringsFromBlob


GetClassIDFromBlob

The GetClassIDFromBlob function retrieves a named class identifier value from a BLOB.

DWORD GetClassIDFromBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  CLSID *pClsID
);

Parameters

hBlob
[in] Handle to a BLOB.
pOwnerName
[in] Pointer to the BLOB owner name.
pCategoryName
[in] Pointer to the BLOB category name.
pTagName
[in] Pointer to the BLOB tag name.
pClsID
[out] Pointer to the BLOB class identifier.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetClassIDInBlob, GetBoolFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob, GetStringsFromBlob


GetDwordFromBlob

The GetDwordFromBlob function retrieves the named DWORD value from a BLOB.

DWORD GetDwordFromBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  DWORD *pDword
);

Parameters

hBlob
[in] Handle to a BLOB.
pOwnerName
[in] Pointer to the BLOB owner name.
pCategoryName
[in] Pointer to the BLOB category name.
pTagName
[in] Pointer to the BLOB tag name.
pDword
[out] Pointer to the DWORD value of the BLOB.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetDwordInBlob, GetBoolFromBlob, GetClassIDFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob, GetStringsFromBlob


GetMacAddressFromBlob

The GetMacAddressFromBlob function retrieves the named MAC address from a BLOB.

DWORD GetMacAddressFromBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  BYTE *pMacAddress
);

Parameters

hBlob
[in] Handle to a BLOB.
pOwnerName
[in] Pointer to the BLOB owner name.
pCategoryName
[in] Pointer to the BLOB category name.
pTagName
[in] Pointer to the BLOB tag name.
pMacAddress
[out] Pointer to the MAC address of the BLOB.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetMacAddressInBlob, GetBoolFromBlob, GetClassIDFromBlob, GetDwordFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob, GetStringsFromBlob


GetNetworkInfoFromBlob

The GetNetworkInfoFromBlob function retrieves network information from a given BLOB.

DWORD GetNetworkInfoFromBlob(
  HBLOB hBlob,
  LPNETWORKINFO lpNetworkInfo
);

Parameters

hBlob
[in] Handle to a BLOB.
lpNetworkInfo
[in, out] A pointer to the user-allocated NETWORKINFO structure that is filled in.

Return Values

If the GetNetworkInfoFromBlob function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Remarks

The network information is stored in the BLOB NetworkInfo section of the BLOB NPP Owner category.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetNetworkInfoInBlob, GetBoolFromBlob, GetClassIDFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob, GetStringsFromBlob


GetNPPAddressFilterFromBlob

The GetNPPAddressFilterFromBlob function fills in the given address filter with information stored in the BLOB.

DWORD GetNPPAddressFilterFromBlob(
  HBLOB hBlob,
  LPADDRESSTABLE pAddressTable,
  HBLOB hErrorBlob
);

Parameters

hBlob
[in] Handle to a BLOB.
pAddressTable
[in, out] Pointer to the user-allocated address table.
hErrorBlob
[out] Handle to an error BLOB that specifies where in the original BLOB the error (if any) occurred.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that describes the error.

Remarks

The address information is stored in the Config section of the BLOB NPP Owner category.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetNPPAddressFilterInBlob, GetBoolFromBlob, GetClassIDFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob, GetStringsFromBlob


GetNPPBlobFromUI

The GetNPPBlobFromUI function selects a register NIC.

DWORD GetNPPBlobFromUI(
  HWND hwnd,
  HBLOB hFilterBlob,
  HBLOB *phBlob
);

Parameters

hwnd
[in] Handle to a window that displays the Select a network dialog box.
hFilterBlob
[in] Handle to a filter BLOB used to limit which NICs are displayed.
phBlob
[out] Pointer to the handle of the BLOB that represents the selected NIC.

Return Values

If the function is successful (the user selects a NIC), the return value is NMERR_SUCCESS, and the BLOB that phBlob points to is filled in.

If the user does not select an NIC, the return value is NMERR_NO_NPP_SELECTED.

If the function is unsuccessful, the return value is another NMERR value.

Remarks

When called, Network Monitor displays the Select a network dialog box, which you can use to select a NIC. The NPP BLOB that represents the NIC is returned to the calling application.

If the BLOB named by hFilterBlob is a special BLOB, the finder will attempt to process it. An example would be a call that had previously returned a special BLOB from the remote NPP. The application inserted the required tag, MACHINE_NAME. In this situation, the finder would pass this BLOB to the remote NPP, which would then return a table of NPP BLOBs representing the machine requested. These remote NPP BLOBs would appear in the dialog box.

The caller is responsible for calling the DestroyBlob function, which destroys the returned BLOB when it is no longer needed.

For information about | See
Three ways to select NICs | Selecting a Network Interface Card
Specifying a filter BLOB | Specifying a Filter BLOB

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Finder.h.
Library: Use NPPTools.lib.

See Also

GetNPPBlobTable, SelectNPPBlobFromTable


GetNPPBlobTable

The GetNPPBlobTable function retrieves an NPP BLOB table that represents the register NICs on the local computer.

DWORD GetNPPBlobTable(
  HBLOB hFilterBlob,
  PBLOB_TABLE *ppBlobTable
);

Parameters

hFilterBlob
[in] Handle to a filter BLOB that limits the NPP BLOBs returned in the table.
ppBlobTable
[out] Pointer to a BLOB_TABLE structure that contains at least one BLOB pointer.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is an error code.

Error Codes

NMERR_NO_NPP_DLL
No DLLs were found in the NPP directory.
NMERR_NO_VALID_NPP_DLLS
None of the DLLs in the NPP directory were valid NPP DLLs.
NMERR_NO_MATCHING_NPPS
NPP BLOBs were discovered, but none passed the filter test.
NMERR_OUT_OF_MEMOR
Network Monitor was not able to allocate memory.

Remarks

The BLOB named by hFilterBlob can also be a special BLOB.

If you set the flag in the filter BLOB to TRUE, the returned BLOB table can also include special BLOBs .

If the BLOB named by hFilterBlob is a special BLOB, the Network Monitor UI will attempt to process it. For example, suppose that a previous call returns a special BLOB from the remote NPP. The application inserts the required tag, MACHINE_NAME. The finder then passes this BLOB to the remote NPP, which then returns a table of the NPP BLOBs associated with the machine name.

To destroy all returned BLOBs and the BLOB table, the caller is responsible for calling the DestroyBlob function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Finder.h.
Library: Use NPPTools.lib.


GetNPPEtypeSapFilter

The GetNPPEtypeSapFilter function retrieves the Etype/Sap filter from a given BLOB.

DWORD GetNPPEtypeSapFilter(
  HBLOB hBlob,
  WORD *pnSaps,
  WORD *pnEtypes,
  LPBYTE *ppSapTable,
  LPWORD *ppEtypeTable,
  DWORD *pFilterFlags,
  HBLOB hErrorBlob
);

Parameters

hBlob
[in] Handle to the BLOB.
pnSaps
[out] Pointer to the returned number of protocols in the SAP table.
pnEtypes
[out] Pointer to the returned number of Etypes in the Etype table.
ppSapTable
[out] Pointer to the returned SAP table.
ppEtypeTable
[out] Pointer to the returned Etype table.
pFilterFlags
[out] Pointer to the returned filter flags.
hErrorBlob
[out] Handle to an error BLOB, which specifies the location in the original BLOB where the error (if any) occurred.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Remarks

The Etype/Sap information is stored in the Config category of the NPP Owner section.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetNPPEtypeSapFilter


GetNPPMacTypeAsNumber

The GetNPPMacTypeAsNumber function retrieves the MAC type from the NetworkInfo category of the NPP section of the BLOB and converts the type data into a MAC type number.

DWORD GetNPPMacTypeAsNumber(
  HBLOB hBlob,
  LPDWORD lpMacType
);

Parameters

hBlob
[in] Handle to the specified BLOB.
lpMacType
[out] Pointer to the MAC type.

Remarks

This function maps the tag, NPP:NetworkInfo:MacType to the MAC_TYPE_* as defined in the Npptypes.h file.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the tag is unavailable, the return value is MAC_TYPE_UNKNOWN.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.


GetNPPPatternFilterFromBlob

The GetNPPPatternFilterFromBlob function retrieves the pattern match filter from a specific BLOB.

DWORD GetNPPPatternFilterFromBlob(
  HBLOB hBlob,
  LPEXPRESSION pExpression,
  HBLOB hErrorBlob
);

Parameters

hBlob
[in] Handle to the BLOB.
pExpression
[in] Pointer to the filter expression.
hErrorBlob
[out] Handle to an error BLOB that specifies where in the original BLOB the error (if any) occurred.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR that indicates the error.

Remarks

The pattern match filter information is stored in the Config category of the BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetNPPPatternFilterInBlob, GetBoolFromBlob, GetClassIDFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob, GetStringsFromBlob


GetNPPTriggerFromBlob

The GetNPPTriggerFromBlob function retrieves the trigger from the given BLOB.

DWORD GetNPPTriggerFromBlob(
  HBLOB hBlob,
  LPTRIGGER pTrigger,
  HBLOB hErrorBlob
);

Parameters

hBlob
[in] Handle to the BLOB.
pTrigger
[out] Pointer to the trigger value.
hErrorBlob
[out] Handle to an error BLOB that specifies where in the original BLOB the error (if any) occurred.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Remarks

The trigger information is stored in the Trigger category of the BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetBoolFromBlob, GetClassIDFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetStringFromBlob, GetStringsFromBlob


GetStringFromBlob

The GetStringFromBlob function returns a string located at a given position within a BLOB.

DWORD GetStringFromBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  const char **ppString
);

Parameters

hBlob
[in] Handle to the BLOB.
pOwnerName
[in] BLOB Owner section where the string is located.
pCategoryName
[in] BLOB Category section where the string is located.
pTagName
[in] Tag of the requested string.
ppString
[out] Pointer to a variable that points to the string that is returned.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

If the specified Owner, Category, or Tag information does not exist, the function returns NMERR_BLOB_ENTRY_DOES_NOT_EXIST.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetStringInBlob GetBoolFromBlob, GetClassIDFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringsFromBlob


GetStringsFromBlob

The GetStringsFromBlob function uses sequential calls to retrieve all of the strings within specified ranges.

DWORD GetStringsFromBlob(
  HBLOB hBlob,
  const char *pRequestedOwnerName,
  const char *pRequestedCategoryName,
  const char *pRequestedTagName,
  const char **ppReturnedOwnerName,
  const char **ppReturnedCategoryName,
  const char **ppReturnedTagName,
  const char **ppReturnedString,
  DWORD *pRestartKey
);

Parameters

hBlob
[in] Handle to the BLOB.
pRequestedOwnerName
[in] Pointer to the Owner section to get the string from.
pRequestedCategoryName
[in] Pointer to the Category section to get the string from.
pRequestedTagName
[in] Pointer to the tag for the requested string.
ppReturnedOwnerName
[out] Pointer to the variable that points to where the Owner name will be returned.
ppReturnedCategoryName
[out] Pointer to the variable that points to where the Category name will be returned.
ppReturnedTagName
[out] Pointer to the variable that points to where the Tag name will be returned.
ppReturnedString
[out] Pointer to the variable that points to where the string name will be returned.
pRestartKey
[out] Pointer to the variable where the restart key will be specified and returned.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the problem.

If a specified combination of Owner, Category, and Tag information does not exist, the return value is NMERR_BLOB_ENTRY_DOES_NOT_EXIST.

When the BLOB is traversed completely within the bounds initially specified, the function returns NMERR_BLOB_ENTRY_DOES_NOT_EXIST, and the pRestartKey parameter points to zero.

Remarks

On the initial call to the GetStringsFromBlob function, the pRestartKey parameter points to a variable that contains the value zero. The pRequested parameters can be used only when the restart key is zero. On subsequent calls, when pRestartKey has nonzero values, the pRequested parameters are ignored. On the initial call, all may point to NULL, which sets up the query to return every entry in the BLOB, one per subsequent call.

Specifying an owner limits the strings returned to just that owner. A similar limitation is true for categories and tags, with the additional caveat that if a category is specified, an owner must also be specified and if a tag is specified, a category (and therefore an owner) must be specified.

When the initial call to GetStringsFromBlob returns, pRestartKey points to a new value, which should be specified on the next call to the function to get the next value.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

SetStringInBlob GetBoolFromBlob, GetClassIDFromBlob, GetDwordFromBlob, GetMacAddressFromBlob, GetNetworkInfoFromBlob, GetNPPAddressFilterFromBlob, GetNPPPatternFilterFromBlob, GetNPPTriggerFromBlob, GetStringFromBlob


IsRemoteNPP

The IsRemoteNPP function indicates whether the given BLOB specifies a remote NPP.

BOOL IsRemoteNPP(
  HBLOB hBlob
);

Parameters

hBlob
[in] Handle to a BLOB.

Return Values

If the function is successful, the return value is TRUE.

Remarks

Use this function to test whether a remote category exists.

Make certain that the remote and local computer names are different.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.


MergeBlob

The MergeBlob function copies all of the entries from the source BLOB into a destination BLOB.

DWORD MergeBlob(
  HBLOB hDstBlob,
  HBLOB hSrcBlob
);

Parameters

hDstBlob
[in, out] Handle to the destination BLOB. On input, this BLOB contains its original information. On output, this BLOB contains its original information plus all the information of the source BLOB.
hSrcBlob
[in] Handle to the source BLOB.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Remarks

Entries common to source and destination files will be overwritten with data from the source BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.


RegCreateBlobKey

The RegCreateBlobKey function stores a BLOB at the given registry key.

DWORD RegCreateBlobKey(
  HKEY hkey,
  const char *szBlobName,
  HBLOB hBlob
);

Parameters

hkey
[out] Handle to the registry key where the BLOB will be stored.
szBlobName
[in] Name (application defined) that represents the BLOB in the registry.
hBlob
[in] Handle to the BLOB that is saved.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

RegOpenBlobKey


RegOpenBlobKey

The RegOpenBlobKey function retrieves a BLOB stored at the given registry key.

DWORD RegOpenBlobKey(
  HKEY hkey,
  const char *szBlobName,
  HBLOB *phBlob
);

Parameters

hkey
[in] Handle to the registry key that contains the BLOB.
szBlobName
[in] Name that identifies the given BLOB in the registry.
phBlob
[out] Pointer to the BLOB that is retrieved.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

RegCreateBlobKey


RemoveFromBlob

The RemoveFromBlob function deletes any level of BLOB entry (Owner, Category, or Tag).

DWORD RemoveFromBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName
);

Parameters

hBlob
[in] Handle to the BLOB from which an entry is deleted.
pOwnerName
[in] Pointer to the Owner name.
pCategoryName
[in] Pointer to the Category name. A NULL parameter value indicates the caller is attempting to delete the given Owner information and all of its child entries. Note that if the pCategoryName parameter value is NULL, the pTagName parameter must also be NULL.
pTagName
[in] Pointer to the Tag name. A NULL pTagName value indicates the caller is attempting to delete the given Category and all of its child entries. If the parameter value is not NULL, the caller is asking that only that the specified Tag entries be deleted.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.


SelectNPPBlobFromTable

The SelectNPPBlobFromTable function selects a NIC from a supplied NPP BLOB table.

DWORD SelectNPPBlobFromTable(
  HWND hwnd,
  PBLOB_TABLE pBlobTable,
  HBLOB *hBlob
);

Parameters

hwnd
[in] Handle to the window that displays the Select a network dialog box.
pBlobTable
[in] Pointer to the supplied BLOB table. Network Monitor uses this table to populate the Select a network dialog box.
hBlob
[out] Handle to the BLOB that represents the selected NIC.

Return Values

If the function is successful and the user selects a NIC, the return value is NMERR_SUCCESS; the BLOB pointed to by hBlob is filled in.

If the user does not select a NIC, the return value is NMERR_NO_NPP_SELECTED.

If the function is unsuccessful, the return value is another NMERR value.

Remarks

When called, Network Monitor displays the Select a network dialog box, which you can use to select a NIC. The NPP BLOB that represents the selected NIC returns to the calling application.

To learn the various ways you can select NICs, see Selecting a Network Interface Card

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Finder.h.
Library: Use NPPTools.lib.

See Also

GetNPPBlobFromUI, GetNPPBlobTable, Special BLOB Entries


SetBoolInBlob

The SetBoolInBlob function sets a Boolean value at a given location within a BLOB.

DWORD SetBoolInBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  BOOL Bool
);

Parameters

hBlob
[in] Handle to a BLOB.
pOwnerName
[in] Pointer to the BLOB Owner name.
pCategoryName
[in] Pointer to the BLOB Category name.
pTagName
[in] Pointer to the BLOB Tag name.
Bool
[in] Boolean value that is set at the given location.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetBoolFromBlob, SetClassIDInBlob, SetDwordInBlob, SetMacAddressInBlob, SetNetworkInfoInBlob, SetNPPAddressFilterInBlob, SetNPPPatternFilterInBlob, SetNPPTriggerInBlob, SetStringInBlob


SetClassIDInBlob

The SetClassIDInBlob function sets the named class identifier value of a BLOB.

DWORD SetClassIDInBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  const CLSID *pClsID
);

Parameters

hBlob
[in] Handle to a BLOB.
pOwnerName
[in] Pointer to the BLOB Owner name that is set.
pCategoryName
[in] Pointer to the BLOB Category name that is set.
pTagName
[in] Pointer to the BLOB Tag name that is set.
pClsID
[in] Pointer to the class identifier of the BLOB that is set.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetClassIDFromBlob, SetBoolInBlob, SetDwordInBlob, SetMacAddressInBlob, SetNetworkInfoInBlob, SetNPPAddressFilterInBlob, SetNPPPatternFilterInBlob, SetNPPTriggerInBlob, SetStringInBlob


SetDwordInBlob

The SetDwordInBlob function sets the named DWORD value of a BLOB.

DWORD SetDwordInBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  DWORD Dword
);

Parameters

hBlob
[in] Handle to a BLOB being set.
pOwnerName
[in] Pointer to the BLOB Owner name being set.
pCategoryName
[in] Pointer to the BLOB Category name being set.
pTagName
[in] Pointer to the BLOB Tag name being set.
Dword
[in] DWORD value of the BLOB being set.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetDwordFromBlob, SetBoolInBlob, SetClassIDInBlob, SetMacAddressInBlob, SetNetworkInfoInBlob, SetNPPAddressFilterInBlob, SetNPPPatternFilterInBlob, SetNPPTriggerInBlob, SetStringInBlob


SetMacAddressInBlob

The SetMacAddressInBlob function sets the requested MAC address of a BLOB.

DWORD SetMacAddressInBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  const BYTE *pMacAddress
);

Parameters

hBlob
[in] Handle to the BLOB being set.
pOwnerName
[in] Pointer to the BLOB Owner name being set.
pCategoryName
[in] Pointer to the BLOB Category name being set.
pTagName
[in] Pointer to the BLOB Tag name being set.
pMacAddress
[in] Pointer to the MAC address of the BLOB being set.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetMacAddressFromBlob, SetBoolInBlob, SetClassIDInBlob, SetDwordInBlob, SetNetworkInfoInBlob, SetNPPAddressFilterInBlob, SetNPPPatternFilterInBlob, SetNPPTriggerInBlob, SetStringInBlob


SetNetworkInfoInBlob

The SetNetworkInfoInBlob function fills in the NETWORKINFO structure in the BLOB.

DWORD SetNetworkInfoInBlob(
  HBLOB hBlob,
  LPNETWORKINFO lpNetworkInfo
);

Parameters

hBlob
[in] Handle to a BLOB.
lpNetworkInfo
[in] Pointer to the user-allocated NETWORKINFO structure that the function fills in.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetNetworkInfoFromBlob, SetBoolInBlob, SetClassIDInBlob, SetDwordInBlob, SetMacAddressInBlob, SetNPPAddressFilterInBlob, SetNPPPatternFilterInBlob, SetNPPTriggerInBlob, SetStringInBlob


SetNPPAddressFilterInBlob

The SetNPPAddressFilterInBlob function sets the given address filter in the BLOB.

DWORD SetNPPAddressFilterInBlob(
  HBLOB hBlob,
  LPADDRESSTABLE pAddressTable
);

Parameters

hBlob
[in] Handle to a BLOB.
pAddressTable
[in] Pointer to the user-allocated address table.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetNPPAddressFilterFromBlob, SetBoolInBlob, SetClassIDInBlob, SetDwordInBlob, SetMacAddressInBlob, SetNetworkInfoInBlob, SetNPPPatternFilterInBlob, SetNPPTriggerInBlob, SetStringInBlob


SetNPPEtypeSapFilter

The SetNPPEtypeSapFilter function sets the BLOB Etype/Sap filter.

DWORD SetNPPEtypeSapFilter(
  HBLOB hBlob,
  WORD nSaps,
  WORD nEtypes,
  LPBYTE lpSapTable,
  LPWORD lpEtypeTable,
  DWORD FilterFlags,
  HBLOB hErrorBlob
);

Parameters

hBlob
[in] Handle to the BLOB.
nSaps
[in] Number of SAPs.
nEtypes
[in] Number of Etypes in the Etype table being set.
lpSapTable
[in] Pointer to the SAP table that is set.
lpEtypeTable
[in] Pointer to the Etype table that is set.
FilterFlags
[in] Filter flags that are set.
hErrorBlob
[out] Handle to an error BLOB that specifies where in the original BLOB the error (if any) occurred.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetNPPEtypeSapFilter


SetNPPPatternFilterInBlob

The SetNPPPatternFilterInBlob function sets the BLOB pattern match filter.

DWORD SetNPPPatternFilterInBlob(
  HBLOB hBlob,
  LPEXPRESSION pExpression,
  HBLOB hErrorBlob
);

Parameters

hBlob
[in] Handle to the BLOB.
pExpression
[in] Pointer to the filter expression being set.
hErrorBlob
[out] Handle to an error BLOB that specifies where in the original BLOB the error (if any) occurred.

Return Values

If the SetNPPPatternFilterInBlob function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Remarks

The pattern match filter information is stored in the Config category of the BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetNPPAddressFilterFromBlob, SetBoolInBlob, SetClassIDInBlob, SetDwordInBlob, SetMacAddressInBlob, SetNetworkInfoInBlob, SetNPPAddressFilterInBlob, SetNPPTriggerInBlob, SetStringInBlob


SetNPPTriggerInBlob

The SetNPPTriggerInBlob function sets the BLOB trigger.

DWORD SetNPPTriggerInBlob(
  HBLOB hBlob,
  LPTRIGGER pTrigger,
  HBLOB hErrorBlob
);

Parameters

hBlob
[in] Handle to the BLOB.
pTrigger
[in] Pointer to the trigger value.
hErrorBlob
[out] Handle to an error BLOB that specifies where in the original BLOB the error (if any) occurred.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Remarks

This trigger information is stored in the Trigger category of the BLOB.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetNPPTriggerFromBlob, SetBoolInBlob, SetClassIDInBlob, SetDwordInBlob, SetMacAddressInBlob, SetNetworkInfoInBlob, SetNPPAddressFilterInBlob, SetNPPPatternFilterInBlob, SetStringInBlob


SetStringInBlob

The SetStringInBlob function sets a string at a given location within a BLOB.

DWORD SetStringInBlob(
  HBLOB hBlob,
  const char *pOwnerName,
  const char *pCategoryName,
  const char *pTagName,
  const char *pString
);

Parameters

hBlob
[in] Handle to the BLOB.
pOwnerName
[in] Pointer to the Owner section of the BLOB, where the string is set.
pCategoryName
[in] Pointer to the Category section of the BLOB, where the string is set.
pTagName
[in] Pointer to the Tag of the requested string.
pString
[in] Pointer to the variable where a pointer to the string will be returned.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the problem.

If the specified Owner, Category, or Tag information does not exist, the return value is NMERR_BLOB_ENTRY_DOES_NOT_EXIST.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.

See Also

GetStringFromBlob, SetBoolInBlob, SetClassIDInBlob, SetDwordInBlob, SetMacAddressInBlob, SetNetworkInfoInBlob, SetNPPAddressFilterInBlob, SetNPPPatternFilterInBlob, SetNPPTriggerInBlob


WriteBlobToFile

The WriteBlobToFile function writes a BLOB to a file.

DWORD WriteBlobToFile(
  HBLOB hBlob,
  const char *pFileName
);

Parameters

hBlob
[in] Handle to the BLOB.
pFileName
[in] Pointer to the name of the file, in which the BLOB is saved.

Return Values

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value is a NMERR value that indicates the error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Blob.h.
Library: Use NPPTools.lib.


BLOB Structures

The BLOB Helper API includes the following structures.

Structure | Description
ADDRESS | Contains a single, supported address.
ADDRESSPAIR | Constructs a capture filter.
ADDRESSTABLE | Specifies a table of address pairs.
ANDEXP | Specifies an array of pattern matches.
BLOB_TABLE | Specifies an array of BLOBs.
CAPTUREFILE_HEADER_VALUES | Defines the structure of the Network Monitor header file.
CAPTUREFILTER | Specifies capture filter data.
EXPRESSION | Specifies an expression of peers structured in logical AND statements.
FRAME | Specifies a frame.
FRAME_DESCRIPTOR | Specifies details of raw frames.
FRAMETABLE | Specifies a set of frames.
GENERIC_PORT | Specifies a port number used in IP or IPX protocols.
IPX_ADDRESS | Specifies an IPX address.
NETWORKINFO | Specifies a NIC.
PATTERNMATCH | Specifies pattern elements used to evaluate frames.
TRIGGER | Specifies that an event occur at a specific time.
UPDATE_EVENT | Updates events.
VINES_IP_ADDRESS | Specifies an address on a Vines network.


ADDRESS

The ADDRESS structure contains a single address of any type of supported addresses.

typedef struct _ADDRESS
{
  DWORD  Type;
  union
{
  BYTE  MACAddress[MAC_ADDRESS_SIZE];
  BYTE  IPAddress[IP_ADDRESS_SIZE];
  BYTE  IPXRawAddress[IPX_ADDRESS_SIZE];
  IPX_ADDRESS  IPXAddress;
  BYTE  VinesIPRawAddress[VINES_IP_ADDRESS_SIZE];
  VINES_IP_ADDRESS  VinesIPAddress;
  ETHERNET_SRC_ADDRESS  EthernetSrcAddress;
  ETHERNET_DST_ADDRESS  EthernetDstAddress;
  TOKENRING_SRC_ADDRESS  TokenringSrcAddress;
  TOKENRING_DST_ADDRESS TokenringDstAddress;
  FDDI_SRC_ADDRESS  FddiSrcAddress;
  FDDI_DST_ADDRESS  FddiDstAddress;
};
    WORD   Flags;
} ADDRESS;
typedef ADDRESS *LPADDRESS;

Members

Type
Address type. Values can be one of the following:

ADDRESS_TYPE_ETHERNET
ADDRESS_TYPE_TOKENRING
ADDRESS_TYPE_FDDI

MACAddress[MAC_ADDRESS_SIZE]
View of the data expressed as a raw MAC address.
IPAddress[IP_ADDRESS_SIZE]
View of the data expressed as a raw IP address.
IPXRawAddress[IPX_ADDRESS_SIZE]
View of the data expressed as a raw IPX address.
IPXAddress
View of the data expressed as a decoded IPX address value.
VinesIPRawAddress[VINES_IP_ADDRESS_SIZE]
View of the data expressed as a raw Vines IP address.
VinesIPAddress
View of the data expressed as a decoded Vines IP address.
EthernetSrcAddress
View of the data expressed as an Ethernet source address.
EthernetDstAddress
View of the data expressed as an Ethernet destination address.
TokenringSrcAddress
A view of the data as a token ring source address.
TokenringDstAddress
A view of the data as a token ring destination address.
FddiSrcAddress
View of the data expressed as an FDDI source address.
FddiDstAddress
View of the data expressed as an FDDI destination address.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


ADDRESSPAIR

The ADDRESSPAIR structure constructs a capture filter.

typedef struct _ADDRESSPAIR
{
  WORD        AddressFlags;
  WORD        NalReserved;
  ADDRESS     DstAddress;
   ADDRESS     SrcAddress;
} ADDRESSPAIR;
typedef ADDRESSPAIR *LPADDRESSPAIR;

Members

AddressFlags
Flags that describe the addresses used by a capture filter.
Flag | Meaning
ADDRESS_FLAGS_MATCH_DST | Matches the destination address.
ADDRESS_FLAGS_MATCH_SRC | Matches the source address.
ADDRESS_FLAGS_ | Excludes the frame if this address is found.
ADDRESS_FLAGS_DST_GROUP_ADDR | Matches group bit only. Use this for broadcast-type messages.
ADDRESS_FLAGS_MATCH_BOTH | Matches destination and source addresses.

NalReserved
This is reserved.
DstAddress
Destination address of the address pair element.
SrcAddress
Source address of the address pair element.

Remarks

For more information about implementing this structure, see Capture Filters .

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

ADDRESSPAIR, CAPTUREFILTER


ADDRESSTABLE

The ADDRESSTABLE structure contains a table of address pairs.

typedef struct _ADDRESSTABLE
{
  DWORD           nAddressPairs;
  DWORD           nNonMacAddressPairs;
  ADDRESSPAIR     AddressPair[MAX_ADDRESS_PAIRS];
} ADDRESSTABLE;

typedef ADDRESSTABLE *LPADDRESSTABLE;

Members

nAddressPairs
Number of address pairs in the AddressPair array.
nNonMacAddressPairs
Number of non-MAC address pairs.
AddressPair[MAX_ADDRESS_PAIRS]
Array of address pairs. Note that you may only store up to eight address pairs per ADDRESSTABLE structure.

Remarks

Use this structure as part of the capture filter construction process. For more information about implementing this structure, see Capture Filters.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

ADDRESSPAIR, CAPTUREFILTER


ANDEXP

The ANDEXP structure contains an array of pattern matches used to evaluate frame data.

typedef struct _ANDEXP
{
  DWORD            nPatternMatches;
  PATTERNMATCH     PatternMatch[MAX_PATTERNS];
} ANDEXP;
typedef ANDEXP *LPANDEXP;

Members

nPatternMatches
Number of pattern matches.
PatternMatch[MAX_PATTERNS]
Array of pattern match elements. Note that each ANDEXP structure can contain up to four pattern match elements. For more information about this member, see Capture Filters.

Remarks

The patterns in the PatternMatch[MAX_PATTERNS] array are joined as peers in logical OR statements in the format

(Pattern 1 || Pattern 2 || Pattern 3).

For more information about implementing this structure, see Capture Filters .

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

PATTERNMATCH


BLOB_TABLE

The BLOB_TABLE structure contains an array of BLOBs.

typedef struct {
  DWORD  dwNumBlobs;
  HBLOB  hBlobs[0];
} BLOB_TABLE;
typedef BLOB_TABLE *PBLOB_TABLE;

Members

dwNumBlobs
Indicator that many BLOBs follow.
hBlobs[0]
Handle to the BLOB array.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in Finder.h.


CAPTUREFILE_HEADER_VALUES

The CAPTUREFILE_HEADER_VALUES structure defines the Network Monitor header file structure.

typedef struct _CAPTUREFILE_HEADER_VALUES
{
  DWORD Signature;
  BYTE BCDVerMinor;
  BYTE BCDVerMajor;
  WORD MacType;
  SYSTEMTIME TimeStamp;
  DWORD FrameTableOffset;
  DWORD FrameTableLength;
  DWORD UserDataOffset;
  DWORD UserDataLength;
  DWORD CommentDataOffset;
  DWORD CommentDataLength;
  DWORD StatisticsOffset;
  DWORD StatisticsLength;
  DWORD NetworkInfoOffset;
  DWORD NetworkInfoLength;
  DWORD ConversationStatsOffset;
  DWORD ConversationStatsLength;
} CAPTUREFILE_HEADER_VALUES;

typedef CAPTUREFILE_HEADER_VALUES *LPCAPTUREFILE_HEADER_VALUES;

Members

Signature
Unique identifier: 'GMBU.
BCDVerMinor
Binary, coded decimal (minor). The value of this member should be zero (0).
BCDVerMajor
Binary coded decimal (major). Note that this should be 2.
MacType
Topology type.
TimeStamp
Time of capture.
FrameTableOffset
Frame index table.
FrameTableLength
Frame index table size.
UserDataOffset
User data offset.
UserDataLength
User data length.
CommentDataOffset
Comment data offset.
CommentDataLength
Length of comment data.
StatisticsOffset
Offset to the STATISTICS structure.
StatisticsLength
Length of the STATISTICS structure.
NetworkInfoOffset
Offset to the NETWORKINFO structure.
NetworkInfoLength
Length of the NETWORKINFO structure.
ConversationStatsOffset
This member is not used.
ConversationStatsLength
This member is not used.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


CAPTUREFILTER

The CAPTUREFILTER structure contains capture filter data.

typedef struct _CAPTUREFILTER
{
  DWORD  FilterFlags;
  LPBYTE lpSapTable;
   LPWORD  lpEtypeTable;
  WORD  nSaps;
  WORD  nEtypes;
  LPADDRESSTABLE  AddressTable;
  EXPRESSION FilterExpression;
  TRIGGER Trigger;
  DWORD nFrameBytesToCopy;
  RESERVED Reserved;
} CAPTUREFILTER;
typedef CAPTUREFILTER *LPCAPTUREFILTER;

Members

FilterFlags
Flags that describe the contents of the capture filter.
Flag | Value | Meaning | Rules
CAPTUREFILTER_FLAGS_INCLUDE_ALL_SAPS | 0x0001 | Includes all SAPs as acceptable frames. | An array of SAP values referenced by lpSapTable indicates that all SAP values except those referenced by lpSapTable are valid.
CAPTUREFILTER_FLAGS_INCLUDE_ALL_ETYPES | 0x0002 | Include all Etypes as acceptable frames. | An array of Etype values passed by lpEtypeTable indicates that all Etype values except those referenced by lpEtypeTable are valid.
CAPTUREFILTER_FLAGS_LOCAL_ONLY | 0x0008 | No P-mode | If set, this capture filter will not set the NIC to P-mode; you will only see local traffic (frames captured to the local machine).
CAPTUREFILTER_FLAGS_KEEP_RAW | 0x0020 | Keep SMT and token ring MAC frames.

lpSapTable
Pointer to an array of SAP values. This member indicates the SAP values that are valid to pass to the driver. If CAPTUREFILTER_FLAGS_INCLUDE_ALL_SAPS is set, this becomes an exception list (include all SAPS except these).
lpEtypeTable
Pointer to an array of Etype values. This indicates those Etype values that are valid to pass to the driver. If CAPTUREFILTER_FLAGS_INCLUDE_ALL_ETYPES is set, this becomes an exception list (include all Etypes except these).
nSaps
Number of SAPs in the SAP table.
nEtypes
Number of Etypes in the Etype table.
AddressTable
Name of the address table.
FilterExpression
An EXPRESSION structure. This contains the pattern match portion of the capture filter.
Trigger
Reserved.
nFrameBytesToCopy
If the nFrameBytesToCopy field is not 0, then it specifies how many bytes to keep of each frame received. If it is 0, then keep the whole frame.
Reserved
Reserved.

Remarks

The combination of flags, values, and expressions determine which frames will be passed by the driver that uses this structure data. For more information about implementing a CAPTUREFILTER structure, see Capture Filters .

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

ADDRESSTABLE, ADDRESSPAIR, EXPRESSION, ANDEXP, PATTERNMATCH


EXPRESSION

The EXPRESSION structure contains a group of ANDEXP arrays that are evaluated as peers in logical AND expressions, which have the format

(ANDEXP 1 && ANDEXP 2 && ANDEXP 3).

typedef struct _EXPRESSION
{
  DWORD       nAndExps;
  ANDEXP      AndExp[MAX_PATTERNS];
} EXPRESSION;
typedef EXPRESSION *LPEXPRESSION;

Members

nAndExps
Number of ANDEXP patterns.
AndExp[MAX_PATTERNS]
Array of ANDEXP patterns. The capture filter arranges all rows of this array as logical AND statements. Note that each EXPRESSION structure can contain a maximum of four ANDEXP patterns.

Remarks

For information about implementing this structure as part of a capture filter, see Capture Filters .

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

ANDEXP, CAPTUREFILTER


FRAME

The FRAME structure is an actual frame from the driver.

typedef struct _FRAME
{
  __int64  TimeStamp;
  DWORD  FrameLength;
  DWORD  nBytesAvail;
  BYTE      MacFrame[0];
} FRAME;
typedef FRAME *LPFRAME;
typedef FRAME UNALIGNED *ULPFRAME;

Members

TimeStamp
Elapsed time, in microseconds, between the start of the capture and the time when the frame was captured.
FrameLength
MAC frame length.
nBytesAvail
Actual frame length copied.
MacFrame
Frame data.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


FRAME_DESCRIPTOR

The FRAME_DESCRIPTOR structure provides descriptive information about raw frames.

typedef struct _FRAME_DESCRIPTOR
{
  LPBYTE  FramePointer;
  __int64 TimeStamp;
  DWORD   FrameLength;
  DWORD   nBytesAvail;
  WORD    Etype;
  BYTE    Sap;
  BYTE    LowProtocol;
  WORD    LowProtocolOffset;
  GENERIC_PORT HighPort;
  WORD    HighProtocolOffset;
} FRAME_DESCRIPTOR;
typedef FRAME_DESCRIPTOR *LPFRAME_DESCRIPTOR;

Members

FramePointer
Pointer to frame data.
TimeStamp
System time, in microseconds, when the frame was captured. This time is typically used to determine the interval between the times two frames were captured.
FrameLength
MAC frame length.
nBytesAvail
Actual frame length copied.
Etype
Etype name.
Sap
SAP value.
LowProtocol
Index of protocol found.
LowProtocolOffset
Offset to protocol data obtained from LowProtocol.
HighPort
Port of high protocol identified in LowProtocol.
HighProtocolOffset
Offset to protocol data obtained from HighPort.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


FRAMETABLE

The FRAMETABLE structure, a circular buffer of frame pointers, is handed back to applications attached to the ITRC interface of the NPP.

typedef struct _FRAMETABLE
{
  DWORD  FrameTableLength;
  DWORD  StartIndex;
  DWORD  EndIndex;
  DWORD  FrameCount;
  FRAME_DESCRIPTOR  Frames[1];
} FRAMETABLE;
typedef FRAMETABLE *LPFRAMETABLE;

Members

FrameTableLength
The total length of the table.
StartIndex
The first index within the table.
EndIndex
The last index within the table.
FrameCount
The number of frames described by this table.
Frames
The actual array of frame descriptors.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


GENERIC_PORT

The GENERIC_PORT structure contains a port number used for IP or IPX protocols.

typedef union
{
  BYTE IPPort;
  WORD ByteSwappedIPXPort;
} GENERIC_PORT;

Members

IPPort
IP port number filled in .
ByteSwappedIPXPort
IPX port number filled in.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


IPX_ADDRESS

The IPX_ADDRESS structure provides an address at the IPX protocol level.

typedef struct _IPX_ADDRESS
{
  BYTE    Subnet[4];
  BYTE    Address[6];
} IPX_ADDRESS;
typedef IPX_ADDRESS *LPIPX_ADDRESS;

Members

Subnet[4]
Network subnet identifier.
Address[6]
Subnet NIC identifier.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


NETWORKINFO

The NETWORKINFO structure describes a NIC.

typedef struct _NETWORKINFO
{
  BYTE PermanentAddr[6];
  BYTE  CurrentAddr[6];
  ADDRESS  OtherAddress;
  DWORD  LinkSpeed;
  DWORD  MacType;
  DWORD  MaxFrameSize;
  DWORD  Flags;
  DWORD  TimestampScaleFactor;
  BYTE  NodeName[32];
  BOOL  PModeSupported;
  BYTE Comment[ADAPTER_COMMENT_LENGTH];
} NETWORKINFO;
typedef NETWORKINFO *LPNETWORKINFO;

Members

PermanentAddr[6]
Permanent MAC address.
CurrentAddr[6]
Current MAC address.
OtherAddress
Other address that support this (for example, IP, IPX).
LinkSpeed
Link speed, measured in Mbps.
MacType
Media type.
MaxFrameSize
Maximum frame size allowed.
Flags
Informational flags.
TimestampScaleFactor
For example, a value of 1 indicates 1/1 ms, 10 indicates 1/10 ms, 100 indicates 1/100 ms, and so on.
NodeName[32]
Name of remote workstation.
PModeSupported
NIC P-mode support indicator.
Comment[ADAPTER_COMMENT_LENGTH]
Adapter comment field.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


PATTERNMATCH

The PATTERNMATCH structure defines pattern elements used to evaluate a frame.

typedef struct _PATTERNMATCH
{
  DWORD        Flags;
  BYTE         OffsetBasis;
  GENERIC_PORT Port;
  WORD         Offset;
  WORD         Length;
  BYTE         PatternToMatch[MAX_PATTERN_LENGTH];
} PATTERNMATCH;
typedef PATTERNMATCH *LPPATTERNMATCH;

Members

Flags
Pattern match flags:
Flag | Value | Meaning
PATTERN_MATCH_FLAGS_NOT | 0x00000001 | When set, this flag retains frames that lack the specified pattern in the proper spot.
PATTERN_MATCH_FLAGS_PORT_SPECIFIED | 0x00000008 | Seeks a port number value.

OffsetBasis
Types of offset, which can be one of the following:
OFFSET_BASIS_RELATIVE_TO_FRAME | Sets an offset, in bytes, relative to start of the frame.
OFFSET_BASIS_RELATIVE_TO_EFFECTIVE_PROTOCOL | Sets an offset, in bytes, relative to the start of the referenced protocol.
OFFSET_BASIS_RELATIVE_TO_IPX | Sets an offset, in bytes, only relative to IPX.
OFFSET_BASIS_RELATIVE_TO_IP | Sets an offset, in bytes, only relative to IP.

Port
Port value, if specified.
Offset
The offset, in bytes, relative to the OffsetBasis.
Length
Length of the matched pattern.
PatternToMatch[MAX_PATTERN_LENGTH]
Pattern to match.

Remarks

This structure is used to construct a capture filter. For more information about implementing this structure, see Capture Filters.

A capture filter can contain up to four PATTERNMATCH structures.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.

See Also

CAPTUREFILTER


TRIGGER

The TRIGGER structure indicates an action to be taken by the driver at a specified time.

typedef struct _TRIGGER
{
  BOOL  TriggerActive;
  BYTE  TriggerType;
  BYTE  TriggerAction;
  DWORD TriggerFlags;
  PATTERNMATCH TriggerPatternMatch;
  DWORD TriggerBufferSize;
  DWORD Reserved;
} TRIGGER;
typedef TRIGGER *LPTRIGGER;

Members

TriggerActive
A Boolean value that determines if the trigger should be paid attention to by the driver.
TriggerType
The op code of the trigger.
TriggerAction
Action that the trigger is to take if it is fired.
TriggerFlags
Trigger flags.
TriggerPatternMatch
The trigger pattern match.
TriggerBufferSize
Trigger buffer size.
Reserved
Reserved.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


UPDATE_EVENT

The UPDATE_EVENT structure updates events. This structure is passed back to the calling application via the event status callback procedure by the NPP.

typedef struct _UPDATE_EVENT
{
  USHORT Event;
  DWORD  Action;
  DWORD Status;
  DWORD Value;
  __int64 TimeStamp;
  LPVOID lpUserContext;
  LPVOID  lpReserved;
  UINT FramesDropped;

    union
    {
       DWORD  Reserved;
       LPFRAMETABLE  lpFrameTable;
       DWORD   lpPacketQueue;
       SECURITY_PERMISSION_RESPONSE  SecurityResponse;
    };
    LPSTATISTICS lpFinalStats;
} UPDATE_EVENT;
typedef UPDATE_EVENT *PUPDATE_EVENT;

Members

Event
Actual event being recorded.
Action
The action taken.
Status
Network status indication.
Value
Auxiliary counter variable.
TimeStamp
The marked events, in microseconds.
lpUserContext
User context given by the application.
lpReserved
Driver or NAL use.
FramesDropped
RTF frames dropped in the specified buffer.
Reserved
No data comes back with this switch option.
lpFrameTable
RTF only.
lpPacketQueue
For transmits.
SecurityResponse
Remote security monitor response.
lpFinalStats
This is only filled in on non-security related stops (for example, triggers).

Remarks

C++ users should note that the declaration for this callback should be in the public part of the header file:

static WINAPI DWORD NetworkCallback( UPDATE_EVENT events);

The implementation should be in the protected section of the .cpp file:

DWORD WINAPI ClassName::NetworkCallback( UPDATE_EVENT events) {};

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


VINES_IP_ADDRESS

The VINES_IP_ADDRESS structure is an IP address on a Vines network.

typedef struct _VINES_IP_ADDRESS
{
  DWORD   NetID;
  WORD    SubnetID;
} VINES_IP_ADDRESS;
typedef VINES_IP_ADDRESS *LPVINES_IP_ADDRESS;

Members

NetID
The identifier of a specific machine on a specific subnet.
SubnetID
The identifier of a specific subnet on the whole network.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Version: Requires Network Monitor 2.0.
Header: Declared in NPPTypes.h.


Glossary

The Network Monitor documentation in the Platform SDK has its own nomenclature. Many of these terms are familiar to developers, but have new or altered definitions in the Network Monitor development environment. Please read the following list of definitions carefully to understand the meaning of the terms.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

address
Identifier of a network node that differentiates one node from another on a network. Also known as the net address, or MAC address. In the Microsoft® Systems Management Server (SMS), an address is used to connect a site and site system. A sender uses a specific address to send instructions and data to other sites.
address pair
Source and destination addresses of a data transmission. The destination can be a single address, multicast, or broadcast. In captured data, the source address is a specific address. In filter specifications, the source address can be a specific address, or ANY, but it cannot be broadcast or multicast.


B

BLOB
Abbreviation for a binary large object which is the generic data structure of Network Monitor. You can use a BLOB to communicate and store configuration and location information, and to store application-specific information — without affecting other data in a BLOB.
buffer
Reserved portion of memory where data is held temporarily waiting to complete a transfer to or from a storage device, or other location in memory.


C

capture
Network traffic data that is collected in frames. A network packet provider (NPP) performs a capture. See also delayed capture, and real-time capture
capture file
A file that Network Monitor creates to store captured data. The .cap file name extension identifies a capture file. Network Monitor randomly generates a capture file name, but you can change the file name when you save the capture file.

Network Monitor creates a capture file each time the capture process starts, and then keeps the file open during the capture process. You cannot access the contents of a capture file until the capture process is stopped and the capture file is closed.

capture filter
Set of Network Monitor functions used to restrict incoming frames that a monitor or network packet provider (NPP) application use.
capture trigger
Trigger event that is set to stop the capture process. The capture trigger event can be a temporary capture file that is directed to a specific level or data pattern that occurs in a captured frame.
captured data
Frames that have a defined set of criteria. The data frames are contained in a temporary capture file.
conversation statistics
Statistics of network traffic saved during a capture. These statistics include station and session information beginning when the capture process starts, and ending when the capture stops. If you pause the capture process, Network Monitor continues to add statistics when you resume the process. To retrieve conversation statistics, call the GetConversationStatistics method for the interface you are using.


D

delayed capture
Collected network traffic that is stored in a capture file. A network packet provider (NPP) performs a delayed capture. Parsers and experts use delayed captures. See also capture, and real-time capture
destination address
The address of the computer to which data is sent.
detail pane
The pane in the Network Monitor frame window that displays detailed information about the protocol properties. By default, the pane appears in the center of the window.
display filter
A filter used to limit the amount of captured data that is displayed in the frame viewer window. A display filter is a postfix stack of objects that can be an operator, value, or property.


E

ERP
Acronym of event reference page. See event reference page
event
Significant action that occurs in the Windows NT operating system, or in an application such as Network Monitor. An event can notify users, write an entry to a log, or do both. In Network Monitor, either the monitor control service, or an expert can report events that are displayed in the event viewer window.
event reference page (ERP)
HTML document that is displayed in the Network Monitor event viewer window, and associated with a defined event in an expert or monitor.
expert
DLL that manipulates the frames collected in a capture file. An expert can provide a summary or report based on the captured data. For example, a top user report.


F

filter BLOB
Binary large object (BLOB) used to restrict the search for a network interface card (NIC). Each entry in the filter BLOB must match an equivalent entry in the network packet provider (NPP) BLOB that represents the NIC. For example, an application can request only Ethernet cards, or cards that support a specific frame rate. You can use a filter BLOB to call the GetNPPBlobFromUI and GetNPPBlobTable functions.
follow set
Protocol set that follows a protocol. Network Monitor uses the follow set of a protocol if the parser cannot detect the next protocol from the data in the capture. See also handoff set
frame
Also called a packet. A packet of data that is transmitted as one unit over a network. Each frame follows the same basic organization, and contains control information such as synchronizing characters, station addresses, an error-checking value, and a variable amount of data.
frame viewer window
Network Monitor window that displays detailed information about individual frames. You can open several frame viewer windows at one time.


G

generic formatter
Property data formatter that Network Monitor provides. The generic formatter can format the data that is displayed in the details pane of the Network Monitor UI. When you want Network Monitor to use the generic formatter, you must specify the FormatPropertyInstance function in InstanceData member of the PROPERTYINFO structure of a property. See also generic formatter output


H

handoff set
Protocol set that follows a protocol. A parser uses the handoff set of a protocol if the parser can detect the next protocol from the data in the capture. See also follow set
handoff table
A table that contains the parser handoff set. You can use a handoff table to access the handoff set information — without accessing the parser-defined INI file. The handoff set information is stored in the INI file of each parser. See also handoff set
hex pane
The pane in the Network Monitor frame viewer window that shows the hexadecimal bytes transmitted in frames that are included in a capture. By default, the hex pane appears at the bottom of the window.


M

MAC address
See address
MCSVC
See monitor control service
monitor
Application that you can use as a diagnostic tool. A monitor surveys real-time network data on a network segment for specific types of frames. You can configure and run a monitor from the Monitor Control Tool. You can use the IP Range Monitor to survey data for frames that originate from computers with invalid IP addresses.
monitor control service (MCSVC)
Network Monitor service that uses the Monitor Control Tool to configure, start, and stop a monitor.


N

NDIS
Acronym for the network driver interface specification. See network driver interface specification
network driver interface specification (NDIS)
The specification for the interface between device drivers and a network. All transports call the NDIS interface to access and work with network interface cards.
Network Monitor agent
A Network Monitor component that is located on a computer running Microsoft® Windows NT® Workstation, or Windows NT® Server. The agent enables a remote computer to capture data from the network. When a Network Monitor installation connects remotely to the Network Monitor agent and initiates a capture, statistics from the capture are transferred over the network to the managing computer. The transfer proceeds at intervals specified when the connection is made.
network packet provider (NPP)
The Network Monitor component that collects network traffic in frames, and then passes the frames to an expert, monitor, and NPP application. An NPP uses the Network Monitor system driver (Nmnt.sys) to get the frames collected from the network, and provides several COM interfaces that pass the frames to an expert, monitor, and network packet provider (NPP) application where they can be displayed and analyzed.
NPP
Acronym for network packet provider. See network packet provider
NPP application
An application that bypasses both the Network Monitor UI and Monitor Control Tool, and connects directly to the network packet provider (NPP). An NPP application can connect to the NPP component with any of the five NPP COM interfaces.
NPP Finder
The Network Monitor component that communicates with NPPs.


P

packet
See frame
parser
Also called a protocol parser. A component that detects a specific protocol in a delayed capture. Each parser can detect one protocol. However, one parser DLL may contain multiple parsers.
parser.ini
A Network Monitor initialization file that contains a list of all the installed parsers. For each parser there is a comment string that describes the parser, the follow set of the parser, and any Help file associated with the parser. The parser INI file is updated when Network Monitor calls ParserAutoInstallInfo, or when the parser DLL calls CreateHandoffTable.
Perfmon
A software tool that allows you to view network performance-related variables that identify the activity of a process.
promiscuous mode
A state in which a network adapter card copies all the frames that pass over the network, regardless of the destination address to a local buffer. This mode enables Network Monitor to capture and display all network traffic.
property
A protocol element in a parser that describes a data field within a frame that is sent by using that protocol.
property database
An internal database that defines all the properties that a specific protocol supports. The property database contains a PROPERTYINFO structure for each property that the parser defines. Network Monitor uses the information in the database when it attaches a property definition to an instance of the property, and when it formats the property data that is displayed in the details pane of the Network Monitor UI.
protocol level
A logical grouping of protocol properties.

R

real-time capture
Network traffic that Network Monitor collects, and then stores in a buffer. A monitor displays real-time captures. See also capture, and delayed capture
Request for Comments (RFC)
A document that contains a published protocol standard. The Internet Architecture Board (IAB) controls the RFCs that are issued.
RFC
Acronym for request for comments. See request for comments


S

SAP
Acronym for service access point. See service access point
server message block (SMB)
File-level protocol that contains primitives, and is used for operations such as Open, Close, Read, and Write.
service access point (SAP)
A frame identifier.
session
A set of data packets that one station sends to another station during a capture. A session is a one-way exchange of packets in which each session has an owner (the station sending the data packets), and a partner (the station receiving the data packets). See also session_information
session information
Information that describes a session. Network Monitor saves session information during data capture. Session information is referred to as conversation statistics, and can be retrieved by a call to the GetConversationStatistics method. See also session, capture, and conversation_statistics
SMB
Acronym for server message block. See server message block
source address
A unique, hexadecimal number that identifies the computer from which data is sent.
special BLOB
Network packet provider (NPP), or filter binary large object (BLOB) that contains supplemental information that other BLOBs do not provide. See also network packet provider, and BLOB
station
A specific NIC installed on a computer that is capturing data. See also station information
station information
Information that describes a station. Network Monitor saves the station information during a data capture. Station information is also referred to as conversation statistics that you can retrieve by a call to the GetConversationStatistics method. See also station and conversation statistics
summary property
A parser-defined property used to group the properties of a protocol for display in the Network Monitor UI. A PROPERTYINFO structure defines a summary property in the same way that other parser-defined properties are defined. The summary property is typically the first property definition attached to a frame when Network Monitor calls the AttachProperties function.
summary pane
The pane in a Network Monitor frame viewer window that lists the frames contained in a capture file. For each frame, the summary pane lists the frame number, the time the frame is captured, the source and destination address of the frame, the protocols used to send the frame, and a brief description of the frame. If a raw address has an associated IP or IPX/XNS address, this address is displayed in Src Other Addr and Dst Other Addr. The address type (IP or IPX/XNS) appears in Type Other Addr.


T

total statistics
Statistics that the network interface card (NIC) reports, and Network Monitor generates. For example, the statistics for the network frames include the number of frames that the NIC reports, the number of frames that the NIC handles, the number of frames that are passed through the capture filter, and the number of frames stored in the buffer or capture file. For a complete list of these statistics, see the STATISTICS structure.
trigger
  1. A specified set of conditions that initiate an event in a Network Monitor expert or monitor.
  2. In Microsoft® SQL Server®, a stored procedure associated with a specific piece of data stored in the SMS site database. When an attempt to modify the data is made through the SMS Administrator Console or another SMS component, a trigger is called automatically.


W

Windows Management Instrumentation (WMI)
The Microsoft® implementation of a Distributed Management Task Force (DMTF) standard that identifies and manipulates objects.
WMI
Acronym for Windows Management Instrumentation. See Windows_Management_Instrumentation


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.