## Introduction

This Manual documents the programming interface and the source code of WinPcap. It offers a detailed description of the functions and structures exported to the programmers, along with a complete documentation of the WinPcap internals. Several tutorials and examples are provided as well.

You can follow the links at the beginning of this page or use the tree control at the left to reach the section you are interested in.

This documentation was created using (and abusing of) the free Doxygen documentation system, that can be found at http://www.doxygen.org.

## What is WinPcap

WinPcap is a free, public system for direct network access under Windows.
Most networking applications access the network through widely used system primitives, like sockets. This approach allows to easily transfer data on a network, because the OS copes with low level details (protocol handling, flow reassembly, etc.) and provides an interface similar to the one used to read and write on a file.

Sometimes however the 'easy way' is not enough, since some applications need a low level view in order to directly handle the network traffic. Therefore, they need raw access to the network, without the intermediation of entities like protocol stacks.

The purpose of WinPcap is to give this kind of access to Win32 applications; it provides facilities to:

- capture raw packets, both the ones destined to the machine where it's running and the ones exchanged by other hosts (on shared media)
- filter the packets according to user-specified rules before dispatching them to the application
- transmit raw packets to the network
- gather statistical values on the network traffic

This set of capabilities is obtained by means of a device driver, that is installed inside the networking portion of the Win32 kernels, plus a couple of DLLs.

All these features are exported through a powerful programming interface, easily exploitable by the applications and portable on different OSes. Documenting this interface, with the help of several examples, is the main goals of this manual, so if you are interested in it you can directly jump to the \ref wpcap.

### What kind of programs use WinPcap

WinPcap can be used by different kind of tools for network analysis, troubleshooting, security and monitoring. In particular, classical tools that rely on WinPcap are:

- network and protocol analyzers
- network monitors
- traffic loggers
- traffic generators
- user-level bridges and routers
- network intrusion detection systems (NIDS)
- network scanners
- security tools

### What WinPcap can't do

WinPcap receives and sends the packets independently from the protocols of the host, like TCP-IP. This means that it isn't able to block, filter or manipulate the traffic generated by other programs on the same machine: it simply sniffs the packets that transit on the wire. Therefore, it cannot be used by applications like traffic shapers, QoS schedulers and personal firewalls.

## Content of this manual

The purpose of this manual is the creation of a comprehensive and easy to browse documentation of the WinPcap architecture. You will find two main sections: \ref wpcap and \ref internals.

The first one can be used by the programmer that needs to exploit WinPcap from its application: it contains all the information about functions and data structures exported by the WinPcap API, a manual that explains how to write packet filters, and a page that explains how to include it in an application. A tutorial with several code samples is provided as well; it can be used to learn the basics of the WinPcap API with a step-by-step approach, but it offers also code snippets that show advanced features.

The second section is intended to WinPcap developers and maintainers, or to curious people that want to know how this system works: it provides a general description of the WinPcap architecture that explains how it works. Moreover, it documents the whole device driver structure, with the possibility to look at the source code, and the interface of packet.dll, the low-level WinPcap API. If you want to understand what happens inside WinPcap or if you need to extend it, this is the section you are interested in. \htmlonly

## Further Documentation

We suggest to give a look at the page http://winpcap.polito.it/docs/ for further and up to date documentation.

In particular, if you are interested in the structure and the internals of WinPcap, we suggest the reading of the following documents:

- Fulvio Risso, Loris Degioanni, An Architecture for High Performance Network Analysis, Proceedings of the 6th IEEE Symposium on Computers and Communications (ISCC 2001), Hammamet, Tunisia, July 2001
- Loris Degioanni, Development of an Architecture for Packet Capture and Network Traffic Analysis, Graduation Thesis, Politecnico Di Torino (Turin, Italy, Mar. 2000)

## Terminology

- For coherence with the literature, we will use the term packet even though frame is more accurate, since the capture process is done at the data-link layer and the data-link header is included in the frames received.
- The term Win9x will be used in this documentation to indicate the family of Microsoft OSes made up of Windows 95 and its derivates, i.e. Windows 98 and Windows ME. The term WinNTx will indicate the OSes built upon the NT kernel, starting from Windows NT 4, like for example Windows 2000, Windows XP, Windows .net Server and so on.

## Note

Our development and documentation efforts focus primarily on the Windows NT/2000/XP version of WinPcap. This choice is based on the fact that the majority of the WinPcap users work on NTx systems, but also that the 9x technology has been abandoned by Microsoft. Moreover, we assume that a person that needs to use a PC for an advanced task like network analysis installs an advanced OS on the machine. For this reason, this documentation will refer to the WinNTx drivers and APIs. Win9x versions are very similar in the concept but sometimes differ in the implementation, moreover the Win9x version of the API lack of some sophisticated functionality. This documentation will describe the whole API, but it will specify when a function is present only in Windows NTx.