From fa9229820cc87b241f86eaec0959592ddb85813b Mon Sep 17 00:00:00 2001 From: basil00 Date: Sun, 27 Jan 2019 08:50:41 +0800 Subject: [PATCH] Document WinDivertHelperCompileFilter(). --- doc/windivert.html | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/doc/windivert.html b/doc/windivert.html index 399d3cc..08a6981 100644 --- a/doc/windivert.html +++ b/doc/windivert.html @@ -39,7 +39,7 @@
  • 6.8 WinDivertHelperParseIPv4Address
  • 6.9 WinDivertHelperParseIPv6Address
  • 6.10 WinDivertHelperCalcChecksums
    • -
  • 6.11 WinDivertHelperCheckFilter
    • +
  • 6.11 WinDivertHelperCompileFilter
  • 6.12 WinDivertHelperEvalFilter
  • 7. Filter Language
    • @@ -1445,12 +1445,14 @@ order to (re)inject the packet.

    -

    6.11 WinDivertHelperCheckFilter

     +

    6.11 WinDivertHelperCompileFilter

     
    -BOOL WinDivertHelperCheckFilter(
+BOOL WinDivertHelperCompileFilter(
     __in const char *filter,
     __in WINDIVERT_LAYER layer,
+    __out_opt char *object,
+    __in UINT objLen,
     __out_opt const char **errorStr,
     __out_opt UINT *errorPos
 );
@@ -1461,18 +1463,32 @@ BOOL WinDivertHelperCheckFilter(
 Parameters
    
 
      
 
    •  filter: The packet filter string to be checked.
      • 
-
    •  layer: The layer.
+
    •  layer: The layer.
      • 
+
    •  object: The compiled filter object.
      • 
+
    •  objLen: The length of the object buffer.
      • 
 
    •  errorStr: The error description.
      • 
 
    •  errorPos: The error position.
      • 
 
    
 
    
 Return Value
    
-TRUE if the packet filter string is valid, FALSE otherwise.
+TRUE if the packet filter compilation is successful, FALSE
+otherwise.
 
    
 Remarks
    
-Checks if the given packet filter string is valid with respect to the
+Compiles the given packet filter string into a compact object
+representation that is optionally stored in object if non-NULL.
+The object representation is a valid null terminated C string, but is
+otherwise opaque and not meant to be human readable.
+The object representation can be passed to all WinDivert functions,
+such as WinDivertOpen(), in place of the
+human-readable filter string equivalent.
+
    
+
    
+The compilation operation will succeed if the given filter string is
+valid with respect to the
 filter language.
-If the filter is invalid, then a human readable description of the error is
+Otherwise, if the filter is invalid, then a human readable description of
+the error is
 returned by errorStr (if non-NULL), and the error's
 position is returned by errorPos (if non-NULL).
 
    
@@ -1486,7 +1502,6 @@ objects, and therefore do not need to be deallocated.
 
     BOOL WinDivertHelperEvalFilter(
     __in const char *filter,
-    __in WINDIVERT_LAYER layer,
     __in PVOID pPacket,
     __in UINT packetLen,
     __in PWINDIVERT_ADDRESS pAddr
@@ -1498,7 +1513,6 @@ BOOL WinDivertHelperEvalFilter(
 Parameters
    
 
      
 
    •  filter: The packet filter string to be evaluated.
      • 
-
    •  layer: The layer.
 
    •  pPacket: The packet.
      • 
 
    •  packetLen: The total length of the packet pPacket.
      • 
 
    •  pAddr: The WINDIVERT_ADDRESS of the packet
@@ -1521,7 +1535,10 @@ Otherwise, if no error occurred, GetLastError() will return
 
      
 Note that this function is relatively slow since the packet filter string
 will be (re)compiled for each call.
-This function is mainly intended for debugging or testing purposes.
+This overhead can be minimized by pre-compiling the filter string into the
+object representation using the WinDivertHelperCompileFilter()
+function.