diff options
author | Jason A. Donenfeld <Jason@zx2c4.com> | 2020-11-05 13:47:18 +0100 |
---|---|---|
committer | Jason A. Donenfeld <Jason@zx2c4.com> | 2020-11-05 16:58:43 +0100 |
commit | 82c41bdb4bbfb38cb1183ecfe56384db894c705e (patch) | |
tree | 5e3caf7ba831880db970f48c88bcb45036bade4b /api | |
parent | api: rename WintunGetAdapter to WintunOpenAdapter (diff) | |
download | wintun-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>
Diffstat (limited to 'api')
-rw-r--r-- | api/wintun.h | 53 |
1 files changed, 27 insertions, 26 deletions
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. |