From ac6db7788a8dfd6e7658427be6d034cadb50081c Mon Sep 17 00:00:00 2001 From: Simon Rozman Date: Thu, 15 Oct 2020 12:52:01 +0200 Subject: api: move documentation to .h and discontinue on static functions While Doxygen correctly locates the function documentation when it is written directly preceding the function body, Microsoft Visual Studio IDE does not. The former requires the documentation to precede the function declaration. Signed-off-by: Simon Rozman --- api/adapter.c | 278 --------------------------------------------------------- api/adapter.h | 141 +++++++++++++++++++++++++++++ api/api.c | 13 --- api/api.h | 13 +++ api/driver.c | 89 +----------------- api/driver.h | 38 +++++++- api/registry.c | 120 ------------------------- api/registry.h | 102 +++++++++++++++++++++ api/resource.c | 22 ----- api/resource.h | 22 +++++ 10 files changed, 315 insertions(+), 523 deletions(-) diff --git a/api/adapter.c b/api/adapter.c index c7ac205..b9d131c 100644 --- a/api/adapter.c +++ b/api/adapter.c @@ -10,23 +10,6 @@ static _locale_t Locale; -/** - * Retrieves driver information detail for a device information set or a particular device information element in the - * device information set. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device for which to retrieve driver information. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @param DrvInfoData A pointer to a structure that specifies the driver information element that represents the - * driver for which to retrieve details. - * - * @param DrvInfoDetailData A pointer to a structure that receives detailed information about the specified driver. - * Must be released with HeapFree(GetProcessHeap(), 0, *DrvInfoDetailData) after use. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS AdapterGetDrvInfoDetail( _In_ HDEVINFO DevInfo, @@ -51,27 +34,6 @@ AdapterGetDrvInfoDetail( } } -/** - * Retrieves a specified Plug and Play device property. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device for which to open a registry key. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @param Property The property to be retrieved. One of the SPDRP_* constants. - * - * @param ValueType A pointer to a variable that receives the data type of the property that is being retrieved. - * This is one of the standard registry data types. - * - * @param Buf A pointer to a buffer that receives the property that is being retrieved. Must be released with - * HeapFree(GetProcessHeap(), 0, *Buf) after use. - * - * @param BufLen On input, a hint of expected registry value size in bytes; on output, actual registry value size - * in bytes. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS GetDeviceRegistryProperty( _In_ HDEVINFO DevInfo, @@ -96,21 +58,6 @@ GetDeviceRegistryProperty( } } -/** - * Retrieves a specified Plug and Play device property string. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device for which to open a registry key. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @param Property The property to be retrieved. One of the SPDRP_* constants. - * - * @param Buf A pointer to a string that receives the string that is being retrieved. Must be released with - * HeapFree(GetProcessHeap(), 0, *Buf) after use. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS GetDeviceRegistryString( _In_ HDEVINFO DevInfo, @@ -138,21 +85,6 @@ GetDeviceRegistryString( } } -/** - * Retrieves a specified Plug and Play device property multi-string. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device for which to open a registry key. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @param Property The property to be retrieved. One of the SPDRP_* constants. - * - * @param Buf A pointer to a multi-string that receives the string that is being retrieved. Must be released - * with HeapFree(GetProcessHeap(), 0, *Buf) after use. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS GetDeviceRegistryMultiString( _In_ HDEVINFO DevInfo, @@ -180,16 +112,6 @@ GetDeviceRegistryMultiString( } } -/** - * Tests if any of device compatible hardware IDs match ours. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS IsOurAdapter(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData, _Out_ BOOL *IsOur) { @@ -201,15 +123,6 @@ IsOurAdapter(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData, _Out_ BOO return ERROR_SUCCESS; } -/** - * Returns a handle to the adapter device object. - * - * @param InstanceId Adapter device instance ID. - * - * @param Handle Pointer to receive the adapter device object handle. Must be released with CloseHandle. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS GetDeviceObject(_In_opt_z_ const WCHAR *InstanceId, _Out_ HANDLE *Handle) { @@ -253,16 +166,6 @@ cleanupBuf: #define TUN_IOCTL_FORCE_CLOSE_HANDLES CTL_CODE(51820U, 0x971U, METHOD_NEITHER, FILE_READ_DATA | FILE_WRITE_DATA) -/** - * Closes all client handles to the Wintun adapter. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS ForceCloseWintunAdapterHandle(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData) { @@ -296,15 +199,6 @@ out: return Result; } -/** - * Disables all Wintun adapters. - * - * @param DevInfo A handle to the device information set. - * - * @param DisabledAdapters Output list of disabled adapters. The adapters disabled are inserted in the list head. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS AdapterDisableAllOurs(_In_ HDEVINFO DevInfo, _Inout_ SP_DEVINFO_DATA_LIST **DisabledAdapters) { @@ -362,15 +256,6 @@ AdapterDisableAllOurs(_In_ HDEVINFO DevInfo, _Inout_ SP_DEVINFO_DATA_LIST **Disa return Result; } -/** - * Enables all adapters. - * - * @param DevInfo A handle to the device information set. - * - * @param AdaptersToEnable Input list of adapters to enable. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS AdapterEnableAll(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA_LIST *AdaptersToEnable) { @@ -392,11 +277,6 @@ AdapterEnableAll(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA_LIST *AdaptersToEna return Result; } -/** - * Removes all Wintun adapters. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS AdapterDeleteAllOurs() { @@ -450,9 +330,6 @@ AdapterCleanup() _free_locale(Locale); } -/** - * Checks device install parameters if a system reboot is required. - */ static BOOL CheckReboot(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData) { @@ -465,9 +342,6 @@ CheckReboot(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData) return (DevInstallParams.Flags & (DI_NEEDREBOOT | DI_NEEDRESTART)) != 0; } -/** - * Sets device install parameters for a quiet installation. - */ static WINTUN_STATUS SetQuietInstall(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData) { @@ -480,18 +354,6 @@ SetQuietInstall(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData) return ERROR_SUCCESS; } -/** - * Returns adapter GUID associated with device. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device for which to open a registry key. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @param CfgInstanceID Pointer to a GUID to receive the adapter GUID. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS GetNetCfgInstanceId(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData, _Out_ GUID *CfgInstanceID) { @@ -518,20 +380,6 @@ cleanupKey: return Result; } -/** - * Returns device info list handle and adapter device info data. - * - * @param CfgInstanceID The adapter GUID. - * - * @param DevInfo A pointer to receive the handle of the device information set that contains a device information - * element that represents the device. Must be released with SetupDiDestroyDeviceInfoList(*DevInfo) - * after use. - * - * @param DevInfoData A pointer to a structure that receives specification of the device information element in - * DevInfo. - * - * @return ERROR_SUCCESS on success; ERROR_FILE_NOT_FOUND if the device is not found; Win32 error code otherwise. - */ static WINTUN_STATUS GetDevInfoData(_In_ const GUID *CfgInstanceID, _Out_ HDEVINFO *DevInfo, _Out_ SP_DEVINFO_DATA *DevInfoData) { @@ -556,9 +404,6 @@ GetDevInfoData(_In_ const GUID *CfgInstanceID, _Out_ HDEVINFO *DevInfo, _Out_ SP return ERROR_FILE_NOT_FOUND; } -/** - * Removes numbered suffix from adapter name. - */ static void RemoveNumberedSuffix(_In_z_ const WCHAR *Name, _Out_ WCHAR *Removed) { @@ -583,18 +428,12 @@ RemoveNumberedSuffix(_In_z_ const WCHAR *Name, _Out_ WCHAR *Removed) wmemcpy(Removed, Name, Len + 1); } -/** - * Returns pool-specific device type name. - */ static void GetPoolDeviceTypeName(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _Out_cap_c_(MAX_POOL_DEVICE_TYPE) WCHAR *Name) { _snwprintf_s(Name, MAX_POOL_DEVICE_TYPE, _TRUNCATE, L"%.*s Tunnel", MAX_POOL, Pool); } -/** - * Checks if SPDRP_DEVICEDESC or SPDRP_FRIENDLYNAME match device type name. - */ static WINTUN_STATUS IsPoolMember( _In_z_count_c_(MAX_POOL) const WCHAR *Pool, @@ -638,22 +477,6 @@ cleanupDeviceDesc: return Result; } -/** - * Creates a Wintun adapter descriptor and populates it from the device's registry key. - * - * @param DevInfo A handle to the device information set that contains a device information element that - * represents the device for which to open a registry key. - * - * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. - * - * @param Pool Name of the adapter pool. - * - * @param Adapter Pointer to a handle to receive the adapter descriptor. Must be released with - * HeapFree(GetProcessHeap(), 0, *Adapter). - * - * @return ERROR_SUCCESS on success; ERROR_INVALID_DATATYPE or ERROR_INVALID_DATA on any invalid registry values; Win32 - * error code otherwise. - */ static WINTUN_STATUS CreateAdapterData( _In_z_count_c_(MAX_POOL) const WCHAR *Pool, @@ -729,9 +552,6 @@ cleanupKey: return Result; } -/** - * Returns the device-level registry key path. - */ static void GetDeviceRegPath(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_REG_PATH) WCHAR *Path) { @@ -744,9 +564,6 @@ GetDeviceRegPath(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_REG_PATH) W Adapter->DevInstanceID); } -/** - * Returns the adapter-specific TCP/IP network registry key path. - */ static void GetTcpipAdapterRegPath(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_REG_PATH) WCHAR *Path) { @@ -760,9 +577,6 @@ GetTcpipAdapterRegPath(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_REG_P Guid); } -/** - * Returns the interface-specific TCP/IP network registry key path. - */ static WINTUN_STATUS GetTcpipInterfaceRegPath(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_REG_PATH) WCHAR *Path) { @@ -794,29 +608,12 @@ cleanupTcpipAdapterRegKey: return Result; } -/** - * Releases Wintun adapter resources. - * - * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter. - */ void WINAPI WintunFreeAdapter(_In_ WINTUN_ADAPTER *Adapter) { HeapFree(GetProcessHeap(), 0, 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 - */ WINTUN_STATUS WINAPI WintunGetAdapter( _In_z_count_c_(MAX_POOL) const WCHAR *Pool, @@ -904,9 +701,6 @@ cleanupMutex: return Result; } -/** - * Returns the name of the Wintun adapter. - */ WINTUN_STATUS WINAPI WintunGetAdapterName(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_ADAPTER_NAME) WCHAR *Name) { @@ -923,9 +717,6 @@ ConvertInterfaceAliasToGuid(_In_z_ const WCHAR *Name, _Out_ GUID *Guid) return ConvertInterfaceLuidToGuid(&Luid, Guid); } -/** - * Sets name of the Wintun adapter. - */ WINTUN_STATUS WINAPI WintunSetAdapterName(_In_ const WINTUN_ADAPTER *Adapter, _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name) { @@ -988,26 +779,12 @@ WintunSetAdapterName(_In_ const WINTUN_ADAPTER *Adapter, _In_z_count_c_(MAX_ADAP return Result; } -/** - * Returns the GUID of the adapter. - * - * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter - * - * @param Guid Pointer to GUID to receive adapter ID. - */ void WINAPI WintunGetAdapterGUID(_In_ const WINTUN_ADAPTER *Adapter, _Out_ GUID *Guid) { memcpy(Guid, &Adapter->CfgInstanceID, sizeof(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. - */ void WINAPI WintunGetAdapterLUID(_In_ const WINTUN_ADAPTER *Adapter, _Out_ LUID *Luid) { @@ -1015,24 +792,12 @@ WintunGetAdapterLUID(_In_ const WINTUN_ADAPTER *Adapter, _Out_ LUID *Luid) (((LONGLONG)Adapter->IfType & ((1 << 16) - 1)) << 48); } -/** - * 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. - */ WINTUN_STATUS WINAPI WintunGetAdapterDeviceObject(_In_ const WINTUN_ADAPTER *Adapter, _Out_ HANDLE *Handle) { return GetDeviceObject(Adapter->DevInstanceID, Handle); } -/** - * @return TRUE if DrvInfoData date and version is newer than supplied parameters. - */ static BOOL IsNewer(_In_ const SP_DRVINFO_DATA_W *DrvInfoData, _In_ const FILETIME *DriverDate, _In_ DWORDLONG DriverVersion) { @@ -1054,27 +819,6 @@ IsNewer(_In_ const SP_DRVINFO_DATA_W *DrvInfoData, _In_ const FILETIME *DriverDa return FALSE; } -/** - * 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. - */ WINTUN_STATUS WINAPI WintunCreateAdapter( _In_z_count_c_(MAX_POOL) const WCHAR *Pool, @@ -1347,16 +1091,6 @@ cleanupMutex: return Result; } -/** - * 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. - */ WINTUN_STATUS WINAPI WintunDeleteAdapter(_In_ const WINTUN_ADAPTER *Adapter, _Inout_ BOOL *RebootRequired) { @@ -1384,18 +1118,6 @@ WintunDeleteAdapter(_In_ const WINTUN_ADAPTER *Adapter, _Inout_ BOOL *RebootRequ return Result; } -/** - * 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. - */ WINTUN_STATUS WINAPI WintunEnumAdapters(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_ WINTUN_ENUM_FUNC Func, _In_ LPARAM Param) { diff --git a/api/adapter.h b/api/adapter.h index 5f38e46..c6c1901 100644 --- a/api/adapter.h +++ b/api/adapter.h @@ -18,6 +18,23 @@ typedef struct _SP_DEVINFO_DATA_LIST struct _SP_DEVINFO_DATA_LIST *Next; } SP_DEVINFO_DATA_LIST; +/** + * Retrieves driver information detail for a device information set or a particular device information element in the + * device information set. + * + * @param DevInfo A handle to the device information set that contains a device information element that + * represents the device for which to retrieve driver information. + * + * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo. + * + * @param DrvInfoData A pointer to a structure that specifies the driver information element that represents the + * driver for which to retrieve details. + * + * @param DrvInfoDetailData A pointer to a structure that receives detailed information about the specified driver. + * Must be released with HeapFree(GetProcessHeap(), 0, *DrvInfoDetailData) after use. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS AdapterGetDrvInfoDetail( _In_ HDEVINFO DevInfo, @@ -25,12 +42,35 @@ AdapterGetDrvInfoDetail( _In_ SP_DRVINFO_DATA_W *DrvInfoData, _Out_ SP_DRVINFO_DETAIL_DATA_W **DrvInfoDetailData); +/** + * Disables all Wintun adapters. + * + * @param DevInfo A handle to the device information set. + * + * @param DisabledAdapters Output list of disabled adapters. The adapters disabled are inserted in the list head. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS AdapterDisableAllOurs(_In_ HDEVINFO DevInfo, _Inout_ SP_DEVINFO_DATA_LIST **DisabledAdapters); +/** + * Enables all adapters. + * + * @param DevInfo A handle to the device information set. + * + * @param AdaptersToEnable Input list of adapters to enable. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS AdapterEnableAll(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA_LIST *AdaptersToEnable); +/** + * Removes all Wintun adapters. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS AdapterDeleteAllOurs(); @@ -49,30 +89,109 @@ typedef struct _WINTUN_ADAPTER WCHAR Pool[MAX_POOL]; } WINTUN_ADAPTER; +/** + * Releases Wintun adapter resources. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter. + */ void WINAPI WintunFreeAdapter(_In_ WINTUN_ADAPTER *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 + */ WINTUN_STATUS WINAPI WintunGetAdapter( _In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name, _Out_ WINTUN_ADAPTER **Adapter); +/** + * 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. + */ WINTUN_STATUS WINAPI WintunGetAdapterName(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_ADAPTER_NAME) WCHAR *Name); +/** + * 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. + */ WINTUN_STATUS WINAPI WintunSetAdapterName(_In_ const WINTUN_ADAPTER *Adapter, _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name); +/** + * Returns the GUID of the adapter. + * + * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter + * + * @param Guid Pointer to GUID to receive adapter ID. + */ void WINAPI WintunGetAdapterGUID(_In_ const WINTUN_ADAPTER *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. + */ void WINAPI WintunGetAdapterLUID(_In_ const WINTUN_ADAPTER *Adapter, _Out_ LUID *Luid); +/** + * 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. + */ WINTUN_STATUS WINAPI WintunGetAdapterDeviceObject(_In_ const WINTUN_ADAPTER *Adapter, _Out_ HANDLE *Handle); +/** + * 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. + */ WINTUN_STATUS WINAPI WintunCreateAdapter( _In_z_count_c_(MAX_POOL) const WCHAR *Pool, @@ -81,10 +200,32 @@ WintunCreateAdapter( _Out_ WINTUN_ADAPTER **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. + */ WINTUN_STATUS WINAPI WintunDeleteAdapter(_In_ const WINTUN_ADAPTER *Adapter, _Inout_ BOOL *RebootRequired); typedef BOOL(CALLBACK *WINTUN_ENUM_FUNC)(_In_ const WINTUN_ADAPTER *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. + */ WINTUN_STATUS WINAPI WintunEnumAdapters(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_ WINTUN_ENUM_FUNC Func, _In_ LPARAM Param); diff --git a/api/api.c b/api/api.c index 3b7e895..ff852a4 100644 --- a/api/api.c +++ b/api/api.c @@ -7,19 +7,6 @@ HINSTANCE ResourceModule; -/** - * 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. - */ WINTUN_STATUS WINAPI WintunGetVersion( _Out_ DWORD *DriverVersionMaj, diff --git a/api/api.h b/api/api.h index e6c6672..e3cc696 100644 --- a/api/api.h +++ b/api/api.h @@ -18,6 +18,19 @@ typedef _Return_type_success_(return == ERROR_SUCCESS) DWORD WINTUN_STATUS; extern HINSTANCE ResourceModule; +/** + * 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. + */ WINTUN_STATUS WINAPI WintunGetVersion( _Out_ DWORD *DriverVersionMaj, diff --git a/api/driver.c b/api/driver.c index edd144b..1742587 100644 --- a/api/driver.c +++ b/api/driver.c @@ -7,13 +7,6 @@ #pragma warning(disable : 4221) /* nonstandard: address of automatic in initializer */ -/** - * Tests if any of the hardware IDs match ours. - * - * @param Hwids Multi-string containing a list of hardware IDs. - * - * @return TRUE on match; FALSE otherwise. - */ BOOL DriverIsOurHardwareID(_In_z_ const WCHAR *Hwids) { @@ -23,13 +16,6 @@ DriverIsOurHardwareID(_In_z_ const WCHAR *Hwids) return FALSE; } -/** - * Tests if hardware ID or any of the compatible IDs match ours. - * - * @param DrvInfoDetailData Detailed information about a particular driver information structure. - * - * @return TRUE on match; FALSE otherwise. - */ BOOL DriverIsOurDrvInfoDetail(_In_ const SP_DRVINFO_DETAIL_DATA_W *DrvInfoDetailData) { @@ -51,11 +37,6 @@ DriverIsOurDrvInfoDetail(_In_ const SP_DRVINFO_DETAIL_DATA_W *DrvInfoDetailData) extern VOID NTAPI RtlGetNtVersionNumbers(_Out_opt_ DWORD *MajorVersion, _Out_opt_ DWORD *MinorVersion, _Out_opt_ DWORD *BuildNumber); -/** - * Queries driver availability and Windows requirement about driver signing model. - * - * @return non-zero when WHQL/Attestation-signed drivers are available and required; zero otherwise. - */ static BOOL HaveWHQL() { @@ -70,15 +51,6 @@ HaveWHQL() # endif } -/** - * Locates the white-space string span. - * - * \param Beg String start - * - * \param End String end (non-inclusive) - * - * \return First non-white-space character or string end. - */ static const CHAR * SkipWSpace(_In_ const CHAR *Beg, _In_ const CHAR *End) { @@ -87,15 +59,6 @@ SkipWSpace(_In_ const CHAR *Beg, _In_ const CHAR *End) return Beg; } -/** - * Locates the non-LF string span. - * - * \param Beg String start - * - * \param End String end (non-inclusive) - * - * \return First LF character or string end. - */ static const CHAR * SkipNonLF(_In_ const CHAR *Beg, _In_ const CHAR *End) { @@ -104,15 +67,6 @@ SkipNonLF(_In_ const CHAR *Beg, _In_ const CHAR *End) return Beg; } -/** - * Queries the version of the driver this wintun.dll is packing. - * - * DriverDate Pointer to a variable to receive the driver date. - * - * DriverVersion Pointer to a variable to receive the driver version. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS DriverGetVersion(_Out_ FILETIME *DriverDate, _Out_ DWORDLONG *DriverVersion) { @@ -210,13 +164,7 @@ DriverGetVersion(_Out_ FILETIME *DriverDate, _Out_ DWORDLONG *DriverVersion) return ERROR_FILE_NOT_FOUND; } -/** - * Checks if the Wintun driver is loaded. - * - * Note: This function does not log any errors, not to flood the log when called from the EnsureDriverUnloaded() loop. - * - * @return non-zero when loaded; zero when not loaded or error - use GetLastError(). - */ +/* This function does not log any errors, not to flood the log when called from the EnsureDriverUnloaded() loop. */ static BOOL IsDriverLoaded(VOID) { VOID *StackBuffer[0x80]; @@ -258,11 +206,6 @@ static BOOL IsDriverLoaded(VOID) return Found; } -/** - * Polls for 15 sec until the Wintun driver is unloaded. - * - * @return non-zero if the driver unloaded; zero on error or timeout - use GetLastError(). - */ static BOOL EnsureDriverUnloaded(VOID) { BOOL Loaded; @@ -271,14 +214,6 @@ static BOOL EnsureDriverUnloaded(VOID) return !Loaded; } -/** - * Installs code-signing certificate to the computer's Trusted Publishers certificate store. - * - * @param SignedResource ID of the RT_RCDATA resource containing the signed binary to extract the code-signing - * certificate from. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS InstallCertificate(_In_z_ const WCHAR *SignedResource) { @@ -347,13 +282,6 @@ cleanupQueriedStore: return Result; } -/** - * Installs Wintun driver to the Windows driver store and updates existing adapters to use it. - * - * @param UpdateExisting Set to non-zero when existing adapters should be upgraded to the newest driver. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS InstallDriver(_In_ BOOL UpdateExisting) { @@ -432,11 +360,6 @@ cleanupFree: return Result; } -/** - * Removes Wintun driver from the Windows driver store. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS RemoveDriver(VOID) { HDEVINFO DevInfo = SetupDiGetClassDevsW(&GUID_DEVCLASS_NET, NULL, NULL, 0); @@ -484,11 +407,6 @@ cleanupDeviceInfoSet: return Result; } -/** - * Installs or updates Wintun driver. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS DriverInstallOrUpdate(VOID) { HANDLE Heap = GetProcessHeap(); @@ -531,11 +449,6 @@ cleanupAdapters:; return Result; } -/** - * Uninstalls Wintun driver. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS DriverUninstall(VOID) { AdapterDeleteAllOurs(); diff --git a/api/driver.h b/api/driver.h index d7906b3..967d862 100644 --- a/api/driver.h +++ b/api/driver.h @@ -10,18 +10,52 @@ #define WINTUN_HWID L"Wintun" +/** + * Tests if any of the hardware IDs match ours. + * + * @param Hwids Multi-string containing a list of hardware IDs. + * + * @return TRUE on match; FALSE otherwise. + */ BOOL DriverIsOurHardwareID(_In_z_ const WCHAR *Hwids); +/** + * Tests if hardware ID or any of the compatible IDs match ours. + * + * @param DrvInfoDetailData Detailed information about a particular driver information structure. + * + * @return TRUE on match; FALSE otherwise. + */ BOOL DriverIsOurDrvInfoDetail(_In_ const SP_DRVINFO_DETAIL_DATA_W *DrvInfoDetailData); #if defined(HAVE_EV) || defined(HAVE_WHQL) -WINTUN_STATUS DriverGetVersion(_Out_ FILETIME *DriverDate, _Out_ DWORDLONG *DriverVersion); +/** + * Queries the version of the driver this wintun.dll is packing. + * + * DriverDate Pointer to a variable to receive the driver date. + * + * DriverVersion Pointer to a variable to receive the driver version. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ +WINTUN_STATUS +DriverGetVersion(_Out_ FILETIME *DriverDate, _Out_ DWORDLONG *DriverVersion); +/** + * Installs or updates Wintun driver. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS DriverInstallOrUpdate(VOID); +/** + * Uninstalls Wintun driver. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS DriverUninstall(VOID); -#endif \ No newline at end of file +#endif diff --git a/api/registry.c b/api/registry.c index e752469..a36b27e 100644 --- a/api/registry.c +++ b/api/registry.c @@ -57,21 +57,6 @@ OpenKeyWait(_In_ HKEY Key, _Inout_z_ WCHAR *Path, _In_ DWORD Access, _In_ ULONGL return Result; } -/** - * Opens the specified registry key. It waits for the registry key to become available. - * - * @param Key Handle of the parent registry key. Must be opened with notify access. - * - * @param Path Subpath of the registry key to open. - * - * @param Access A mask that specifies the desired access rights to the key to be opened. - * - * @param Timeout Timeout to wait for the value in milliseconds. - * - * @param KeyOut Pointer to a variable to receive the key handle. - * - * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; Win32 error code otherwise. - */ WINTUN_STATUS RegistryOpenKeyWait( _In_ HKEY Key, @@ -85,21 +70,6 @@ RegistryOpenKeyWait( return OpenKeyWait(Key, Buf, Access, GetTickCount64() + Timeout, KeyOut); } -/** - * Validates and/or sanitizes string value read from registry. - * - * @param Buf On input, it contains a pointer to pointer where the data is stored. The data must be allocated - * using HeapAlloc(GetProcessHeap(), 0). On output, it contains a pointer to pointer where the - * sanitized data is stored. It must be released with HeapFree(GetProcessHeap(), 0, *Buf) after - * use. - * - * @param Len Length of data string in wide characters. - * - * @param ValueType Type of data. Must be either REG_SZ or REG_EXPAND_SZ. REG_MULTI_SZ is treated like REG_SZ; only - * the first string of a multi-string is to be used. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS RegistryGetString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType) { @@ -150,20 +120,6 @@ RegistryGetString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType) } } -/** - * Validates and/or sanitizes multi-string value read from registry. - * - * @param Buf On input, it contains a pointer to pointer where the data is stored. The data must be allocated - * using HeapAlloc(GetProcessHeap(), 0). On output, it contains a pointer to pointer where the - * sanitized data is stored. It must be released with HeapFree(GetProcessHeap(), 0, *Buf) after - * use. - * - * @param Len Length of data string in wide characters. - * - * @param ValueType Type of data. Must be one of REG_MULTI_SZ, REG_SZ or REG_EXPAND_SZ. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS RegistryGetMultiString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType) { @@ -218,24 +174,6 @@ RegistryGetMultiString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType return ERROR_SUCCESS; } -/** - * Retrieves the type and data for the specified value name associated with an open registry key. - * - * @param Key Handle of the registry key to read from. Must be opened with read access. - * - * @param Name Name of the value to read. - * - * @param ValueType A pointer to a variable that receives a code indicating the type of data stored in the specified - * value. - * - * @param Buf Pointer to a pointer to retrieve registry value. The buffer must be released with - * HeapFree(GetProcessHeap(), 0, *Buf) after use. - * - * @param BufLen On input, a hint of expected registry value size in bytes; on output, actual registry value size - * in bytes. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ static WINTUN_STATUS RegistryQuery( _In_ HKEY Key, @@ -259,21 +197,6 @@ RegistryQuery( } } -/** - * Reads string value from registry key. - * - * @param Key Handle of the registry key to read from. Must be opened with read access. - * - * @param Name Name of the value to read. - * - * @param Value Pointer to string to retrieve registry value. If the value type is REG_EXPAND_SZ the value is - * expanded using ExpandEnvironmentStrings(). If the value type is REG_MULTI_SZ, only the first - * string from the multi-string is returned. The string must be released with - * HeapFree(GetProcessHeap(), 0, Value) after use. - * - * @return ERROR_SUCCESS on success; ERROR_INVALID_DATATYPE when the registry value is not a string; Win32 error code - * otherwise. - */ WINTUN_STATUS RegistryQueryString(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ WCHAR **Value) { @@ -297,23 +220,6 @@ RegistryQueryString(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ WCHAR **V } } -/** - * Reads string value from registry key. It waits for the registry value to become available. - * - * @param Key Handle of the registry key to read from. Must be opened with read and notify access. - * - * @param Name Name of the value to read. - * - * @param Timeout Timeout to wait for the value in milliseconds. - * - * @param Value Pointer to string to retrieve registry value. If the value type is REG_EXPAND_SZ the value is - * expanded using ExpandEnvironmentStrings(). If the value type is REG_MULTI_SZ, only the first - * string from the multi-string is returned. The string must be released with - * HeapFree(GetProcessHeap(), 0, Value) after use. - * - * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; ERROR_INVALID_DATATYPE when the registry value is not a - * string; Win32 error code otherwise. - */ WINTUN_STATUS RegistryQueryStringWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ WCHAR **Value) { @@ -346,18 +252,6 @@ RegistryQueryStringWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD return Result; } -/** - * Reads a 32-bit DWORD value from registry key. - * - * @param Key Handle of the registry key to read from. Must be opened with read access. - * - * @param Name Name of the value to read. - * - * @param Value Pointer to DWORD to retrieve registry value. - * - * @return ERROR_SUCCESS on success; ERROR_INVALID_DATATYPE when registry value exist but not REG_DWORD type; - * ERROR_INVALID_DATA when registry value size is not 4 bytes; Win32 error code otherwise. - */ WINTUN_STATUS RegistryQueryDWORD(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ DWORD *Value) { @@ -378,20 +272,6 @@ RegistryQueryDWORD(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ DWORD *Val return ERROR_SUCCESS; } -/** - * Reads a 32-bit DWORD value from registry key. It waits for the registry value to become available. - * - * @param Key Handle of the registry key to read from. Must be opened with read access. - * - * @param Name Name of the value to read. - * - * @param Timeout Timeout to wait for the value in milliseconds. - * - * @param Value Pointer to DWORD to retrieve registry value. - * - * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; ERROR_INVALID_DATATYPE when registry value exist but not - * REG_DWORD type; ERROR_INVALID_DATA when registry value size is not 4 bytes; Win32 error code otherwise. - */ WINTUN_STATUS RegistryQueryDWORDWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ DWORD *Value) { diff --git a/api/registry.h b/api/registry.h index 222694a..3d073f9 100644 --- a/api/registry.h +++ b/api/registry.h @@ -11,6 +11,21 @@ 256 /* Maximum registry path length \ https://support.microsoft.com/en-us/help/256986/windows-registry-information-for-advanced-users */ +/** + * Opens the specified registry key. It waits for the registry key to become available. + * + * @param Key Handle of the parent registry key. Must be opened with notify access. + * + * @param Path Subpath of the registry key to open. + * + * @param Access A mask that specifies the desired access rights to the key to be opened. + * + * @param Timeout Timeout to wait for the value in milliseconds. + * + * @param KeyOut Pointer to a variable to receive the key handle. + * + * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; Win32 error code otherwise. + */ WINTUN_STATUS RegistryOpenKeyWait( _In_ HKEY Key, @@ -19,20 +34,107 @@ RegistryOpenKeyWait( _In_ DWORD Timeout, _Out_ HKEY *KeyOut); +/** + * Validates and/or sanitizes string value read from registry. + * + * @param Buf On input, it contains a pointer to pointer where the data is stored. The data must be allocated + * using HeapAlloc(GetProcessHeap(), 0). On output, it contains a pointer to pointer where the + * sanitized data is stored. It must be released with HeapFree(GetProcessHeap(), 0, *Buf) after + * use. + * + * @param Len Length of data string in wide characters. + * + * @param ValueType Type of data. Must be either REG_SZ or REG_EXPAND_SZ. REG_MULTI_SZ is treated like REG_SZ; only + * the first string of a multi-string is to be used. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS RegistryGetString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType); +/** + * Validates and/or sanitizes multi-string value read from registry. + * + * @param Buf On input, it contains a pointer to pointer where the data is stored. The data must be allocated + * using HeapAlloc(GetProcessHeap(), 0). On output, it contains a pointer to pointer where the + * sanitized data is stored. It must be released with HeapFree(GetProcessHeap(), 0, *Buf) after + * use. + * + * @param Len Length of data string in wide characters. + * + * @param ValueType Type of data. Must be one of REG_MULTI_SZ, REG_SZ or REG_EXPAND_SZ. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS RegistryGetMultiString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType); +/** + * Reads string value from registry key. + * + * @param Key Handle of the registry key to read from. Must be opened with read access. + * + * @param Name Name of the value to read. + * + * @param Value Pointer to string to retrieve registry value. If the value type is REG_EXPAND_SZ the value is + * expanded using ExpandEnvironmentStrings(). If the value type is REG_MULTI_SZ, only the first + * string from the multi-string is returned. The string must be released with + * HeapFree(GetProcessHeap(), 0, Value) after use. + * + * @return ERROR_SUCCESS on success; ERROR_INVALID_DATATYPE when the registry value is not a string; Win32 error code + * otherwise. + */ WINTUN_STATUS RegistryQueryString(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ WCHAR **Value); +/** + * Reads string value from registry key. It waits for the registry value to become available. + * + * @param Key Handle of the registry key to read from. Must be opened with read and notify access. + * + * @param Name Name of the value to read. + * + * @param Timeout Timeout to wait for the value in milliseconds. + * + * @param Value Pointer to string to retrieve registry value. If the value type is REG_EXPAND_SZ the value is + * expanded using ExpandEnvironmentStrings(). If the value type is REG_MULTI_SZ, only the first + * string from the multi-string is returned. The string must be released with + * HeapFree(GetProcessHeap(), 0, Value) after use. + * + * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; ERROR_INVALID_DATATYPE when the registry value is not a + * string; Win32 error code otherwise. + */ WINTUN_STATUS RegistryQueryStringWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ WCHAR **Value); +/** + * Reads a 32-bit DWORD value from registry key. + * + * @param Key Handle of the registry key to read from. Must be opened with read access. + * + * @param Name Name of the value to read. + * + * @param Value Pointer to DWORD to retrieve registry value. + * + * @return ERROR_SUCCESS on success; ERROR_INVALID_DATATYPE when registry value exist but not REG_DWORD type; + * ERROR_INVALID_DATA when registry value size is not 4 bytes; Win32 error code otherwise. + */ WINTUN_STATUS RegistryQueryDWORD(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ DWORD *Value); +/** + * Reads a 32-bit DWORD value from registry key. It waits for the registry value to become available. + * + * @param Key Handle of the registry key to read from. Must be opened with read access. + * + * @param Name Name of the value to read. + * + * @param Timeout Timeout to wait for the value in milliseconds. + * + * @param Value Pointer to DWORD to retrieve registry value. + * + * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; ERROR_INVALID_DATATYPE when registry value exist but not + * REG_DWORD type; ERROR_INVALID_DATA when registry value size is not 4 bytes; Win32 error code otherwise. + */ WINTUN_STATUS RegistryQueryDWORDWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ DWORD *Value); diff --git a/api/resource.c b/api/resource.c index e2e5174..82f0d13 100644 --- a/api/resource.c +++ b/api/resource.c @@ -5,17 +5,6 @@ #include "pch.h" -/** - * Locates RT_RCDATA resource memory address and size. - * - * ResourceName Name of the RT_RCDATA resource. Use MAKEINTRESOURCEW to locate resource by ID. - * - * Address Pointer to a pointer variable to receive resource address. - * - * Size Pointer to a variable to receive resource size. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS ResourceGetAddress(_In_z_ const WCHAR *ResourceName, _Out_ const VOID **Address, _Out_ DWORD *Size) { @@ -37,17 +26,6 @@ ResourceGetAddress(_In_z_ const WCHAR *ResourceName, _Out_ const VOID **Address, return ERROR_SUCCESS; } -/** - * Copies resource to a file. - * - * DestinationPath File path - * - * SecurityAttributes File security attributes. May be NULL for detault. - * - * ResourceName Name of the RT_RCDATA resource. Use MAKEINTRESOURCEW to locate resource by ID. - * - * @return ERROR_SUCCESS on success; Win32 error code otherwise. - */ WINTUN_STATUS ResourceCopyToFile( _In_z_ const WCHAR *DestinationPath, diff --git a/api/resource.h b/api/resource.h index 2ee2547..5021490 100644 --- a/api/resource.h +++ b/api/resource.h @@ -8,9 +8,31 @@ #include "api.h" #include +/** + * Locates RT_RCDATA resource memory address and size. + * + * ResourceName Name of the RT_RCDATA resource. Use MAKEINTRESOURCEW to locate resource by ID. + * + * Address Pointer to a pointer variable to receive resource address. + * + * Size Pointer to a variable to receive resource size. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS ResourceGetAddress(_In_z_ const WCHAR *ResourceName, _Out_ const VOID **Address, _Out_ DWORD *Size); +/** + * Copies resource to a file. + * + * DestinationPath File path + * + * SecurityAttributes File security attributes. May be NULL for detault. + * + * ResourceName Name of the RT_RCDATA resource. Use MAKEINTRESOURCEW to locate resource by ID. + * + * @return ERROR_SUCCESS on success; Win32 error code otherwise. + */ WINTUN_STATUS ResourceCopyToFile( _In_z_ const WCHAR *DestinationPath, -- cgit v1.2.3-59-g8ed1b