<body>


/*! \mainpage WinPcap Documentation
\image html winpcap.gif
\htmlonly


<p><b>Author</b>:&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Loris Degioanni (<a href="mailto:degioanni@polito.it">degioanni@polito.it</a>),
<a href="http://netgroup.polito.it/winpcap">NetGroup</a>, Politecnico di Torino<br>
<b>Home page</b>:&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://winpcap.polito.it">http://winpcap.polito.it</a></p>


<hr>

\endhtmlonly

<h2>Modules</h2>
<p>
- \ref wpcap<br>
 - \ref wpcap_def<br>
 - \ref wpcap_fn<br>
 - \ref language<br>
 - \ref wpcapsamps<br>
  - \ref wpcapsamp1<br>
  - \ref wpcapsamp2<br>
 - \ref wpcap_tut<br>
  - \ref wpcap_tut1<br>
  - \ref wpcap_tut2<br>
  - \ref wpcap_tut3<br>
  - \ref wpcap_tut4<br>
  - \ref wpcap_tut5<br>
  - \ref wpcap_tut6<br>
  - \ref wpcap_tut7<br>
  - \ref wpcap_tut8<br>
  - \ref wpcap_tut9<br>
- \ref internals<br>
 - \ref NPF<br>
  - \ref NPF_include<br>
  - \ref NPF_code<br>
 - \ref packetapi<br>
  - \ref packet32h<br>
  - \ref packet32<br>
  - \ref packetsamps<br>
 - \ref compilation<br>
- \ref remote<br>
 - \ref remote_help<br>
 - \ref remote_struct<br>
 - \ref remote_func<br>
 - \ref remote_pri_struct<br>
 - \ref remote_pri_struct<br>
</p>

\htmlonly
<hr>

<h2>Introduction</h2>


<p>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.&nbsp;

</p>
<p>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.

</p>
<p>This documentation was
created using (and abusing of) the free Doxygen documentation system, that can
be found at <a href="http://www.doxygen.org/index.html">http://www.doxygen.org</a>.

</p>
<h2>What is WinPcap</h2>
<p>WinPcap is a free, public
system for direct network access under Windows.<br>
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.

</p>
<p>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.

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

<ul>
  <li>capture
    raw packets, both the ones destined to the machine where it's running and
    the ones exchanged by other hosts (on shared media)</li>
  <li>filter
    the packets according to user-specified rules before dispatching them to the
    application</li>
  <li>transmit raw packets to the network</li>
  <li>gather statistical values on the network traffic</li>
</ul>
<p>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.</p>

<p>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.</p>

<h3>What kind of programs use WinPcap</h3>
<p>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:</p>

<ul>
  <li>network and protocol analyzers</li>
  <li>network monitors</li>
  <li>traffic loggers</li>
  <li>traffic generators</li>
  <li>user-level bridges and routers</li>
  <li>network intrusion detection systems (NIDS)</li>
  <li>network scanners</li>
  <li>security tools</li>
</ul>
<h3>What WinPcap can't do</h3>
<p>WinPcap receives and sends
the packets <i>independently</i> 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.

\endhtmlonly</p>

<h2>Content of this manual</h2>
<p>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. </p>
<p>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. </p>
<p>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&nbsp;</p>
<h2>Further Documentation</h2>
<p>We suggest to give a look at the page <a href="http://winpcap.polito.it/docs/">http://winpcap.polito.it/docs/</a>
for further and up to date documentation.</p>
<p>In particular, if you are interested in
the structure and the internals of WinPcap, we suggest the reading of the
following documents:</p>
<ul>
  <li>Fulvio Risso, Loris Degioanni, <a href="http://www.polito.it/~risso/pubs/iscc01-wpcap.pdf">An
    Architecture for High Performance Network Analysis</a>, <i>Proceedings of
    the 6<sup>th</sup> IEEE Symposium on Computers and Communications (ISCC
    2001)</i>, Hammamet, Tunisia, July 2001</li>
  <li>Loris Degioanni, <a href="http://winpcap.polito.it/docs/th_degio.zip">Development
    of an Architecture for Packet Capture and Network Traffic Analysis</a>,
    Graduation Thesis, Politecnico Di Torino (Turin, Italy, Mar. 2000)
</ul>

<h2>Terminology</h2>
<ul>
  <li>For coherence with the literature, we will use the term <i>packet</i> even
    though <i>frame</i> 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.</li>
  <li>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.</li>
</ul>

<h2>Note</h2>
<p>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.</p>

<p>*/</p>
</body>


