From e11897e34329c59d993b471ceddfbd146ccbef1b Mon Sep 17 00:00:00 2001
From: Simon Rozman <simon@rozman.si>
Date: Thu, 29 Oct 2020 06:21:32 +0100
Subject: api: depretiate WintunIsPacketAvailable()

Spinning on the WintunReceivePacket() while it returns
ERROR_NO_MORE_ITEMS achieves the same.

Signed-off-by: Simon Rozman <simon@rozman.si>
---
 README.md       | 22 +++++++++++-----------
 api/exports.def |  1 -
 api/session.c   |  6 ------
 api/wintun.h    |  9 ---------
 4 files changed, 11 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index eabaf95..8afe261 100644
--- a/README.md
+++ b/README.md
@@ -58,7 +58,6 @@ Once adapter is created, use the following functions to start a session and tran
 - `WintunStartSession()` starts a session. One adapter may have only one session.
 - `WintunEndSession()` ends and frees the session.
 - `WintunIsPacketAvailable()` checks if there is a receive packet available.
-- `WintunWaitForPacket()` waits for a receive packet to become available.
 - `WintunReceivePacket()` receives one packet.
 - `WintunReceiveRelease()` releases internal buffer after client processed the receive packet.
 - `WintunAllocateSendPacket()` allocates memory for send packet.
@@ -69,23 +68,24 @@ Once adapter is created, use the following functions to start a session and tran
 Reading packets from the adapter may be done as:
 
 ```C
-// TODO: Preallocate WINTUN_PACKET *Queue linked list with WINTUN_MAX_IP_PACKET_SIZE packets.
 for (;;) {
-    if (!WintunIsPacketAvailable(Session))
-        WintunWaitForPacket(Session, INFINITE);
-    for (WINTUN_PACKET *p = Queue; p && p->Size <= WINTUN_MAX_IP_PACKET_SIZE; p = p->Next)
-        p->Size = DWORD_MAX;
     BYTE *Packet;
     DWORD PacketSize;
     DWORD Result = WintunReceivePacket(Session, &Packet, &PacketSize);
-    if (Result != ERROR_SUCCESS)
-        return Result;
-    // TODO: Process packet.
-    WintunReceiveRelease(Session, Packet);
+    switch (Result) {
+    case ERROR_SUCCESS:
+        // TODO: Process packet.
+        WintunReceiveRelease(Session, Packet);
+        break;
+    case ERROR_NO_MORE_ITEMS:
+        WintunWaitForPacket(Session, INFINITE);
+        continue;
+    }
+    return Result;
 }
 ```
 
-It may be desirable to spin on `WintunIsPacketAvailable()` for some time under heavy use before waiting with `WintunWaitForPacket()`, in order to reduce latency.
+It may be desirable to spin on `WintunReceivePacket()` while it returns `ERROR_NO_MORE_ITEMS` for some time under heavy use before waiting with `WintunWaitForPacket()`, in order to reduce latency.
 
 Writing packets to the adapter may be done as:
 
diff --git a/api/exports.def b/api/exports.def
index 6dbd89a..2c9e78b 100644
--- a/api/exports.def
+++ b/api/exports.def
@@ -11,7 +11,6 @@ EXPORTS
 	WintunGetAdapterLUID
 	WintunGetAdapterName
 	WintunGetVersion
-	WintunIsPacketAvailable
 	WintunReceivePacket
 	WintunReceiveRelease
 	WintunSendPacket
diff --git a/api/session.c b/api/session.c
index 02aa5be..259b1f5 100644
--- a/api/session.c
+++ b/api/session.c
@@ -147,12 +147,6 @@ WintunEndSession(_In_ TUN_SESSION *Session)
     HeapFree(ModuleHeap, 0, Session);
 }
 
-BOOL WINAPI
-WintunIsPacketAvailable(_In_ TUN_SESSION *Session)
-{
-    return Session->Send.Head != InterlockedGetU(&Session->Descriptor.Send.Ring->Tail);
-}
-
 WINTUN_STATUS WINAPI
 WintunWaitForPacket(_In_ TUN_SESSION *Session, _In_ DWORD Milliseconds)
 {
diff --git a/api/wintun.h b/api/wintun.h
index 2fe5c2e..ff79d8a 100644
--- a/api/wintun.h
+++ b/api/wintun.h
@@ -260,15 +260,6 @@ typedef void(WINAPI *WINTUN_END_SESSION_FUNC)(_In_ WINTUN_SESSION_HANDLE Session
  */
 #define WINTUN_MAX_IP_PACKET_SIZE 0xFFFF
 
-/**
- * Peeks if there is a packet available for reading.
- *
- * @param Session       Wintun session handle obtained with WintunStartSession
- *
- * @return Non-zero if there is a packet available; zero otherwise.
- */
-BOOL(WINAPI *WINTUN_IS_PACKET_AVAILABLE_FUNC)(_In_ WINTUN_SESSION_HANDLE Session);
-
 /**
  * Waits for a packet to become available for reading.
  *
-- 
cgit v1.2.3-59-g8ed1b