From 60c3a26e1c7cbc5c6c70c7fe964519e6da8b1b05 Mon Sep 17 00:00:00 2001 From: basil00 Date: Wed, 1 Nov 2017 20:56:51 +0800 Subject: [PATCH] Documentation improvements. --- CHANGELOG | 2 ++ doc/windivert.html | 54 ++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 54 insertions(+), 2 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 375aa37..cfc0a92 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -91,3 +91,5 @@ WinDivert 1.4.0-rc block until the packet exits the Windows TCP/IP stack. This is slower but provides better error messages, so is useful for debugging. - Internally queued packets are now reinjected on WinDivertClose(). + - WinDivertRecv() will eventually fail with ERROR_HOST_UNREACHABLE + if a packet loops indefinitely between WinDivert and another driver. diff --git a/doc/windivert.html b/doc/windivert.html index e1d7110..2eb2bee 100644 --- a/doc/windivert.html +++ b/doc/windivert.html @@ -598,7 +598,45 @@ BOOL WinDivertRecv( TRUE if a packet was successfully received, or FALSE if an error occurred. Use GetLastError() to get the reason for the error. +

+Common errors include: +

+ + + + + + + + + + +
+Name + +Code + +Description +
+ERROR_HOST_UNREACHABLE + +1232 + +This error occurs when a packet enters into a mutual infinite loop +between WinDivert and another network packet capture driver, possibly +an alternative version of WinDivert. +Infinite loops can occur when another driver copies and reinjects a packet +sent by WinDivertSend(). +The copied packet will be considered new again, and will be diverted +back to WinDivertRecv(), completing the +loop. +To stop packets looping indefinitely, WinDivert automatically decrements the +ip.TTL or ipv6.HopLimit fields of potentially affected +packets, eventually returning ERROR_HOST_UNREACHABLE when the value +reaches zero. +
+

Remarks
Receives a diverted packet that matched the filter passed to @@ -1669,11 +1707,23 @@ They are If two or more Windows Filtering Platform (WFP) callout drivers (including WinDivert applications) block and inject unmodified copies of packets then this can lead to an infinite loop. - This appears to be caused by a design flaw of WFP. + If such a loop occurs, + WinDivertRecv() will eventually fail + with error ERROR_HOST_UNREACHABLE. + Unfortunately, such errors are not easy to fix. + Some crude solutions include: (1) removing the incompatible driver, or + (2) ignoring all packets with ip.TTL or + ipv6.HopLimit less than the Windows DefaultTTL + registry value. See GitHub issue #41 for more information. -

  • WinDivert can cause the MSVC x86_64 debugger to hang: +
  • WinDivert can cause the MSVC x86_64 debugger to deadlock: + The deadlock occurs because the debugger uses local sockets. + Thus: the debugger pauses the WinDivert + application, which stops packets from being processed, which + causes the debugger wait forever on input from a socket. + The deadlock can be avoided by ignoring loopback traffic. See GitHub issue #26 for more information.