From ea366e80c24dd4e6eedb6f03b619ab352867f615 Mon Sep 17 00:00:00 2001
From: basil00 <basil@reqrypt.org>
Date: Wed, 13 Feb 2019 09:06:07 +0800
Subject: [PATCH] Update WinDivert documentation.

---
 doc/windivert.html | 330 +++++++++++++++++++++++++++++++++++++--------
 1 file changed, 274 insertions(+), 56 deletions(-)

diff --git a/doc/windivert.html b/doc/windivert.html
index 7ab2d9c..5828015 100644
--- a/doc/windivert.html
+++ b/doc/windivert.html
@@ -40,11 +40,14 @@
 <li><a href="#divert_helper_hash_packet">6.8 WinDivertHelperHashPacket</a></li>
 <li><a href="#divert_helper_parse_ipv4_address">6.9 WinDivertHelperParseIPv4Address</li>
 <li><a href="#divert_helper_parse_ipv6_address">6.10 WinDivertHelperParseIPv6Address</li>
-<li><a href="#divert_helper_calc_checksums">6.11 WinDivertHelperCalcChecksums</a></li>
-<li><a href="#divert_helper_compile_filter">6.12 WinDivertHelperCompileFilter</a></li>
-<li><a href="#divert_helper_eval_filter">6.13 WinDivertHelperEvalFilter</a></li>
-<li><a href="#divert_helper_eval_ntoh"><h3>6.14 WinDivertHelperNtoh*</a></li>
-<li><a href="#divert_helper_eval_hton"><h3>6.15 WinDivertHelperHton*</a></li>
+<li><a href="#divert_helper_format_ipv4_address">6.11 WinDivertHelperFormatIPv4Address</li>
+<li><a href="#divert_helper_format_ipv6_address">6.12 WinDivertHelperFormatIPv6Address</li>
+<li><a href="#divert_helper_calc_checksums">6.13 WinDivertHelperCalcChecksums</a></li>
+<li><a href="#divert_helper_compile_filter">6.14 WinDivertHelperCompileFilter</a></li>
+<li><a href="#divert_helper_eval_filter">6.15 WinDivertHelperEvalFilter</a></li>
+<li><a href="#divert_helper_format_filter">6.16 WinDivertHelperFormatFilter</a></li>
+<li><a href="#divert_helper_ntoh"><h3>6.17 WinDivertHelperNtoh*</a></li>
+<li><a href="#divert_helper_hton"><h3>6.18 WinDivertHelperHton*</a></li>
 </ul>
 <li><a href="#filter_language">7. Filter Language</a></li>
 <ul>
@@ -736,6 +739,18 @@ have a valid digital signature
 </tr>
 <tr>
 <td>
+<tt>ERROR_SERVICE_DOES_NOT_EXIST</tt>
+</td>
+<td>
+1060
+</td>
+<td>
+The handle was opened with the <tt>WINDIVERT_FLAG_NO_INSTALL</tt> flag and
+the WinDivert driver is not already installed.
+</td>
+</tr>
+<tr>
+<td>
 <tt>ERROR_DRIVER_BLOCKED</tt>
 </td>
 <td>
@@ -767,13 +782,14 @@ disabled.
 </p><p>
 <b>Remarks</b><br>
 Opens a WinDivert handle for the given filter.
-Unless otherwise specified by <tt>flags</tt>, any packet that matches the
-filter will be diverted to the handle.
-Diverted packets can be read by the application with
+Unless otherwise specified by <tt>flags</tt>, any packet or event that
+matches the filter will be diverted to the handle.
+Diverted packets/events can be read by the application with
 <a href="#divert_recv"><tt>WinDivertRecv()</tt></a>.
 </p>
 <p>
-A typical application is only interested in a subset of all network traffic.
+A typical application is only interested in a subset of all network traffic
+or events.
 In this case the filter should <i>match as closely as possible</i> to
 the subset of interest.
 This avoids unnecessary overheads introduced by diverting packets to the
@@ -784,7 +800,10 @@ information.
 <p>
 The <i>layer</i> of the WinDivert handle is determined by the <tt>layer</tt>
 parameter.
-Currently the following layers are supported.
+See <a href="#divert_layers"><tt>WINDIVERT_LAYER</tt></a> for more
+information.
+Currently the following layers are supported:
+</p>
 <center>
 <table border="1" cellpadding="5" width="75%">
 <tr>
@@ -800,8 +819,8 @@ Description
 <tt>WINDIVERT_LAYER_NETWORK = 0</tt>
 </td>
 <td>
-The network layer.
-This is the default.
+Network packets to/from the local machine.
+This is the default layer.
 </td>
 </tr>
 <tr>
@@ -809,12 +828,35 @@ This is the default.
 <tt>WINDIVERT_LAYER_NETWORK_FORWARD</tt>
 </td>
 <td>
-The network layer (forwarded packets).
+Network packets passing through the local machine.
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_LAYER_FLOW</tt>
+</td>
+<td>
+Network flow established/deleted events.
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_LAYER_SOCKET</tt>
+</td>
+<td>
+Socket operation events.
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_LAYER_REFLECT</tt>
+</td>
+<td>
+WinDivert handle events.
 </td>
 </tr>
 </table>
 </center>
-</p>
 <p>
 Different WinDivert handles can be assigned different priorities by the
 <tt>priority</tt> parameter.
@@ -825,12 +867,14 @@ and so on, provided the packet matches the handle's filter.
 A packet is only diverted once per priority level, so handles should not
 share priority levels unless they use mutually exclusive filters.
 Otherwise it is not defined which handle will receive the packet first.
-Lower <tt>priority</tt> values represent higher priorities, with <tt>-1000</tt>
-being the highest priority, <tt>0</tt> the middle (and a good default)
-priority, and <tt>1000</tt> the lowest priority.
+Lower <tt>priority</tt> values represent higher priorities, with
+<tt>-30000</tt> being the highest priority, <tt>0</tt> the middle
+(and a good default) priority, and <tt>30000</tt> the lowest priority.
 </p>
 <p>
-The following flags are supported.
+Different flags affect how the opened handle behaves.
+The following flags are supported:
+</p>
 <center>
 <table border="1" cellpadding="5" width="75%">
 <tr>
@@ -867,23 +911,116 @@ WinDivert <a href="#filter_language">filter language</a>.
 </tr>
 <tr>
 <td>
-<tt>WINDIVERT_FLAG_DEBUG</tt>
+<tt>WINDIVERT_FLAG_RECV_ONLY</tt>
 </td>
 <td>
-This flag causes <a href="#divert_send"><tt>WinDivertSend()</tt></a> to block
-until the injected packet <i>exits</i> the Windows TCP/IP stack.
-By default, <a href="#divert_send"><tt>WinDivertSend()</tt></a> does not
-block and returns immediately after the packet <i>enters</i> the
-TCP/IP stack.
-The default mode is faster, but will not return an error code if the
-packet is lost or rejected for any reason; making debugging difficult.
+This flags forces the handle into <q>receive only</q> mode which effectively
+disables <a href="#divert_send"><tt>WinDivertSend()</tt></a>.
+This means that it is possible to block/capture packets or events but not
+inject them.
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_FLAG_READ_ONLY</tt>
+</td>
+<td>
+An alias for <tt>WINDIVERT_FLAG_RECV_ONLY</tt>.
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_FLAG_SEND_ONLY</tt>
+</td>
+<td>
+This flags forces the handle into <q>send only</q> mode which effectively
+disables <a href="#divert_recv"><tt>WinDivertRecv()</tt></a>.
+This means that it is possible to inject packets or events, but not
+block/capture them.
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_FLAG_WRITE_ONLY</tt>
+</td>
+<td>
+An alias for <tt>WINDIVERT_FLAG_SEND_ONLY</tt>.
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_FLAG_RECV_PARTIAL</tt>
+</td>
+<td>
+This flags enables <q>partial receives</q>.
+By default, if a packet is too big for the buffer passed to
+<a href="#divert_recv"><tt>WinDivertRecv()</tt></a>, the operation
+will fail with <tt>ERROR_INSUFFICIENT_BUFFER</tt>.
+This flag silences this error and only copies part of the packet
+up to the buffer size.
+The <tt>WINDIVERT_FLAG_RECV_PARTIAL</tt> behavior was the default
+on older (pre-2.0) versions of WinDivert.
+</td>
+</tr>
+<td>
+<tt>WINDIVERT_FLAG_NO_INSTALL</tt>
+</td>
+<td>
+This flags causes <tt>WinDivertOpen()</tt> to fail with 
+<tt>ERROR_SERVICE_DOES_NOT_EXIST</tt> if the WinDivert driver
+is not already installed.
+This flag is useful for querying the WinDivert state using a
+<tt>WINDIVERT_LAYER_REFLECT</tt> handle.
 </td>
 </tr>
 </table>
 </center>
-Note that only one of <tt>WINDIVERT_FLAG_SNIFF</tt> or
-<tt>WINDIVERT_FLAG_DROP</tt> may be set at the same time.
+<p>
+Note that any combination of
+<tt>(WINDIVERT_FLAG_SNIFF | WINDIVERT_FLAG_DROP)</tt> or
+<tt>(WINDIVERT_FLAG_RECV_ONLY | WINDIVERT_FLAG_SEND_ONLY)</tt> or
+<tt>(WINDIVERT_FLAG_RECV_PARTIAL | WINDIVERT_FLAG_SEND_ONLY)</tt>
+are considered invalid.
 </p>
+<p>
+Some layers have mandatory flags, as listed below:
+</p>
+<center>
+<table border="1" cellpadding="5" width="75%">
+<tr>
+<th>
+Layer
+</th>
+<th>
+Required Flags
+</th>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_LAYER_FLOW</tt>
+</td>
+<td>
+<tt>WINDIVERT_FLAG_SNIFF | WINDIVERT_FLAG_RECV_ONLY</tt>
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_LAYER_SOCKET</tt>
+</td>
+<td>
+<tt>WINDIVERT_FLAG_RECV_ONLY</tt>
+</td>
+</tr>
+<tr>
+<td>
+<tt>WINDIVERT_LAYER_REFLECT</tt>
+</td>
+<td>
+<tt>WINDIVERT_FLAG_SNIFF | WINDIVERT_FLAG_RECV_ONLY</tt>
+</td>
+</tr>
+</table>
+</center>
 </dd></dl>
 
 <a name="divert_recv"><h3>5.4 WinDivertRecv</h3></a>
@@ -1246,7 +1383,7 @@ When the packet queue is empty,
 <a href="#divert_recv"><tt>WinDivertRecv()</tt></a>
 will fail with <tt>ERROR_NO_DATA</tt>.
 </p>
-<dd></dl>
+</dd></dl>
 
 <a name="divert_close"><h3>5.9 WinDivertClose</h3></a>
 <table border="1" cellpadding="5"><tr><td>
@@ -1272,7 +1409,7 @@ Use <tt>GetLastError()</tt> to get the reason for the error.
 Closes a WinDivert handle created by
 <a href="#divert_open"><tt>WinDivertOpen()</tt></a>.
 </p>
-<dd></dl>
+</dd></dl>
 
 <a name="divert_set_param"><h3>5.10 WinDivertSetParam</h3></a>
 <table border="1" cellpadding="5"><tr><td>
@@ -1351,7 +1488,7 @@ and the maximum is 33554432 (32MB).
 </table>
 </center>
 </p>
-<dd></dl>
+</dd></dl>
 
 <a name="divert_get_param"><h3>5.11 WinDivertGetParam</h3></a>
 <table border="1" cellpadding="5"><tr><td>
@@ -1381,7 +1518,7 @@ Gets a WinDivert parameter.
 See <a href="#divert_set_param"><tt>WinDivertSetParam()</tt></a> for the list
 of parameters.
 </p>
-<dd></dl>
+</dd></dl>
 
 <hr>
 <a name="helper_programming_api"><h2>6. Helper Programming API</h2></a>
@@ -1687,11 +1824,12 @@ Use <tt>GetLastError()</tt> to get the reason for the error.
 </p><p>
 <b>Remarks</b><br>
 Parses an IPv4 address stored in <tt>addrStr</tt>.
-If <tt>pAddr</tt> is non-<tt>NULL</tt>, the is be stored in
+If <tt>pAddr</tt> is non-<tt>NULL</tt>, the result is be stored in
 host-byte-order.
-Use <tt>htonl()</tt> to convert the result into network-byte-order.
+Use <a href="#divert_helper_hton"><tt>WinDivertHelperHtonl()</tt></a>
+to convert the result into network-byte-order.
 </p>
-<dd></dl>
+</dd></dl>
 
 <a name="divert_helper_parse_ipv6_address"><h3>6.10 WinDivertHelperParseIPv6Address</h3></a>
 <table border="1" cellpadding="5"><tr><td>
@@ -1719,23 +1857,68 @@ Parses an IPv6 address stored in <tt>addrStr</tt>.
 If <tt>pAddr</tt> is non-<tt>NULL</tt>, the buffer assumed 
 to be large enough to hold a 16-byte IPv6 address.
 The result is stored in host-byte-order.
-For example, given an IPv6 address of the form
-<tt>0011:2233:4455:6677:8899:aabb:ccdd:eeff</tt>, then
-the result is ordered as follows:
-<pre>
-pAddr[0] = 0xccddeeff
-pAddr[1] = 0x8899aabb
-pAddr[2] = 0x44556677
-pAddr[3] = 0x00112233
-</pre>
-where each <tt>pAddr[i]</tt> is in host-byte-order.
-The result can be converted into network-byte-order by setting
-<tt>pAddr[i] = htonl(pAddr[i])</tt> for each <tt>i</tt> and
-swapping the array indexes.
+Use <a href="#divert_helper_hton"><tt>WinDivertHelperHtonIpv6Address()</tt></a>
+to convert the result into network-byte-order.
 </p>
-<dd></dl>
+</dd></dl>
 
-<a name="divert_helper_calc_checksums"><h3>6.11 WinDivertHelperCalcChecksums</h3></a>
+<a name="divert_helper_format_ipv4_address"><h3>6.11 WinDivertHelperParseIPv4Address</h3></a>
+<table border="1" cellpadding="5"><tr><td>
+<pre>
+BOOL <b>WinDivertHelperFormatIPv4Address</b>(
+    __in UINT32 addr,
+    __out char *buffer,
+    __in UINT bufLen
+);
+</pre>
+</td></tr></table>
+<dl><dd>
+<p>
+<b>Parameters</b><br>
+<ul>
+<li> <tt>addr</tt>: The IPv4 address in host-byte order.</li>
+<li> <tt>buffer</tt>: The buffer to store the formatted string.</li>
+<li> <tt>bufLen</tt>: The length of <tt>buffer</tt>.
+</ul>
+</p><p>
+<b>Return Value</b><br>
+<tt>TRUE</tt> if successful, <tt>FALSE</tt> if an error occurred.
+Use <tt>GetLastError()</tt> to get the reason for the error.
+</p><p>
+<b>Remarks</b><br>
+Convert an IPv4 address into a string.
+</p>
+</dd></dl>
+
+<a name="divert_helper_format_ipv6_address"><h3>6.12 WinDivertHelperParseIPv6Address</h3></a>
+<table border="1" cellpadding="5"><tr><td>
+<pre>
+BOOL <b>WinDivertHelperFormatIPv6Address</b>(
+    __in const UINT32 *pAddr,
+    __out char *buffer,
+    __in UINT bufLen
+);
+</pre>
+</td></tr></table>
+<dl><dd>
+<p>
+<b>Parameters</b><br>
+<ul>
+<li> <tt>pAddr</tt>: The IPv6 address in host-byte order.</li>
+<li> <tt>buffer</tt>: The buffer to store the formatted string.</li>
+<li> <tt>bufLen</tt>: The length of <tt>buffer</tt>.
+</ul>
+</p><p>
+<b>Return Value</b><br>
+<tt>TRUE</tt> if successful, <tt>FALSE</tt> if an error occurred.
+Use <tt>GetLastError()</tt> to get the reason for the error.
+</p><p>
+<b>Remarks</b><br>
+Convert an IPv6 address into a string.
+</p>
+</dd></dl>
+
+<a name="divert_helper_calc_checksums"><h3>6.13 WinDivertHelperCalcChecksums</h3></a>
 <table border="1" cellpadding="5"><tr><td>
 <pre>
 UINT <b>WinDivertHelperCalcChecksums</b>(
@@ -1795,7 +1978,7 @@ order to (re)inject the packet.
 </p>
 </dd></dl>
 
-<a name="divert_helper_compile_filter"><h3>6.12 WinDivertHelperCompileFilter</h3></a>
+<a name="divert_helper_compile_filter"><h3>6.14 WinDivertHelperCompileFilter</h3></a>
 <table border="1" cellpadding="5"><tr><td>
 <pre>
 BOOL <b>WinDivertHelperCompileFilter</b>(
@@ -1847,7 +2030,7 @@ objects, and therefore do not need to be deallocated.
 <p>
 </dd></dl>
 
-<a name="divert_helper_eval_filter"><h3>6.13 WinDivertHelperEvalFilter</h3></a>
+<a name="divert_helper_eval_filter"><h3>6.15 WinDivertHelperEvalFilter</h3></a>
 <table border="1" cellpadding="5"><tr><td>
 <pre>
 BOOL <b>WinDivertHelperEvalFilter</b>(
@@ -1886,13 +2069,48 @@ Otherwise, if no error occurred, <tt>GetLastError()</tt> will return
 Note that this function is relatively slow since the packet filter string
 will be (re)compiled for each call.
 This overhead can be minimized by pre-compiling the filter string into the
-object representation using the <a
-href="#divert_helper_compile_filter">WinDivertHelperCompileFilter()</a>
+object representation using the
+<a href="#divert_helper_compile_filter"><tt>WinDivertHelperCompileFilter()</tt></a>
 function.
 <p>
 </dd></dl>
 
-<a name="divert_helper_eval_ntoh"><h3>6.14 WinDivertHelperNtoh*</h3></a>
+<a name="divert_helper_format_filter"><h3>6.16 WinDivertHelperFormatFilter</h3></a>
+<table border="1" cellpadding="5"><tr><td>
+<pre>
+BOOL <b>WinDivertHelperEvalFilter</b>(
+    __in const char *filter,
+    __in WINDIVERT_LAYER layer,
+    __out char *buffer,
+    __in UINT bufLen
+);
+</pre>
+</td></tr></table>
+<dl><dd>
+<p>
+<b>Parameters</b><br>
+<ul>
+<li> <tt>filter</tt>: The packet filter string to be evaluated.</li>
+<li> <tt>layer</tt>: The layer.</li>
+<li> <tt>buffer</tt>: A buffer for the formatted filter.</li>
+<li> <tt>bufLen</tt>: The length of <tt>buffer</tt>.</li>
+</ul>
+</p><p>
+<b>Return Value</b><br>
+<tt>TRUE</tt> if successful, <tt>FALSE</tt> if an error occurred.
+Use <tt>GetLastError()</tt> to get the reason for the error.
+</p><p>
+<b>Remarks</b><br>
+Formats the given filter string or object.
+This function is mainly useful for <q>decompiling</q> the filter object
+representation back into a human-readable filter string representation.
+One application is the <tt>WINDIVERT_LAYER_REFLECT</tt> layer,
+where a pseudo packet containing a filter object is returned by
+<a href="#divert_recv"><tt>WinDivertRecv()</tt></a>.
+</p>
+</dd></dl>
+
+<a name="divert_helper_ntoh"><h3>6.17 WinDivertHelperNtoh*</h3></a>
 <table border="1" cellpadding="5"><tr><td>
 <pre>
 UINT16 <b>WinDivertHelperNtohs</b>(
@@ -1927,7 +2145,7 @@ Converts a value/IPv6-address from network to host byte-order.
 </p>
 </dd></dl>
 
-<a name="divert_helper_eval_hton"><h3>6.15 WinDivertHelperHton*</h3></a>
+<a name="divert_helper_hton"><h3>6.18 WinDivertHelperHton*</h3></a>
 <table border="1" cellpadding="5"><tr><td>
 <pre>
 UINT16 <b>WinDivertHelperHtons</b>(