diff options
author | Simon Rozman <simon@rozman.si> | 2021-07-28 20:20:09 +0200 |
---|---|---|
committer | Simon Rozman <simon@rozman.si> | 2021-07-28 20:25:27 +0200 |
commit | d675646ab8df227ba39c9d0160d0ba77e8f85479 (patch) | |
tree | d6138df6a8b10083de89c644261116abd64b46d8 /api/wintun.h | |
parent | example: resolve signed/unsigned code analysis warning (diff) | |
download | wintun-d675646ab8df227ba39c9d0160d0ba77e8f85479.tar.xz wintun-d675646ab8df227ba39c9d0160d0ba77e8f85479.zip |
api: upgrade
Signed-off-by: Simon Rozman <simon@rozman.si>
Diffstat (limited to '')
-rw-r--r-- | api/wintun.h | 110 |
1 files changed, 69 insertions, 41 deletions
diff --git a/api/wintun.h b/api/wintun.h index 2b03d33..9464a96 100644 --- a/api/wintun.h +++ b/api/wintun.h @@ -16,7 +16,7 @@ extern "C" { /** * A handle representing Wintun adapter */ -typedef void *WINTUN_ADAPTER_HANDLE; +typedef struct _WINTUN_ADAPTER *WINTUN_ADAPTER_HANDLE; /** * Maximum pool name length including zero terminator @@ -39,13 +39,14 @@ typedef void *WINTUN_ADAPTER_HANDLE; * @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 the adapter handle. Must be released with WintunFreeAdapter. If - * the function fails, the return value is NULL. To get extended error information, call GetLastError. + * the function fails, the return value is NULL. To get extended error information, call GetLastError. */ -typedef _Return_type_success_(return != NULL) WINTUN_ADAPTER_HANDLE(WINAPI *WINTUN_CREATE_ADAPTER_FUNC)( - _In_z_ const WCHAR *Pool, - _In_z_ const WCHAR *Name, - _In_opt_ const GUID *RequestedGUID, - _Out_opt_ BOOL *RebootRequired); +typedef _Must_inspect_result_ +_Return_type_success_(return != NULL) +_Post_maybenull_ +WINTUN_ADAPTER_HANDLE(WINAPI WINTUN_CREATE_ADAPTER_FUNC_IMPL) +(_In_z_ LPCWSTR Pool, _In_z_ LPCWSTR Name, _In_opt_ const GUID *RequestedGUID, _Out_opt_ BOOL *RebootRequired); +typedef WINTUN_CREATE_ADAPTER_FUNC_IMPL *WINTUN_CREATE_ADAPTER_FUNC; /** * Opens an existing Wintun adapter. @@ -55,14 +56,15 @@ typedef _Return_type_success_(return != NULL) WINTUN_ADAPTER_HANDLE(WINAPI *WINT * @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 + * 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); - +typedef _Must_inspect_result_ +_Return_type_success_(return != NULL) +_Post_maybenull_ +WINTUN_ADAPTER_HANDLE(WINAPI WINTUN_OPEN_ADAPTER_FUNC_IMPL)(_In_z_ LPCWSTR Pool, _In_z_ LPCWSTR Name); +typedef WINTUN_OPEN_ADAPTER_FUNC_IMPL *WINTUN_OPEN_ADAPTER_FUNC; /** * Deletes a Wintun adapter. @@ -78,10 +80,10 @@ typedef _Return_type_success_(return != NULL) * @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_ADAPTER_FUNC)( - _In_ WINTUN_ADAPTER_HANDLE Adapter, - _In_ BOOL ForceCloseSessions, - _Out_opt_ BOOL *RebootRequired); +typedef _Return_type_success_(return != FALSE) +BOOL(WINAPI WINTUN_DELETE_ADAPTER_FUNC_IMPL) +(_In_ WINTUN_ADAPTER_HANDLE Adapter, _In_ BOOL ForceCloseSessions, _Out_opt_ BOOL *RebootRequired); +typedef WINTUN_DELETE_ADAPTER_FUNC_IMPL *WINTUN_DELETE_ADAPTER_FUNC; /** * Called by WintunEnumAdapters for each adapter in the pool. @@ -107,15 +109,17 @@ typedef BOOL(CALLBACK *WINTUN_ENUM_CALLBACK)(_In_ WINTUN_ADAPTER_HANDLE Adapter, * @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_ENUM_ADAPTERS_FUNC)(_In_z_ const WCHAR *Pool, _In_ WINTUN_ENUM_CALLBACK Callback, _In_ LPARAM Param); +typedef _Return_type_success_(return != FALSE) +BOOL(WINAPI WINTUN_ENUM_ADAPTERS_FUNC_IMPL)(_In_z_ LPCWSTR Pool, _In_ WINTUN_ENUM_CALLBACK Callback, _In_ LPARAM Param); +typedef WINTUN_ENUM_ADAPTERS_FUNC_IMPL *WINTUN_ENUM_ADAPTERS_FUNC; /** * Releases Wintun adapter resources. * * @param Adapter Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter. */ -typedef void(WINAPI *WINTUN_FREE_ADAPTER_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter); +typedef VOID(WINAPI WINTUN_FREE_ADAPTER_FUNC_IMPL)(_In_ WINTUN_ADAPTER_HANDLE Adapter); +typedef WINTUN_FREE_ADAPTER_FUNC_IMPL *WINTUN_FREE_ADAPTER_FUNC; /** * Deletes all Wintun adapters in a pool and if there are no more adapters in any other pools, also removes Wintun @@ -129,7 +133,8 @@ typedef void(WINAPI *WINTUN_FREE_ADAPTER_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapte * 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); +BOOL(WINAPI WINTUN_DELETE_POOL_DRIVER_FUNC_IMPL)(_In_z_ LPCWSTR Pool, _Out_opt_ BOOL *RebootRequired); +typedef WINTUN_DELETE_POOL_DRIVER_FUNC_IMPL *WINTUN_DELETE_POOL_DRIVER_FUNC; /** * Returns the LUID of the adapter. @@ -138,7 +143,8 @@ typedef _Return_type_success_(return != FALSE) * * @param Luid Pointer to LUID to receive adapter LUID. */ -typedef void(WINAPI *WINTUN_GET_ADAPTER_LUID_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ NET_LUID *Luid); +typedef VOID(WINAPI WINTUN_GET_ADAPTER_LUID_FUNC_IMPL)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ NET_LUID *Luid); +typedef WINTUN_GET_ADAPTER_LUID_FUNC_IMPL *WINTUN_GET_ADAPTER_LUID_FUNC; /** * Returns the name of the Wintun adapter. @@ -150,9 +156,11 @@ typedef void(WINAPI *WINTUN_GET_ADAPTER_LUID_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Ad * @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_GET_ADAPTER_NAME_FUNC)( - _In_ WINTUN_ADAPTER_HANDLE Adapter, - _Out_cap_c_(MAX_ADAPTER_NAME) WCHAR *Name); +typedef _Must_inspect_result_ +_Return_type_success_(return != FALSE) +BOOL(WINAPI WINTUN_GET_ADAPTER_NAME_FUNC_IMPL) +(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_writes_z_(MAX_ADAPTER_NAME) LPWSTR Name); +typedef WINTUN_GET_ADAPTER_NAME_FUNC_IMPL *WINTUN_GET_ADAPTER_NAME_FUNC; /** * Sets name of the Wintun adapter. @@ -165,7 +173,8 @@ typedef _Return_type_success_(return != FALSE) BOOL(WINAPI *WINTUN_GET_ADAPTER_N * get extended error information, call GetLastError. */ typedef _Return_type_success_(return != FALSE) - BOOL(WINAPI *WINTUN_SET_ADAPTER_NAME_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _In_z_ const WCHAR *Name); +BOOL(WINAPI WINTUN_SET_ADAPTER_NAME_FUNC_IMPL)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _In_z_ LPCWSTR Name); +typedef WINTUN_SET_ADAPTER_NAME_FUNC_IMPL *WINTUN_SET_ADAPTER_NAME_FUNC; /** * Determines the version of the Wintun driver currently loaded. @@ -174,7 +183,9 @@ typedef _Return_type_success_(return != FALSE) * zero. To get extended error information, call GetLastError. Possible errors include the following: * ERROR_FILE_NOT_FOUND Wintun not loaded */ -typedef DWORD(WINAPI *WINTUN_GET_RUNNING_DRIVER_VERSION_FUNC)(void); +typedef _Return_type_success_(return != 0) +DWORD(WINAPI WINTUN_GET_RUNNING_DRIVER_VERSION_FUNC_IMPL)(VOID); +typedef WINTUN_GET_RUNNING_DRIVER_VERSION_FUNC_IMPL *WINTUN_GET_RUNNING_DRIVER_VERSION_FUNC; /** * Determines the level of logging, passed to WINTUN_LOGGER_CALLBACK. @@ -193,7 +204,7 @@ typedef enum * * @param Message Message text. */ -typedef void(CALLBACK *WINTUN_LOGGER_CALLBACK)(_In_ WINTUN_LOGGER_LEVEL Level, _In_z_ const WCHAR *Message); +typedef VOID(CALLBACK *WINTUN_LOGGER_CALLBACK)(_In_ WINTUN_LOGGER_LEVEL Level, _In_z_ LPCWSTR Message); /** * Sets logger callback function. @@ -202,7 +213,8 @@ typedef void(CALLBACK *WINTUN_LOGGER_CALLBACK)(_In_ WINTUN_LOGGER_LEVEL Level, _ * threads concurrently. Should the logging require serialization, you must handle serialization in * NewLogger. Set to NULL to disable. */ -typedef void(WINAPI *WINTUN_SET_LOGGER_FUNC)(_In_ WINTUN_LOGGER_CALLBACK NewLogger); +typedef VOID(WINAPI WINTUN_SET_LOGGER_FUNC_IMPL)(_In_ WINTUN_LOGGER_CALLBACK NewLogger); +typedef WINTUN_SET_LOGGER_FUNC_IMPL *WINTUN_SET_LOGGER_FUNC; /** * Minimum ring capacity. @@ -217,7 +229,7 @@ typedef void(WINAPI *WINTUN_SET_LOGGER_FUNC)(_In_ WINTUN_LOGGER_CALLBACK NewLogg /** * A handle representing Wintun session */ -typedef void *WINTUN_SESSION_HANDLE; +typedef struct _TUN_SESSION *WINTUN_SESSION_HANDLE; /** * Starts Wintun session. @@ -230,15 +242,19 @@ typedef void *WINTUN_SESSION_HANDLE; * @return Wintun session handle. Must be released with WintunEndSession. If the function fails, the return value is * NULL. To get extended error information, call GetLastError. */ -typedef _Return_type_success_(return != NULL) - WINTUN_SESSION_HANDLE(WINAPI *WINTUN_START_SESSION_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _In_ DWORD Capacity); +typedef _Must_inspect_result_ +_Return_type_success_(return != NULL) +_Post_maybenull_ +WINTUN_SESSION_HANDLE(WINAPI WINTUN_START_SESSION_FUNC_IMPL)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _In_ DWORD Capacity); +typedef WINTUN_START_SESSION_FUNC_IMPL *WINTUN_START_SESSION_FUNC; /** * Ends Wintun session. * * @param Session Wintun session handle obtained with WintunStartSession */ -typedef void(WINAPI *WINTUN_END_SESSION_FUNC)(_In_ WINTUN_SESSION_HANDLE Session); +typedef VOID(WINAPI WINTUN_END_SESSION_FUNC_IMPL)(_In_ WINTUN_SESSION_HANDLE Session); +typedef WINTUN_END_SESSION_FUNC_IMPL *WINTUN_END_SESSION_FUNC; /** * Gets Wintun session's read-wait event handle. @@ -250,7 +266,8 @@ typedef void(WINAPI *WINTUN_END_SESSION_FUNC)(_In_ WINTUN_SESSION_HANDLE Session * 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); +typedef HANDLE(WINAPI WINTUN_GET_READ_WAIT_EVENT_FUNC_IMPL)(_In_ WINTUN_SESSION_HANDLE Session); +typedef WINTUN_GET_READ_WAIT_EVENT_FUNC_IMPL *WINTUN_GET_READ_WAIT_EVENT_FUNC; /** * Maximum IP packet size @@ -272,8 +289,12 @@ typedef HANDLE(WINAPI *WINTUN_GET_READ_WAIT_EVENT_FUNC)(_In_ WINTUN_SESSION_HAND * ERROR_NO_MORE_ITEMS Wintun buffer is exhausted; * ERROR_INVALID_DATA Wintun buffer is corrupt */ -typedef _Return_type_success_(return != NULL) _Ret_bytecount_(*PacketSize) BYTE *( - WINAPI *WINTUN_RECEIVE_PACKET_FUNC)(_In_ WINTUN_SESSION_HANDLE Session, _Out_ DWORD *PacketSize); +typedef _Must_inspect_result_ +_Return_type_success_(return != NULL) +_Post_maybenull_ +_Post_writable_byte_size_(*PacketSize) +BYTE *(WINAPI WINTUN_RECEIVE_PACKET_FUNC_IMPL)(_In_ WINTUN_SESSION_HANDLE Session, _Out_ DWORD *PacketSize); +typedef WINTUN_RECEIVE_PACKET_FUNC_IMPL *WINTUN_RECEIVE_PACKET_FUNC; /** * Releases internal buffer after the received packet has been processed by the client. This function is thread-safe. @@ -282,7 +303,9 @@ typedef _Return_type_success_(return != NULL) _Ret_bytecount_(*PacketSize) BYTE * * @param Packet Packet obtained with WintunReceivePacket */ -typedef void(WINAPI *WINTUN_RELEASE_RECEIVE_PACKET_FUNC)(_In_ WINTUN_SESSION_HANDLE Session, _In_ const BYTE *Packet); +typedef VOID( + WINAPI WINTUN_RELEASE_RECEIVE_PACKET_FUNC_IMPL)(_In_ WINTUN_SESSION_HANDLE Session, _In_ const BYTE *Packet); +typedef WINTUN_RELEASE_RECEIVE_PACKET_FUNC_IMPL *WINTUN_RELEASE_RECEIVE_PACKET_FUNC; /** * Allocates memory for a packet to send. After the memory is filled with packet data, call WintunSendPacket to send @@ -299,8 +322,12 @@ typedef void(WINAPI *WINTUN_RELEASE_RECEIVE_PACKET_FUNC)(_In_ WINTUN_SESSION_HAN * ERROR_HANDLE_EOF Wintun adapter is terminating; * ERROR_BUFFER_OVERFLOW Wintun buffer is full; */ -typedef _Return_type_success_(return != NULL) _Ret_bytecount_(PacketSize) BYTE *( - WINAPI *WINTUN_ALLOCATE_SEND_PACKET_FUNC)(_In_ WINTUN_SESSION_HANDLE Session, _In_ DWORD PacketSize); +typedef _Must_inspect_result_ +_Return_type_success_(return != NULL) +_Post_maybenull_ +_Post_writable_byte_size_(PacketSize) +BYTE *(WINAPI WINTUN_ALLOCATE_SEND_PACKET_FUNC_IMPL)(_In_ WINTUN_SESSION_HANDLE Session, _In_ DWORD PacketSize); +typedef WINTUN_ALLOCATE_SEND_PACKET_FUNC_IMPL *WINTUN_ALLOCATE_SEND_PACKET_FUNC; /** * Sends the packet and releases internal buffer. WintunSendPacket is thread-safe, but the WintunAllocateSendPacket @@ -311,7 +338,8 @@ typedef _Return_type_success_(return != NULL) _Ret_bytecount_(PacketSize) BYTE * * * @param Packet Packet obtained with WintunAllocateSendPacket */ -typedef void(WINAPI *WINTUN_SEND_PACKET_FUNC)(_In_ WINTUN_SESSION_HANDLE Session, _In_ const BYTE *Packet); +typedef VOID(WINAPI WINTUN_SEND_PACKET_FUNC_IMPL)(_In_ WINTUN_SESSION_HANDLE Session, _In_ const BYTE *Packet); +typedef WINTUN_SEND_PACKET_FUNC_IMPL *WINTUN_SEND_PACKET_FUNC; #ifdef __cplusplus } |