aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJason A. Donenfeld <Jason@zx2c4.com>2020-11-05 13:47:18 +0100
committerJason A. Donenfeld <Jason@zx2c4.com>2020-11-05 16:58:43 +0100
commit82c41bdb4bbfb38cb1183ecfe56384db894c705e (patch)
tree5e3caf7ba831880db970f48c88bcb45036bade4b
parentapi: rename WintunGetAdapter to WintunOpenAdapter (diff)
downloadwintun-82c41bdb4bbfb38cb1183ecfe56384db894c705e.tar.xz
wintun-82c41bdb4bbfb38cb1183ecfe56384db894c705e.zip
api: rearrange wintun.h to have better grouping and improve docs
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
-rw-r--r--README.md36
-rw-r--r--api/wintun.h53
2 files changed, 45 insertions, 44 deletions
diff --git a/README.md b/README.md
index 34ff255..6993d01 100644
--- a/README.md
+++ b/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,31 +171,31 @@ 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.
-#### WintunDeleteAdapter()
+#### WintunOpenAdapter()
-`BOOL WintunDeleteAdapter (WINTUN_ADAPTER_HANDLE Adapter, BOOL ForceCloseSessions, BOOL * RebootRequired)`
+`WINTUN_ADAPTER_HANDLE WintunOpenAdapter (const WCHAR * Pool, const WCHAR * Name)`
-Deletes a Wintun adapter.
+Opens an existing Wintun adapter.
**Parameters**
-- *Adapter*: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
-- *ForceCloseSessions*: Force close adapter handles that may be in use by other processes. Only set this to TRUE with extreme care, as this is resource intensive and may put processes into an undefined or unpredictable state. Most users should set this to FALSE.
-- *RebootRequired*: Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
+- *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 nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
+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
-#### WintunDeletePoolDriver()
+#### WintunDeleteAdapter()
-`BOOL WintunDeletePoolDriver (const WCHAR * Pool, BOOL * RebootRequired)`
+`BOOL WintunDeleteAdapter (WINTUN_ADAPTER_HANDLE Adapter, BOOL ForceCloseSessions, 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.
+Deletes a Wintun adapter.
**Parameters**
-- *Pool*: Name of the adapter pool. Zero-terminated string of up to WINTUN\_MAX\_POOL-1 characters.
+- *Adapter*: Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
+- *ForceCloseSessions*: Force close adapter handles that may be in use by other processes. Only set this to TRUE with extreme care, as this is resource intensive and may put processes into an undefined or unpredictable state. Most users should set this to FALSE.
- *RebootRequired*: Optional pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot.
**Returns**
@@ -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()
diff --git a/api/wintun.h b/api/wintun.h
index 96effda..79742d8 100644
--- a/api/wintun.h
+++ b/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.
*
@@ -48,6 +48,23 @@ typedef _Return_type_success_(return != NULL) WINTUN_ADAPTER_HANDLE(WINAPI *WINT
_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.
*
* @param Adapter Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
@@ -67,23 +84,9 @@ typedef _Return_type_success_(return != FALSE) BOOL(WINAPI *WINTUN_DELETE_ADAPTE
_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
- * 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
+ * @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 != NULL)
- WINTUN_ADAPTER_HANDLE(WINAPI *WINTUN_OPEN_ADAPTER_FUNC)(_In_z_ const WCHAR *Pool, _In_z_ const WCHAR *Name);
+typedef _Return_type_success_(return != FALSE)
+ BOOL(WINAPI *WINTUN_DELETE_POOL_DRIVER_FUNC)(_In_z_ const WCHAR *Pool, _Out_opt_ BOOL *RebootRequired);
/**
* Returns a handle to the adapter device object.