api: separate read-wait handle into other function

Makes the API a bit more clear.

Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>

api/exports.def

@@ -11,6 +11,7 @@ EXPORTS
 	WintunGetAdapterGUID
 	WintunGetAdapterLUID
 	WintunGetAdapterName
+	WintunGetReadWaitEvent
 	WintunGetVersion
 	WintunReceivePacket
 	WintunReceiveRelease

api/rundll32.c

@@ -163,8 +163,7 @@ VOID __stdcall DoThingsForDebugging(HWND hwnd, HINSTANCE hinst, LPSTR lpszCmdLin
     assert(WintunCreateAdapter(L"Wintun", L"Test", &TestGuid, &Adapter, &RebootRequired) == ERROR_SUCCESS);
     assert(!RebootRequired);
     TUN_SESSION *Session;
-    HANDLE ReadWait;
+    assert(WintunStartSession(Adapter, WINTUN_MIN_RING_CAPACITY, &Session) == ERROR_SUCCESS);
-    assert(WintunStartSession(Adapter, WINTUN_MIN_RING_CAPACITY, &Session, &ReadWait) == ERROR_SUCCESS);
     WintunEndSession(Session);
     assert(WintunDeleteAdapter(Adapter, TRUE, &RebootRequired) == ERROR_SUCCESS);
     assert(!RebootRequired);

api/session.c

@@ -74,8 +74,7 @@ WINTUN_STATUS WINAPI
 WintunStartSession(
     _In_ const WINTUN_ADAPTER *Adapter,
     _In_ DWORD Capacity,
-    _Out_ TUN_SESSION **Session,
+    _Out_ TUN_SESSION **Session)
-    _Out_ HANDLE *ReadWait)
 {
     TUN_SESSION *s = HeapAlloc(ModuleHeap, HEAP_ZERO_MEMORY, sizeof(TUN_SESSION));
     if (!s)
@@ -137,7 +136,6 @@ WintunStartSession(
     (void)InitializeCriticalSectionAndSpinCount(&s->Receive.Lock, LOCK_SPIN_COUNT);
     (void)InitializeCriticalSectionAndSpinCount(&s->Send.Lock, LOCK_SPIN_COUNT);
     *Session = s;
-    *ReadWait = s->Descriptor.Send.TailMoved;
     return ERROR_SUCCESS;
 cleanupHandle:
     CloseHandle(s->Handle);
@@ -167,6 +165,12 @@ WintunEndSession(_In_ TUN_SESSION *Session)
     HeapFree(ModuleHeap, 0, Session);
 }
 
+HANDLE WINAPI
+WintunGetReadWaitEvent(_In_ TUN_SESSION *Session)
+{
+    return Session->Descriptor.Send.TailMoved;
+}
+
 WINTUN_STATUS WINAPI
 WintunReceivePacket(_In_ TUN_SESSION *Session, _Out_bytecapcount_(*PacketSize) BYTE **Packet, _Out_ DWORD *PacketSize)
 {

api/session.h

@@ -17,8 +17,7 @@ WINTUN_STATUS WINAPI
 WintunStartSession(
     _In_ const WINTUN_ADAPTER *Adapter,
     _In_ DWORD Capacity,
-    _Out_ TUN_SESSION **Session,
+    _Out_ TUN_SESSION **Session);
-    _Out_ HANDLE *ReadWait);
 
 /**
  * @copydoc WINTUN_END_SESSION_FUNC
@@ -26,6 +25,12 @@ WintunStartSession(
 void WINAPI
 WintunEndSession(_In_ TUN_SESSION *Session);
 
+/**
+ * @copydoc WINTUN_GET_READ_WAIT_EVENT_FUNC
+ */
+HANDLE WINAPI
+WintunGetReadWaitEvent(_In_ TUN_SESSION *Session);
+
 /**
  * @copydoc WINTUN_RECEIVE_PACKET_FUNC
  */

api/wintun.h

@@ -234,18 +234,12 @@ typedef void *WINTUN_SESSION_HANDLE;
  *
  * @param Session       Pointer to a variable to receive Wintun session handle
  *
- * @param ReadWait      Pointer to receive event handle to wait for available data when reading. Should
- *                      WintunReceivePackets return ERROR_NO_MORE_ITEMS (after spinning on it for a while under heavy
- *                      load), wait for this event to become signaled before retrying WintunReceivePackets. Do not call
- *                      CloseHandle on this event - it is managed by the session.
- *
  * @return ERROR_SUCCESS on success; Win32 error code otherwise.
  */
 typedef WINTUN_STATUS(WINAPI *WINTUN_START_SESSION_FUNC)(
     _In_ WINTUN_ADAPTER_HANDLE Adapter,
     _In_ DWORD Capacity,
-    _Out_ WINTUN_SESSION_HANDLE *Session,
+    _Out_ WINTUN_SESSION_HANDLE *Session);
-    _Out_ HANDLE *ReadWait);
 
 /**
  * Ends Wintun session.
@@ -254,6 +248,18 @@ typedef WINTUN_STATUS(WINAPI *WINTUN_START_SESSION_FUNC)(
  */
 typedef void(WINAPI *WINTUN_END_SESSION_FUNC)(_In_ WINTUN_SESSION_HANDLE Session);
 
+/**
+ * Gets Wintun session's read-wait event handle.
+ *
+ * @param Session       Wintun session handle obtained with WintunStartSession
+ *
+ * @return Pointer to receive event handle to wait for available data when reading. Should
+ *         WintunReceivePackets return ERROR_NO_MORE_ITEMS (after spinning on it for a while under heavy
+ *         load), wait for this event to become signaled before retrying WintunReceivePackets. Do not call
+ *         CloseHandle on this event - it is managed by the session.
+ */
+typedef HANDLE(WINAPI *WINTUN_GET_READ_WAIT_EVENT_FUNC)(_In_ WINTUN_SESSION_HANDLE *Session);
+
 /**
  * Maximum IP packet size
  */