api: rearrange wintun.h to have better grouping and improve docs

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

README.md

@@ -110,7 +110,7 @@ Called by WintunEnumAdapters for each adapter in the pool.
 
 **Parameters**
 
-- *Adapter*: Adapter handle.
+- *Adapter*: Adapter handle, which will be freed when this function returns.
 - *Param*: An application-defined value passed to the WintunEnumAdapters.
 
 **Returns**
@@ -158,7 +158,7 @@ Enumerator
 
 `WINTUN_ADAPTER_HANDLE WintunCreateAdapter (const WCHAR * Pool, const WCHAR * Name, const GUID * RequestedGUID, BOOL * RebootRequired)`
 
-Creates a Wintun adapter.
+Creates a new Wintun adapter.
 
 **Parameters**
 
@@ -171,6 +171,21 @@ Creates a Wintun adapter.
 
 If the function succeeds, the return value is the adapter handle. Must be released with WintunFreeAdapter. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
 
+#### WintunOpenAdapter()
+
+`WINTUN_ADAPTER_HANDLE WintunOpenAdapter (const WCHAR * Pool, const WCHAR * Name)`
+
+Opens an existing Wintun adapter.
+
+**Parameters**
+
+- *Pool*: Name of the adapter pool. Zero-terminated string of up to WINTUN\_MAX\_POOL-1 characters.
+- *Name*: Adapter name. Zero-terminated string of up to MAX\_ADAPTER\_NAME-1 characters.
+
+**Returns**
+
+If the function succeeds, the return value is adapter handle. Must be released with WintunFreeAdapter. If the function fails, the return value is NULL. To get extended error information, call GetLastError. Possible errors include the following: ERROR\_FILE\_NOT\_FOUND if adapter with given name is not found; ERROR\_ALREADY\_EXISTS if adapter is found but not a Wintun-class or not a member of the pool
+
 #### WintunDeleteAdapter()
 
 `BOOL WintunDeleteAdapter (WINTUN_ADAPTER_HANDLE Adapter, BOOL ForceCloseSessions, BOOL * RebootRequired)`
@@ -187,21 +202,6 @@ Deletes a Wintun adapter.
 
 If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
 
-#### WintunDeletePoolDriver()
-
-`BOOL WintunDeletePoolDriver (const WCHAR * Pool, BOOL * RebootRequired)`
-
-Deletes all Wintun adapters in a pool and if there are no more adapters in any other pools, also removes Wintun from the driver store, usually called by uninstallers.
-
-**Parameters**
-
-- *Pool*: Name of the adapter pool. Zero-terminated string of up to WINTUN\_MAX\_POOL-1 characters.
-- *RebootRequired*: Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
-
-**Returns**
-
-If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
-
 #### WintunEnumAdapters()
 
 `BOOL WintunEnumAdapters (const WCHAR * Pool, WINTUN_ENUM_CALLBACK Callback, LPARAM Param)`
@@ -228,20 +228,20 @@ Releases Wintun adapter resources.
 
 - *Adapter*: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
 
-#### WintunOpenAdapter()
+#### WintunDeletePoolDriver()
 
-`WINTUN_ADAPTER_HANDLE WintunOpenAdapter (const WCHAR * Pool, const WCHAR * Name)`
+`BOOL WintunDeletePoolDriver (const WCHAR * Pool, BOOL * RebootRequired)`
 
-Finds a Wintun adapter by its name.
+Deletes all Wintun adapters in a pool and if there are no more adapters in any other pools, also removes Wintun from the driver store, usually called by uninstallers.
 
 **Parameters**
 
 - *Pool*: Name of the adapter pool. Zero-terminated string of up to WINTUN\_MAX\_POOL-1 characters.
-- *Name*: Adapter name. Zero-terminated string of up to MAX\_ADAPTER\_NAME-1 characters.
+- *RebootRequired*: Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
 
 **Returns**
 
-If the function succeeds, the return value is adapter handle. Must be released with WintunFreeAdapter. If the function fails, the return value is NULL. To get extended error information, call GetLastError. Possible errors include the following: ERROR\_FILE\_NOT\_FOUND if adapter with given name is not found; ERROR\_ALREADY\_EXISTS if adapter is found but not a Wintun-class or not a member of the pool
+If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
 
 #### WintunOpenAdapterDeviceObject()
 

api/wintun.h

@@ -24,7 +24,7 @@ typedef void *WINTUN_ADAPTER_HANDLE;
 #define WINTUN_MAX_POOL 256
 
 /**
- * Creates a Wintun adapter.
+ * Creates a new Wintun adapter.
  *
  * @param Pool          Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
  *
@@ -47,6 +47,23 @@ typedef _Return_type_success_(return != NULL) WINTUN_ADAPTER_HANDLE(WINAPI *WINT
     _In_opt_ const GUID *RequestedGUID,
     _Out_opt_ BOOL *RebootRequired);
 
+/**
+ * Opens an existing Wintun adapter.
+ *
+ * @param Pool          Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
+ *
+ * @param Name          Adapter name. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
+ *
+ * @return If the function succeeds, the return value is adapter handle. Must be released with WintunFreeAdapter. If the
+ *         function fails, the return value is NULL. To get extended error information, call GetLastError. Possible
+ *         errors include the following:
+ *         ERROR_FILE_NOT_FOUND if adapter with given name is not found;
+ *         ERROR_ALREADY_EXISTS if adapter is found but not a Wintun-class or not a member of the pool
+ */
+typedef _Return_type_success_(return != NULL)
+    WINTUN_ADAPTER_HANDLE(WINAPI *WINTUN_OPEN_ADAPTER_FUNC)(_In_z_ const WCHAR *Pool, _In_z_ const WCHAR *Name);
+
+
 /**
  * Deletes a Wintun adapter.
  *
@@ -66,24 +83,10 @@ typedef _Return_type_success_(return != FALSE) BOOL(WINAPI *WINTUN_DELETE_ADAPTE
     _In_ BOOL ForceCloseSessions,
     _Out_opt_ BOOL *RebootRequired);
 
-/**
- * Deletes all Wintun adapters in a pool and if there are no more adapters in any other pools, also removes Wintun
- * from the driver store, usually called by uninstallers.
- *
- * @param Pool             Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- *
- * @param RebootRequired   Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
- *
- * @return If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To
- *         get extended error information, call GetLastError.
- */
-typedef _Return_type_success_(return != FALSE)
-    BOOL(WINAPI *WINTUN_DELETE_POOL_DRIVER_FUNC)(_In_z_ const WCHAR *Pool, _Out_opt_ BOOL *RebootRequired);
-
 /**
  * Called by WintunEnumAdapters for each adapter in the pool.
  *
- * @param Adapter       Adapter handle.
+ * @param Adapter       Adapter handle, which will be freed when this function returns.
  *
  * @param Param         An application-defined value passed to the WintunEnumAdapters.
  *
@@ -115,20 +118,18 @@ typedef _Return_type_success_(return != FALSE) BOOL(
 typedef void(WINAPI *WINTUN_FREE_ADAPTER_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter);
 
 /**
- * Finds a Wintun adapter by its name.
+ * Deletes all Wintun adapters in a pool and if there are no more adapters in any other pools, also removes Wintun
+ * from the driver store, usually called by uninstallers.
  *
- * @param Pool          Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
+ * @param Pool             Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
  *
- * @param Name          Adapter name. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
+ * @param RebootRequired   Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
  *
- * @return If the function succeeds, the return value is adapter handle. Must be released with WintunFreeAdapter. If the
+ * @return If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To
- *         function fails, the return value is NULL. To get extended error information, call GetLastError. Possible
+ *         get extended error information, call GetLastError.
- *         errors include the following:
- *         ERROR_FILE_NOT_FOUND if adapter with given name is not found;
- *         ERROR_ALREADY_EXISTS if adapter is found but not a Wintun-class or not a member of the pool
  */
-typedef _Return_type_success_(return != NULL)
+typedef _Return_type_success_(return != FALSE)
-    WINTUN_ADAPTER_HANDLE(WINAPI *WINTUN_OPEN_ADAPTER_FUNC)(_In_z_ const WCHAR *Pool, _In_z_ const WCHAR *Name);
+    BOOL(WINAPI *WINTUN_DELETE_POOL_DRIVER_FUNC)(_In_z_ const WCHAR *Pool, _Out_opt_ BOOL *RebootRequired);
 
 /**
  * Returns a handle to the adapter device object.