diff options
author | Simon Rozman <simon@rozman.si> | 2020-10-17 15:11:34 +0200 |
---|---|---|
committer | Jason A. Donenfeld <Jason@zx2c4.com> | 2020-10-30 16:51:01 +0100 |
commit | 449876fdfd0c70e2d822e0576cec650a22704d91 (patch) | |
tree | 8a033361260e3524a44c3cbeb9674eee7d8807db /api/wintun.h | |
parent | api: fix grammar (diff) | |
download | wintun-449876fdfd0c70e2d822e0576cec650a22704d91.tar.xz wintun-449876fdfd0c70e2d822e0576cec650a22704d91.zip |
api: introduce wintun.h
The SDK header for deployment containing datatype and function
declarations for use by C/C++ clients.
As we shall not distribute MSVC wintun.lib files, making clients need to
use GetProcAddress(), this file contains function type declarations
rather then __declspec(dllimport) function declarations.
Signed-off-by: Simon Rozman <simon@rozman.si>
Diffstat (limited to 'api/wintun.h')
-rw-r--r-- | api/wintun.h | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/api/wintun.h b/api/wintun.h new file mode 100644 index 0000000..0917a6c --- /dev/null +++ b/api/wintun.h @@ -0,0 +1,211 @@ +/* SPDX-License-Identifier: GPL-2.0 + * + * Copyright (C) 2018-2020 WireGuard LLC. All Rights Reserved. + */ + +#pragma once + +#include <Windows.h> +#include <IPExport.h> + +typedef _Return_type_success_(return == ERROR_SUCCESS) DWORD WINTUN_STATUS; + +/** + * A handle representing Wintun adapter + */ +typedef void *WINTUN_ADAPTER_HANDLE; + +#define MAX_POOL 256 + +/** + * Creates a Wintun adapter. + * + * @param Pool Name of the adapter pool. + * + * @param Name The requested name of the adapter. + * + * @param RequestedGUID The GUID of the created network adapter, which then influences NLA generation + * deterministically. If it is set to NULL, the GUID is chosen by the system at random, and hence + * a new NLA entry is created for each new adapter. It is called "requested" GUID because the API + * it uses is completely undocumented, and so there could be minor interesting complications with + * its usage. + * + * @param Adapter Pointer to a handle to receive the adapter handle. Must be released with + * WintunFreeAdapter. + * + * @param RebootRequired Pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot. Must be + * initialised to FALSE manually before this function is called. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ +typedef WINTUN_STATUS(WINAPI *WINTUN_CREATE_ADAPTER_FUNC)( + _In_z_count_c_(MAX_POOL) const WCHAR *Pool, + _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name, + _In_opt_ const GUID *RequestedGUID, + _Out_ WINTUN_ADAPTER_HANDLE *Adapter, + _Inout_ BOOL *RebootRequired); + +/** + * Deletes a Wintun adapter. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter. + * + * @param RebootRequired Pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot. Must be + * initialised to FALSE manually before this function is called. + * + * @return ERROR_SUCCESS on success or the adapter was not found; Win32 error code otherwise. + */ +typedef WINTUN_STATUS( + WINAPI *WINTUN_DELETE_ADAPTER_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Inout_ BOOL *RebootRequired); + +/** + * Called by WintunEnumAdapters for each adapter in the pool. + * + * @param Adapter Adapter handle. + * + * @param Param An application-defined value passed to the WintunEnumAdapters. + * + * @return Non-zero to continue iterating adapters; zero to stop. + */ +typedef BOOL(CALLBACK *WINTUN_ENUM_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _In_ LPARAM Param); + +/** + * Enumerates all Wintun adapters. + * + * @param Pool Name of the adapter pool. + * + * @param Func Callback function. To continue enumeration, the callback function must return TRUE; to stop + * enumeration, it must return FALSE. + * + * @param Param An application-defined value to be passed to the callback function. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ +typedef WINTUN_STATUS(WINAPI *WINTUN_ENUM_ADAPTERS_FUNC)( + _In_z_count_c_(MAX_POOL) const WCHAR *Pool, + _In_ WINTUN_ENUM_FUNC Func, + _In_ LPARAM Param); + +/** + * Releases Wintun adapter resources. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter. + */ +typedef void(WINAPI *WINTUN_FREE_ADAPTER_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter); + +/** + * Finds a Wintun adapter by its name. + * + * @param Pool Name of the adapter pool. + * + * @param Name Adapter name. + * + * @param Adapter Pointer to a handle to receive the adapter handle. Must be released with WintunFreeAdapter. + * + * @return ERROR_SUCCESS on success; 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; Win32 error code otherwise + */ +typedef WINTUN_STATUS(WINAPI *WINTUN_GET_ADAPTER_FUNC)( + _In_z_count_c_(MAX_POOL) const WCHAR *Pool, + _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name, + _Out_ WINTUN_ADAPTER_HANDLE *Adapter); + +/** + * Returns a handle to the adapter device object. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter. + * + * @param Handle Pointer to receive the adapter device object handle. Must be released with CloseHandle. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ +typedef WINTUN_STATUS( + WINAPI *WINTUN_GET_ADAPTER_DEVICE_OBJECT_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ HANDLE *Handle); + +/** + * Returns the GUID of the adapter. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter + * + * @param Guid Pointer to GUID to receive adapter ID. + */ +typedef void(WINAPI *WINTUN_GET_ADAPTER_GUID_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ GUID *Guid); + +/** + * Returns the LUID of the adapter. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter + * + * @param Luid Pointer to LUID to receive adapter LUID. + */ +typedef void(WINAPI *WINTUN_GET_ADAPTER_LUID_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ LUID *Luid); + +/** + * Returns the name of the Wintun adapter. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter + * + * @param Name Pointer to a string to receive adapter name + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ +typedef WINTUN_STATUS(WINAPI *WINTUN_GET_ADAPTER_NAME_FUNC)( + _In_ WINTUN_ADAPTER_HANDLE Adapter, + _Out_cap_c_(MAX_ADAPTER_NAME) WCHAR *Name); + +/** + * Returns the version of the Wintun driver and NDIS system currently loaded. + * + * @param DriverVersionMaj Pointer to a DWORD to receive the Wintun driver major version number. + * + * @param DriverVersionMin Pointer to a DWORD to receive the Wintun driver minor version number. + * + * @param NdisVersionMaj Pointer to a DWORD to receive the NDIS major version number. + * + * @param NdisVersionMin Pointer to a DWORD to receive the NDIS minor version number. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ +typedef WINTUN_STATUS(WINAPI *WINTUN_GET_VERSION_FUNC)( + _Out_ DWORD *DriverVersionMaj, + _Out_ DWORD *DriverVersionMin, + _Out_ DWORD *NdisVersionMaj, + _Out_ DWORD *NdisVersionMin); + +/** + * Sets name of the Wintun adapter. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter + * + * @param Name Adapter name + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ +typedef WINTUN_STATUS(WINAPI *WINTUN_SET_ADAPTER_NAME_FUNC)( + _In_ WINTUN_ADAPTER_HANDLE Adapter, + _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name); + +typedef enum _WINTUN_LOGGER_LEVEL +{ + WINTUN_LOG_INFO = 0, + WINTUN_LOG_WARN, + WINTUN_LOG_ERR +} WINTUN_LOGGER_LEVEL; + +/** + * Called by internal logger to report diagnostic messages + * + * @param Level Message level. + * + * @param Message Message text. + * + * @return Anything - return value is ignored. + */ +typedef BOOL(CALLBACK *WINTUN_LOGGER_FUNC)(_In_ WINTUN_LOGGER_LEVEL Level, _In_z_ const WCHAR *Message); + +/** + * Sets logger callback function. + * + * @param NewLogger Pointer to callback function to use as a new global logger. + */ +typedef void(WINAPI *WINTUN_SET_LOGGER_FUNC)(_In_ WINTUN_LOGGER_FUNC NewLogger); |