Hesham/wintun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

api: update documentation

Browse Source 
Signed-off-by: Simon Rozman <simon@rozman.si>
This commit is contained in:
Simon Rozman 2020-07-24 08:29:55 +02:00 committed by Jason A. Donenfeld
parent 355ce73841
commit 640605a8d9
3 changed files with 106 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
api/api.c
View File

@ -9,6 +9,16 @@ HINSTANCE ResourceModule;
/** /**
* Returns the version of the Wintun driver and NDIS system currently loaded. * 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 WINTUN_STATUS WINAPI
WintunGetVersion( WintunGetVersion(

94
api/devmgmt.c
View File

@ -21,21 +21,20 @@ const static GUID ADAPTER_NET_GUID = { 0xcac88484L,
* @param DevInfo A handle to the device information set that contains a device information element that * @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. * represents the device for which to open a registry key.
* *
* @param DevInfoData A pointer to a structure that specifies the device information element in DeviceInfoSet. * @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 Property The property to be retrieved. One of the SPDRP_* constants.
* *
* @param PropertyRegDataType A pointer to a variable that receives the data type of the property that is being * @param ValueType A pointer to a variable that receives the data type of the property that is being retrieved.
* retrieved. This is one of the standard registry data types. This parameter is optional * This is one of the standard registry data types.
* and can be NULL.
* *
* @param PropertyBuffer A pointer to a buffer that receives the property that is being retrieved. Must be * @param Buf A pointer to a buffer that receives the property that is being retrieved. Must be released with
* released with HeapFree(GetProcessHeap(), 0, Value) after use. * HeapFree(GetProcessHeap(), 0, *Buf) after use.
* *
* @param PropertySize A pointer to a variable of type DWORD that receives the property size, in bytes, of the * @param BufLen On input, a hint of expected registry value size in bytes; on output, actual registry value size
* PropertyBuffer buffer. This parameter is optional and can be NULL. * in bytes.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
GetDeviceRegistryProperty( GetDeviceRegistryProperty(
@ -67,14 +66,14 @@ GetDeviceRegistryProperty(
* @param DevInfo A handle to the device information set that contains a device information element that * @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. * represents the device for which to open a registry key.
* *
* @param DevInfoData A pointer to a structure that specifies the device information element in DeviceInfoSet. * @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 Property The property to be retrieved. One of the SPDRP_* constants.
* *
* @param PropertyBuffer A pointer to a string that receives the string that is being retrieved. Must be * @param Buf A pointer to a string that receives the string that is being retrieved. Must be released with
* released with HeapFree(GetProcessHeap(), 0, Value) after use. * HeapFree(GetProcessHeap(), 0, *Buf) after use.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
GetDeviceRegistryString( GetDeviceRegistryString(
@ -108,14 +107,14 @@ GetDeviceRegistryString(
* @param DevInfo A handle to the device information set that contains a device information element that * @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. * represents the device for which to open a registry key.
* *
* @param DevInfoData A pointer to a structure that specifies the device information element in DeviceInfoSet. * @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 Property The property to be retrieved. One of the SPDRP_* constants.
* *
* @param PropertyBuffer A pointer to a multi-string that receives the string that is being retrieved. Must be * @param Buf A pointer to a multi-string that receives the string that is being retrieved. Must be released
* released with HeapFree(GetProcessHeap(), 0, Value) after use. * with HeapFree(GetProcessHeap(), 0, *Buf) after use.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
GetDeviceRegistryMultiString( GetDeviceRegistryMultiString(
@ -150,15 +149,15 @@ GetDeviceRegistryMultiString(
* @param DevInfo A handle to the device information set that contains a device information element that * @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. * represents the device for which to open a registry key.
* *
* @param DevInfoData A pointer to a structure that specifies the device information element in DeviceInfoSet. * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo.
* *
* @param DriverData A pointer to a structure that specifies the driver information element that represents the * @param DriverData A pointer to a structure that specifies the driver information element that represents the
* driver for which to retrieve details. * driver for which to retrieve details.
* *
* @param DriverDetailData A pointer to a structure that receives detailed information about the specified driver. * @param DriverDetailData A pointer to a structure that receives detailed information about the specified driver.
* Must be released with HeapFree(GetProcessHeap(), 0, Value) after use. * Must be released with HeapFree(GetProcessHeap(), 0, *DriverDetailData) after use.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
GetDriverInfoDetail( GetDriverInfoDetail(
@ -187,7 +186,7 @@ GetDriverInfoDetail(
/** /**
* Tests if any of the hardware IDs match ours. * Tests if any of the hardware IDs match ours.
* *
* @param Hwids Multi-string containing a list of hardware IDs * @param Hwids Multi-string containing a list of hardware IDs.
* *
* @return TRUE on match; FALSE otherwise. * @return TRUE on match; FALSE otherwise.
*/ */
@ -201,7 +200,7 @@ IsOurHardwareID(_In_z_ WCHAR *Hwids)
} }
/** /**
* Check if the device is using Wintun driver. * Checks if the device is using Wintun driver.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
IsUsingOurDriver(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData, _Out_ BOOL *IsOurDriver) IsUsingOurDriver(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData, _Out_ BOOL *IsOurDriver)
@ -269,11 +268,11 @@ SetQuietInstall(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData)
* @param DevInfo A handle to the device information set that contains a device information element that * @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. * represents the device for which to open a registry key.
* *
* @param DevInfoData A pointer to a structure that specifies the device information element in DeviceInfoSet. * @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. * @param CfgInstanceID Pointer to a GUID to receive the adapter GUID.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
GetNetCfgInstanceId(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData, _Out_ GUID *CfgInstanceID) GetNetCfgInstanceId(_In_ HDEVINFO DevInfo, _In_ SP_DEVINFO_DATA *DevInfoData, _Out_ GUID *CfgInstanceID)
@ -295,16 +294,16 @@ cleanupKey:
/** /**
* Returns device info list handle and adapter device info data. * Returns device info list handle and adapter device info data.
* *
* @param CfgInstanceID The adapter GUID * @param CfgInstanceID The adapter GUID.
* *
* @param DevInfo A pointer to receive the handle of the device information set that contains a device information * @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) * element that represents the device. Must be released with SetupDiDestroyDeviceInfoList(*DevInfo)
* after use. * after use.
* *
* @param DevInfoData A pointer to a structure that receives specification of the device information element in * @param DevInfoData A pointer to a structure that receives specification of the device information element in
* DeviceInfoSet. * DevInfo.
* *
* @return ERROR_SUCCESS on success; ERROR_FILE_NOT_FOUND if the device is not found; Win32 error code otherwise * @return ERROR_SUCCESS on success; ERROR_FILE_NOT_FOUND if the device is not found; Win32 error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
GetDevInfoData(_In_ const GUID *CfgInstanceID, _Out_ HDEVINFO *DevInfo, _Out_ SP_DEVINFO_DATA *DevInfoData) GetDevInfoData(_In_ const GUID *CfgInstanceID, _Out_ HDEVINFO *DevInfo, _Out_ SP_DEVINFO_DATA *DevInfoData)
@ -412,14 +411,15 @@ cleanupDeviceDesc:
* @param DevInfo A handle to the device information set that contains a device information element that * @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. * represents the device for which to open a registry key.
* *
* @param DevInfoData A pointer to a structure that specifies the device information element in DeviceInfoSet. * @param DevInfoData A pointer to a structure that specifies the device information element in DevInfo.
* *
* @param Pool Name of the adapter pool * @param Pool Name of the adapter pool.
* *
* @param Adapter Pointer to a handle to receive the adapter descriptor. Must be released with * @param Adapter Pointer to a handle to receive the adapter descriptor. Must be released with
* HeapFree(GetProcessHeap(), 0, *Adapter). * HeapFree(GetProcessHeap(), 0, *Adapter).
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; ERROR_INVALID_DATATYPE or ERROR_INVALID_DATA on any invalid registry values; Win32
* error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
CreateAdapterData( CreateAdapterData(
@ -549,7 +549,7 @@ cleanupTcpipAdapterRegKey:
/** /**
* Releases Wintun adapter resources. * Releases Wintun adapter resources.
* *
* @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
*/ */
void WINAPI void WINAPI
WintunFreeAdapter(_In_ WINTUN_ADAPTER *Adapter) WintunFreeAdapter(_In_ WINTUN_ADAPTER *Adapter)
@ -560,16 +560,14 @@ WintunFreeAdapter(_In_ WINTUN_ADAPTER *Adapter)
/** /**
* Finds a Wintun adapter by its name. * Finds a Wintun adapter by its name.
* *
* @param Pool Name of the adapter pool * @param Pool Name of the adapter pool.
* *
* @param Name Adapter name * @param Name Adapter name.
* *
* @param Adapter Pointer to a handle to receive the adapter handle. Must be released with * @param Adapter Pointer to a handle to receive the adapter handle. Must be released with WintunFreeAdapter.
* WintunFreeAdapter.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise; * @return ERROR_SUCCESS on success; ERROR_FILE_NOT_FOUND if adapter with given name is not found; ERROR_ALREADY_EXISTS
* ERROR_FILE_NOT_FOUND if adapter with given name is not found; * if adapter is found but not a Wintun-class or not a member of the pool; Win32 error code otherwise
* ERROR_ALREADY_EXISTS if adapter is found but not a Wintun-class or not a member of the pool
*/ */
WINTUN_STATUS WINAPI WINTUN_STATUS WINAPI
WintunGetAdapter(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_z_ const WCHAR *Name, _Out_ WINTUN_ADAPTER **Adapter) WintunGetAdapter(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_z_ const WCHAR *Name, _Out_ WINTUN_ADAPTER **Adapter)
@ -769,11 +767,11 @@ WintunGetAdapterLUID(_In_ const WINTUN_ADAPTER *Adapter, _Out_ LUID *Luid)
/** /**
* Returns a handle to the adapter device object. * Returns a handle to the adapter device object.
* *
* @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter * @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
* *
* @param Handle Pointer to receive the adapter device object handle. Must be released with CloseHandle. * @param Handle Pointer to receive the adapter device object handle. Must be released with CloseHandle.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINAPI WINTUN_STATUS WINAPI
WintunGetAdapterDeviceObject(_In_ const WINTUN_ADAPTER *Adapter, _Out_ HANDLE *Handle) WintunGetAdapterDeviceObject(_In_ const WINTUN_ADAPTER *Adapter, _Out_ HANDLE *Handle)
@ -840,9 +838,9 @@ IsNewer(_In_ const SP_DRVINFO_DATA_W *DriverData, _In_ const FILETIME *DriverDat
/** /**
* Creates a Wintun adapter. * Creates a Wintun adapter.
* *
* @param Pool Name of the adapter pool * @param Pool Name of the adapter pool.
* *
* @param Name The requested name of the adapter * @param Name The requested name of the adapter.
* *
* @param RequestedGUID The GUID of the created network adapter, which then influences NLA generation * @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 * deterministically. If it is set to NULL, the GUID is chosen by the system at random, and hence
@ -856,7 +854,7 @@ IsNewer(_In_ const SP_DRVINFO_DATA_W *DriverData, _In_ const FILETIME *DriverDat
* @param RebootRequired Pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot. Must be * @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. * initialised to FALSE manually before this function is called.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINAPI WINTUN_STATUS WINAPI
WintunCreateAdapter( WintunCreateAdapter(
@ -1105,12 +1103,12 @@ cleanupMutex:
/** /**
* Deletes a Wintun adapter. * Deletes a Wintun adapter.
* *
* @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter * @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 * @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. * initialised to FALSE manually before this function is called.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise. This function succeeds if the adapter was not found. * @return ERROR_SUCCESS on success or the adapter was not found; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINAPI WINTUN_STATUS WINAPI
WintunDeleteAdapter(_In_ const WINTUN_ADAPTER *Adapter, _Inout_ BOOL *RebootRequired) WintunDeleteAdapter(_In_ const WINTUN_ADAPTER *Adapter, _Inout_ BOOL *RebootRequired)
@ -1142,14 +1140,14 @@ cleanupDevInfo:
/** /**
* Enumerates all Wintun adapters. * Enumerates all Wintun adapters.
* *
* @param Pool Name of the adapter pool * @param Pool Name of the adapter pool.
* *
* @param Func Callback function. To continue enumeration, the callback function must return TRUE; to stop * @param Func Callback function. To continue enumeration, the callback function must return TRUE; to stop
* enumeration, it must return FALSE. * enumeration, it must return FALSE.
* *
* @param Param An application-defined value to be passed to the callback function * @param Param An application-defined value to be passed to the callback function.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINAPI WINTUN_STATUS WINAPI
WintunEnumAdapters(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_ WINTUN_ENUMPROC Func, _In_ LPARAM Param) WintunEnumAdapters(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_ WINTUN_ENUMPROC Func, _In_ LPARAM Param)

101
api/registry.c
View File

@ -53,15 +53,15 @@ OpenKeyWait(_In_ HKEY Key, _Inout_z_ WCHAR *Path, _In_ DWORD Access, _In_ ULONGL
* *
* @param Key Handle of the parent registry key. Must be opened with notify access. * @param Key Handle of the parent registry key. Must be opened with notify access.
* *
* @param Path Subpath of the registry key to open * @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 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 Timeout Timeout to wait for the value in milliseconds.
* *
* @param KeyOut Pointer to a variable to receive the key handle * @param KeyOut Pointer to a variable to receive the key handle.
* *
* @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; error code otherwise * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINTUN_STATUS
RegistryOpenKeyWait( RegistryOpenKeyWait(
@ -88,19 +88,19 @@ RegistryWaitForKey(_In_ HKEY Key, _In_z_count_c_(MAX_REG_PATH) const WCHAR *Path
} }
/** /**
* Validate and/or sanitize string value read from registry. * Validates and/or sanitizes string value read from registry.
* *
* @param Buf On input, it contains pointer to pointer where the data is stored. The data must be * @param Buf On input, it contains a pointer to pointer where the data is stored. The data must be allocated
* allocated using HeapAlloc(GetProcessHeap(), 0). * using HeapAlloc(GetProcessHeap(), 0). On output, it contains a pointer to pointer where the
* On output, it contains pointer to pointer where the sanitized data is stored. It must be * sanitized data is stored. It must be released with HeapFree(GetProcessHeap(), 0, *Buf) after
* released with HeapFree(GetProcessHeap(), 0, *Buf) after use. * use.
* *
* @param Len Length of data string in wide characters * @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 * @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. * the first string of a multi-string is to be used.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINTUN_STATUS
RegistryGetString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType) RegistryGetString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType)
@ -153,18 +153,18 @@ RegistryGetString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType)
} }
/** /**
* Validate and/or sanitize multi-string value read from registry. * Validates and/or sanitizes multi-string value read from registry.
* *
* @param Buf On input, it contains pointer to pointer where the data is stored. The data must be * @param Buf On input, it contains a pointer to pointer where the data is stored. The data must be allocated
* allocated using HeapAlloc(GetProcessHeap(), 0). * using HeapAlloc(GetProcessHeap(), 0). On output, it contains a pointer to pointer where the
* On output, it contains pointer to pointer where the sanitized data is stored. It must be * sanitized data is stored. It must be released with HeapFree(GetProcessHeap(), 0, *Buf) after
* released with HeapFree(GetProcessHeap(), 0, *Buf) after use. * use.
* *
* @param Len Length of data string in wide characters * @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. * @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 * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINTUN_STATUS
RegistryGetMultiString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType) RegistryGetMultiString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType)
@ -223,10 +223,9 @@ RegistryGetMultiString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType
/** /**
* Retrieves the type and data for the specified value name associated with an open registry key. * 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 * @param Key Handle of the registry key to read from. Must be opened with read access.
* access.
* *
* @param Name Name of the value to read * @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 * @param ValueType A pointer to a variable that receives a code indicating the type of data stored in the specified
* value. * value.
@ -237,7 +236,7 @@ RegistryGetMultiString(_Inout_ WCHAR **Buf, _In_ DWORD Len, _In_ DWORD ValueType
* @param BufLen On input, a hint of expected registry value size in bytes; on output, actual registry value size * @param BufLen On input, a hint of expected registry value size in bytes; on output, actual registry value size
* in bytes. * in bytes.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; Win32 error code otherwise.
*/ */
static WINTUN_STATUS static WINTUN_STATUS
RegistryQuery( RegistryQuery(
@ -265,17 +264,17 @@ RegistryQuery(
/** /**
* Reads string value from registry key. * Reads string value from registry key.
* *
* @param Key Handle of the registry key to read from. Must be opened with read * @param Key Handle of the registry key to read from. Must be opened with read access.
* access.
* *
* @param Name Name of the value to read * @param Name Name of the value to read.
* *
* @param Value Pointer to string to retrieve registry value. If the value type is * @param Value Pointer to string to retrieve registry value. If the value type is REG_EXPAND_SZ the value is
* REG_EXPAND_SZ the value is expanded using ExpandEnvironmentStrings(). If the value type is * expanded using ExpandEnvironmentStrings(). If the value type is REG_MULTI_SZ, only the first
* REG_MULTI_SZ, only the first string from the multi-string is returned. * string from the multi-string is returned. The string must be released with
* The string must be released with HeapFree(GetProcessHeap(), 0, Value) after use. * HeapFree(GetProcessHeap(), 0, Value) after use.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; ERROR_INVALID_DATATYPE when the registry value is not a string; Win32 error code
* otherwise.
*/ */
WINTUN_STATUS WINTUN_STATUS
RegistryQueryString(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ WCHAR **Value) RegistryQueryString(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ WCHAR **Value)
@ -302,19 +301,19 @@ 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. * 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 * @param Key Handle of the registry key to read from. Must be opened with read and notify access.
* access.
* *
* @param Name Name of the value to read * @param Name Name of the value to read.
* *
* @param Timeout Timeout to wait for the value in milliseconds * @param Timeout Timeout to wait for the value in milliseconds.
* *
* @param Value Pointer to string to retrieve registry value. If the value type is * @param Value Pointer to string to retrieve registry value. If the value type is REG_EXPAND_SZ the value is
* REG_EXPAND_SZ the value is expanded using ExpandEnvironmentStrings(). * expanded using ExpandEnvironmentStrings(). If the value type is REG_MULTI_SZ, only the first
* The string must be released with HeapFree(GetProcessHeap(), 0, Value) * string from the multi-string is returned. The string must be released with
* after use. * HeapFree(GetProcessHeap(), 0, Value) after use.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @return ERROR_SUCCESS on success; WAIT_TIMEOUT on timeout; ERROR_INVALID_DATATYPE when the registry value is a
* string; Win32 error code otherwise.
*/ */
WINTUN_STATUS WINTUN_STATUS
RegistryQueryStringWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ WCHAR **Value) RegistryQueryStringWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ WCHAR **Value)
@ -345,14 +344,14 @@ RegistryQueryStringWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD
/** /**
* Reads a 32-bit DWORD value from registry key. * Reads a 32-bit DWORD value from registry key.
* *
* @param Key Handle of the registry key to read from. Must be opened with read * @param Key Handle of the registry key to read from. Must be opened with read access.
* access.
* *
* @param Name Name of the value to read * @param Name Name of the value to read.
* *
* @param Value Pointer to DWORD to retrieve registry value * @param Value Pointer to DWORD to retrieve registry value.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @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 WINTUN_STATUS
RegistryQueryDWORD(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ DWORD *Value) RegistryQueryDWORD(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ DWORD *Value)
@ -371,16 +370,16 @@ RegistryQueryDWORD(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _Out_ DWORD *Val
/** /**
* Reads a 32-bit DWORD value from registry key. It waits for the registry value to become available. * 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 * @param Key Handle of the registry key to read from. Must be opened with read access.
* access.
* *
* @param Name Name of the value to read * @param Name Name of the value to read.
* *
* @param Timeout Timeout to wait for the value in milliseconds * @param Timeout Timeout to wait for the value in milliseconds.
* *
* @param Value Pointer to DWORD to retrieve registry value * @param Value Pointer to DWORD to retrieve registry value.
* *
* @return ERROR_SUCCESS on success; Win32 error code otherwise * @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 WINTUN_STATUS
RegistryQueryDWORDWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ DWORD *Value) RegistryQueryDWORDWait(_In_ HKEY Key, _In_opt_z_ const WCHAR *Name, _In_ DWORD Timeout, _Out_ DWORD *Value)